ecologylab.xml
Class FieldDescriptor

java.lang.Object
  ecologylab.generic.Debug
      ecologylab.xml.ElementState
          ecologylab.xml.FieldDescriptor

All Implemented Interfaces:

FieldTypes, XMLTranslationExceptionTypes

public class FieldDescriptor
extends ElementState
implements FieldTypes

Used to provide convenient access for setting and getting values, using the ecologylab.xml type system. Provides marshalling and unmarshalling from Strings.

Author:

andruid

Nested Class Summary

Nested classes/interfaces inherited from class ecologylab.xml.ElementState

ElementState.DeclarationStyle, ElementState.xml_attribute, ElementState.xml_bind_from, ElementState.xml_bind_to, ElementState.xml_class, ElementState.xml_classes, ElementState.xml_collection, ElementState.xml_format, ElementState.xml_leaf, ElementState.xml_map, ElementState.xml_nested, ElementState.xml_nowrap, ElementState.xml_other_tags, ElementState.xml_scope, ElementState.xml_tag, ElementState.xml_text

Field Summary

static java.lang.String	NULL
static java.lang.Class[]	SET_METHOD_ARG

Fields inherited from class ecologylab.xml.ElementState

CDATA, NORMAL, UTF16, UTF16_LE, UTF8

Fields inherited from interface ecologylab.xml.FieldTypes

ATTRIBUTE, AWFUL_OLD_NESTED_ELEMENT, BAD_FIELD, COLLECTION_ELEMENT, COLLECTION_SCALAR, IGNORED_ATTRIBUTE, IGNORED_ELEMENT, LEAF, MAP_ELEMENT, MAP_SCALAR, NAME_SPACE_ATTRIBUTE, NAME_SPACE_LEAF_NODE, NAME_SPACE_MASK, NAME_SPACE_NESTED_ELEMENT, NAMESPACE_IGNORED_ELEMENT, NAMESPACE_TRIAL_ELEMENT, NESTED_ELEMENT, PSEUDO_FIELD_DESCRIPTOR, ROOT, TEXT_ELEMENT, TEXT_NODE_VALUE, UNSET_TYPE, WRAPPER, XMLNS_ATTRIBUTE, XMLNS_IGNORED

Fields inherited from interface ecologylab.xml.XMLTranslationExceptionTypes

FILE_NOT_FOUND, IO_EXCEPTION, NULL_PURL, UNKNOWN

Constructor Summary

FieldDescriptor()
Default constructor only for use by translateFromXML().

FieldDescriptor(ClassDescriptor baseClassDescriptor)
Constructor for the pseudo-FieldDescriptor associated with each ClassDesctiptor, for translateToXML of fields that deriveTagFromClass.

FieldDescriptor(ClassDescriptor baseClassDescriptor, FieldDescriptor wrappedFD, java.lang.String wrapperTag)

FieldDescriptor(ClassDescriptor declaringClassDescriptor, java.lang.reflect.Field field, int annotationType)
This is the normal constructor.

Method Summary

void	appendCollectionLeaf(org.w3c.dom.Element element, java.lang.Object instance)
void	appendLeaf(org.w3c.dom.Element element, java.lang.Object instance) Use this and the context to set an attribute (name, value) on the Element DOM Node passed in.
void	appendValueAsAttribute(java.lang.Appendable appendable, java.lang.Object context) Use this and the context to append an attribute / value pair to the Appendable passed in.
void	appendValueAsAttribute(java.lang.StringBuilder buffy, java.lang.Object context) Use this and the context to append an attribute / value pair to the StringBuilder passed in.
void	appendXmlText(org.w3c.dom.Element element, java.lang.Object instance)
boolean	belongsTo(ClassDescriptor c)
java.lang.String	elementStart()
ElementState	getAndPerhapsCreateNested(ElementState context)
java.util.Collection	getCollection(ElementState context)
java.lang.String	getCollectionOrMapTagName()
java.lang.reflect.Field	getField()
java.lang.String	getFieldName()
java.lang.Class<?>	getFieldType()
java.lang.String[]	getFormat()
java.util.Map	getMap(ElementState context)
ElementState	getNested(ElementState context)
ScalarType<?>	getScalarType()
java.util.Collection<ClassDescriptor>	getTagClassDescriptors()
java.lang.String	getTagName() NB: For polymorphic fields, the value of this field is meaningless, except for wrapped collections and maps.
int	getType()
java.lang.Class<?>	getTypeArgClass(java.lang.reflect.Field field, int i) Get the value of the ith declared type argument from a field declaration.
java.lang.String	getValueString(ElementState context) Get the String representation of the value of the field, in the context object, using the ScalarType.
FieldDescriptor	getWrappedFD()
java.lang.reflect.Field	getXmlTextScalarField()
boolean	hasXmlText()
boolean	isCDATA()
boolean	isCollection()
boolean	isMarshallOnly() Used to describe scalar types used for serializing the type system, itself.
boolean	isMixin()
boolean	isNeedsEscaping()
boolean	isNested()
boolean	isNonNullReference(ElementState context)
boolean	isPolymorphic() Most fields derive their tag from Field name for marshaling.
boolean	isPseudoScalar()
boolean	isScalar()
boolean	isWrapped()
boolean	isXmlNsDecl()
void	set(ElementState context, java.lang.Object value) In the supplied context object, set the non-scalar field to a non-scalar value.
boolean	set(ElementState context, java.lang.String valueString)
boolean	set(ElementState context, java.lang.String valueString, ScalarUnmarshallingContext scalarUnMarshallingContext) In the supplied context object, set the *typed* value of the field, using the valueString passed in.
void	setAttribute(org.w3c.dom.Element element, java.lang.Object context) Use this and the context to set an attribute (name, value) on the Element DOM Node passed in.
void	setField(ElementState context, java.lang.Object value)
java.lang.String	toString()
void	writeElementStart(java.lang.Appendable appendable)
void	writeElementStart(java.lang.StringBuilder buffy)
void	writeWrap(java.lang.Appendable appendable, boolean close) Write the tags for opening and closing a wrapped collection.
void	writeWrap(java.lang.StringBuilder buffy, boolean close) Write the tags for opening and closing a wrapped collection.

Methods inherited from class ecologylab.xml.ElementState

buildDOM, buildDOM, buildDOM, buildDOM, buildDOM, buildDOMFromXMLCharSequence, buildDOMFromXMLString, checkAnnotation, classDescriptor, createParentDirs, getChildFieldAccessors, getElementStateById, getFieldDescriptors, getNestedNameSpace, getTextNodeString, hasScalarTextField, lookupNestedNameSpace, parent, recycle, setDeclarationStyle, setParent, setUseDOMForTranslateTo, translateFromXML, translateFromXML, translateFromXML, translateFromXML, translateFromXML, translateFromXMLCharSequence, translateFromXMLDOM, translateFromXMLDOM, translateFromXMLDOM, translateFromXMLDOM, translateFromXMLDOM, translateFromXMLDOM, translateFromXMLDOMCharSequence, translateFromXMLDOMCharSequence, translateFromXMLRootNode, translateFromXMLSAX, translateFromXMLSAX, translateFromXMLSAX, translateFromXMLSAX, translateFromXMLSAX, translateToDOM, translateToXML, translateToXML, translateToXML, translateToXML, writePrettyXML, writePrettyXML, writePrettyXML

Methods inherited from class ecologylab.generic.Debug

classSimpleName, closeLoggingFile, debug, debug, debug, debug, debugA, debugA, debugA, debugI, debugI, debugI, error, error, getClassName, getClassName, getInteractive, getPackageName, getPackageName, getPackageName, initialize, level, level, level, logToFile, print, print, println, println, println, println, println, println, printlnA, printlnA, printlnA, printlnI, printlnI, printlnI, printlnI, setLoggingFile, show, show, superString, toggleInteractive, toString, warning, warning, weird, weird

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NULL

public static final java.lang.String NULL

See Also:

Constant Field Values

SET_METHOD_ARG

public static final java.lang.Class[] SET_METHOD_ARG

Constructor Detail

FieldDescriptor

public FieldDescriptor()

Default constructor only for use by translateFromXML().

FieldDescriptor

public FieldDescriptor(ClassDescriptor baseClassDescriptor)

Constructor for the pseudo-FieldDescriptor associated with each ClassDesctiptor, for translateToXML of fields that deriveTagFromClass.

Parameters:

baseClassDescriptor -

FieldDescriptor

public FieldDescriptor(ClassDescriptor baseClassDescriptor,
                       FieldDescriptor wrappedFD,
                       java.lang.String wrapperTag)

FieldDescriptor

public FieldDescriptor(ClassDescriptor declaringClassDescriptor,
                       java.lang.reflect.Field field,
                       int annotationType)

This is the normal constructor.

Parameters:

declaringClassDescriptor -

field -

annotationType - Coarse pre-evaluation of the field's annotation type. Does not differentiate scalars from elements, or check for semantic consistency.

Method Detail

getTypeArgClass

public java.lang.Class<?> getTypeArgClass(java.lang.reflect.Field field,
                                          int i)

Get the value of the ith declared type argument from a field declaration. Only works when the type variable is directly instantiated in the declaration.

DOES NOT WORK when the type variable is instantiated outside the declaration, and passed in. This is because in Java, generic type variables are (lamely!) erased after compile time. They do not exist at runtime :-( :-( :-(

Parameters:

field -

i - Index of the type variable in the field declaration.

Returns:

The class of the type variable, if it exists.

isScalar

public boolean isScalar()

Returns:

true if this field represents a ScalarType, not a nested element or collection thereof.

isCollection

public boolean isCollection()

isNested

public boolean isNested()

set

public boolean set(ElementState context,
                   java.lang.String valueString)

set

public boolean set(ElementState context,
                   java.lang.String valueString,
                   ScalarUnmarshallingContext scalarUnMarshallingContext)

In the supplied context object, set the *typed* value of the field, using the valueString passed in. Unmarshalling is performed automatically, by the ScalarType already stored in this.

Use a set method, if one is defined.

Parameters:

context - ElementState object to set the Field in this.

valueString - The value to set, which this method will use with the ScalarType, to create the value that will be set.

set

public void set(ElementState context,
                java.lang.Object value)

In the supplied context object, set the non-scalar field to a non-scalar value.

Parameters:

context -

value - An ElementState, or a Collection, or a Map.

setField

public void setField(ElementState context,
                     java.lang.Object value)

getValueString

public java.lang.String getValueString(ElementState context)

Get the String representation of the value of the field, in the context object, using the ScalarType.

Parameters:

context -

Returns:

getFieldName

public java.lang.String getFieldName()

Returns:

The Java name of the field.

getTagName

public java.lang.String getTagName()

NB: For polymorphic fields, the value of this field is meaningless, except for wrapped collections and maps.

Returns:

The tag name that this field is translated to XML with.

getScalarType

public ScalarType<?> getScalarType()

Returns:

the scalarType of the field

getField

public java.lang.reflect.Field getField()

Returns:

the field

getFieldType

public java.lang.Class<?> getFieldType()

Returns:

the class of the field

getType

public int getType()

Returns:

The OptimizationTypes type of the field.

getXmlTextScalarField

public java.lang.reflect.Field getXmlTextScalarField()

Returns:

the xmlTextScalarField

getNested

public ElementState getNested(ElementState context)

getMap

public java.util.Map getMap(ElementState context)

getCollection

public java.util.Collection getCollection(ElementState context)

isPseudoScalar

public boolean isPseudoScalar()

isMixin

public boolean isMixin()

isNonNullReference

public boolean isNonNullReference(ElementState context)

Parameters:

context - Object that the field is in.

Returns:

true if the field is not a scalar or a psuedo-scalar, and it has a non null value.

getAndPerhapsCreateNested

public ElementState getAndPerhapsCreateNested(ElementState context)

isWrapped

public boolean isWrapped()

appendValueAsAttribute

public void appendValueAsAttribute(java.lang.StringBuilder buffy,
                                   java.lang.Object context)
                            throws java.lang.IllegalArgumentException,
                                   java.lang.IllegalAccessException

Use this and the context to append an attribute / value pair to the StringBuilder passed in.

Parameters:

buffy -

context -

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalAccessException

setAttribute

public void setAttribute(org.w3c.dom.Element element,
                         java.lang.Object context)
                  throws java.lang.IllegalArgumentException,
                         java.lang.IllegalAccessException

Use this and the context to set an attribute (name, value) on the Element DOM Node passed in.

Parameters:

element -

context -

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalAccessException

appendLeaf

public void appendLeaf(org.w3c.dom.Element element,
                       java.lang.Object instance)
                throws java.lang.IllegalArgumentException,
                       java.lang.IllegalAccessException

Use this and the context to set an attribute (name, value) on the Element DOM Node passed in.

Parameters:

element -

instance -

isAtXMLText - TODO

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalAccessException

appendXmlText

public void appendXmlText(org.w3c.dom.Element element,
                          java.lang.Object instance)
                   throws java.lang.IllegalArgumentException,
                          java.lang.IllegalAccessException

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalAccessException

appendCollectionLeaf

public void appendCollectionLeaf(org.w3c.dom.Element element,
                                 java.lang.Object instance)
                          throws java.lang.IllegalArgumentException,
                                 java.lang.IllegalAccessException

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalAccessException

appendValueAsAttribute

public void appendValueAsAttribute(java.lang.Appendable appendable,
                                   java.lang.Object context)
                            throws java.lang.IllegalArgumentException,
                                   java.lang.IllegalAccessException,
                                   java.io.IOException

Use this and the context to append an attribute / value pair to the Appendable passed in.

Parameters:

appendable -

context -

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalAccessException

java.io.IOException

isCDATA

public boolean isCDATA()

isNeedsEscaping

public boolean isNeedsEscaping()

getFormat

public java.lang.String[] getFormat()

toString

public java.lang.String toString()

Overrides:

toString in class Debug

getTagClassDescriptors

public java.util.Collection<ClassDescriptor> getTagClassDescriptors()

writeElementStart

public void writeElementStart(java.lang.StringBuilder buffy)

writeElementStart

public void writeElementStart(java.lang.Appendable appendable)
                       throws java.io.IOException

Throws:

java.io.IOException

writeWrap

public void writeWrap(java.lang.StringBuilder buffy,
                      boolean close)

Write the tags for opening and closing a wrapped collection.

Parameters:

buffy -

close -

writeWrap

public void writeWrap(java.lang.Appendable appendable,
                      boolean close)
               throws java.io.IOException

Write the tags for opening and closing a wrapped collection.

Parameters:

appendable -

close -

Throws:

java.io.IOException

elementStart

public java.lang.String elementStart()

isPolymorphic

public boolean isPolymorphic()

Most fields derive their tag from Field name for marshaling. However, some, such as those annotated with @xml_class, @xml_classes, @xml_scope, derive their tag from the class of an instance. This includes all polymorphic fields.

Returns:

true if the tag name name is derived from the class name ( not the usual case, but needed for polymorphism). else if the tag name is derived from the class name for @xml_nested or, for @xml_collection and @xml_map), the tag name is derived from the annotation's value

getCollectionOrMapTagName

public java.lang.String getCollectionOrMapTagName()

hasXmlText

public boolean hasXmlText()

isXmlNsDecl

public boolean isXmlNsDecl()

isMarshallOnly

public boolean isMarshallOnly()

Used to describe scalar types used for serializing the type system, itself. They cannot be unmarshalled in Java, only marshalled. Code may be written to access their String representations in other languages.

Returns:

false for almost all ScalarTypes and for all element fields

getWrappedFD

public FieldDescriptor getWrappedFD()

belongsTo

public boolean belongsTo(ClassDescriptor c)