org.exolab.castor.xml.util
Class XMLFieldDescriptorImpl

java.lang.Object
  org.exolab.castor.mapping.loader.FieldDescriptorImpl
      org.exolab.castor.xml.util.XMLFieldDescriptorImpl

All Implemented Interfaces:

NatureExtendable, PropertyHolder, FieldDescriptor, XMLFieldDescriptor

Direct Known Subclasses:

XMLContainerElementFieldDescriptor

public class XMLFieldDescriptorImpl
extends FieldDescriptorImpl
implements XMLFieldDescriptor

XML field descriptor. Wraps FieldDescriptor and adds XML-related information, type conversion, etc.

Note: When using a GeneralizedFieldHandler the getFieldType() methods of handler and descriptor need to return the same result.

Version:

$Revision: 8690 $ $Date: 2006-04-13 06:47:36 -0600 (Thu, 13 Apr 2006) $

Author:

Keith Visco, Ralf Joachim

Field Summary

boolean

_isReference True if the field is a reference to another Object in the hierarchy.

Fields inherited from interface org.exolab.castor.xml.XMLFieldDescriptor

PROPERTY_XML_LANG, PROPERTY_XML_SPACE

Constructor Summary

XMLFieldDescriptorImpl(Class<?> fieldType, String fieldName, String xmlName, NodeType nodeType)

XMLFieldDescriptorImpl(FieldDescriptor fieldDesc, String xmlName, NodeType nodeType, NodeType primitiveNodeType)
Construct a new field descriptor for the specified field.

Method Summary

boolean	equals(Object obj) Returns true if two XMLFieldDescriptors should be treated as equal.
String	getComponentType() Returns the component type of this XMLFieldDescriptor instance, if the field described represents a collection of values.
int	getConstructorArgumentIndex() Returns the index within the constructor argument array where the value of this field should be.
String	getLocationPath() Returns the "relative" XML path for the field being described.
String	getNameSpacePrefix() Return the "suggested" namespace prefix to use when marshaling as XML.
String	getNameSpaceURI() Returns the namespace URI to be used when marshaling and unmarshaling as XML.
NodeType	getNodeType() Returns the node type of the field being described.
String	getQNamePrefix() Returns the prefix used in case the value of the field described by this descriptor is of type QName.
String	getSchemaType() Returns the XML Schema type of the XML field being described.
List<String>	getSubstitutes() Returns the possible substitution groups for this class.
FieldValidator	getValidator() Returns a specific validator for the field described by this descriptor.
String	getXMLName() Returns the XML Name for the field being described.
String	getXMLProperty(String propertyName) Returns the value property with the given name or null if no such property exists.
int	hashCode() Returns the hashCode for this XMLFieldDescriptor
boolean	isConstructorArgument() Returns true if the value of the field represented by this descriptor should be set via the constructor of the containing class.
boolean	isContainer() Returns true if the field described by this descriptor is a container field.
boolean	isDerivedFromXSList() Indicates whether the field described by this XMLFieldDescriptorImpl is created as a result of a definition.
boolean	isIncremental() Returns the incremental flag which when true indicates that this member may be safely added before the unmarshaler is finished unmarshaling it.
boolean	isMapped() Returns true if the field described by this descriptor is Map or Hashtable.
boolean	isNillable() Returns true if the field described by this descriptor may be nillable.
boolean	isReference() Returns true if the field described by this descriptor is a reference (ie.
boolean	matches(String xmlName) Returns true if this descriptor can be used to handle elements or attributes with the given XML name.
boolean	matches(String xmlName, String namespace) Returns true if this descriptor can be used to handle elements or attributes with the given XML name.
void	setComponentType(String componentType) Sets the type of the XML Schema type of the value for the field being described.
void	setConstructorArgumentIndex(int index) Sets whether or not the value of the field represented by this FieldDescriptor should be set via the constructor of the containing ClassDescriptor.
void	setContainer(boolean isContainer) Set if the field is a container field or not.
void	setDerivedFromXSList(boolean derivedFromXSList) Sets whether the field described by this XMLFieldDescriptorImpl is created as a result of a definition.
void	setIncremental(boolean incremental) Sets the incremental flag which indicates whether this member can be added before the unmarshaler is finished unmarshaling it.
void	setLocationPath(String path) Sets the location path for the field being described.
void	setMapped(boolean mapped) Sets whether or not this field has been mapped in a Map or Hashtable.
void	setMatches(String matchExpr) This is a space separated list of xml names that this Field descriptor matches.
void	setNameSpacePrefix(String nsPrefix) Sets the namespace prefix used when marshaling as XML.
void	setNameSpaceURI(String nsURI) Sets the namespace URI used when marshaling and unmarshaling as XML.
void	setNillable(boolean nillable) Sets whether or not the described field is allowed to be nil.
void	setNodeType(NodeType nodeType) Sets the XML node type for the described field.
void	setQNamePrefix(String qNamePrefix) Sets the prefix used in case the value of the field described by this descriptor is of type QName.
void	setReference(boolean isReference) Sets the flag indicating that the field described by this descriptor is a reference to another field in the object model.
void	setSchemaType(String schemaType) Sets the type of the XML Schema type of the value for the field being described.
void	setSubstitutes(List<String> substitutes) Sets the possible substitution groups for this class.
void	setUseParentsNamespace(boolean useParentsNamespace) Sets whether or not the namespace for the parent "containing" class should be used during marshaling/unmarshaling when no specific namespace URI has been set for this field.
void	setValidator(FieldValidator validator)
void	setXMLName(String xmlName) Sets the xml name for the described field.
void	setXMLProperty(String propertyName, String value) Sets the value property with the given name.
String	toString()

Methods inherited from class org.exolab.castor.mapping.loader.FieldDescriptorImpl

addNature, getClassDescriptor, getCollection, getComparator, getContainingClassDescriptor, getCreateMethod, getFieldName, getFieldType, getGetMethod, getHandler, getProperty, getSetMethod, hasNature, isDirect, isIdentity, isImmutable, isLazy, isMultivalued, isRequired, isTransient, setClassDescriptor, setCollection, setComparator, setContainingClassDescriptor, setCreateMethod, setDirect, setFieldName, setFieldType, setGetMethod, setHandler, setIdentity, setImmutable, setLazy, setMultivalued, setProperty, setRequired, setSetMethod, setTransient

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.exolab.castor.xml.XMLFieldDescriptor

isMultivalued

Methods inherited from interface org.exolab.castor.mapping.FieldDescriptor

getClassDescriptor, getContainingClassDescriptor, getFieldName, getFieldType, getHandler, isImmutable, isRequired, isTransient, setContainingClassDescriptor

Methods inherited from interface org.castor.core.nature.PropertyHolder

getProperty, setProperty

Methods inherited from interface org.castor.core.nature.NatureExtendable

addNature, hasNature

Field Detail

_isReference

public boolean _isReference

True if the field is a reference to another Object in the hierarchy.

Constructor Detail

XMLFieldDescriptorImpl

public XMLFieldDescriptorImpl(Class<?> fieldType,
                              String fieldName,
                              String xmlName,
                              NodeType nodeType)

XMLFieldDescriptorImpl

public XMLFieldDescriptorImpl(FieldDescriptor fieldDesc,
                              String xmlName,
                              NodeType nodeType,
                              NodeType primitiveNodeType)
                       throws MappingException

Construct a new field descriptor for the specified field. This is an XML field descriptor wrapping a field descriptor and adding XML related properties and methods.

Parameters:

fieldDesc - The field descriptor

xmlName - The XML name of the field

nodeType - The node type of this field

primitiveNodeType -

Throws:

MappingException - Invalid mapping information

Method Detail

setConstructorArgumentIndex

public void setConstructorArgumentIndex(int index)

Sets whether or not the value of the field represented by this FieldDescriptor should be set via the constructor of the containing ClassDescriptor. The index value greater than 0 specifies the index within the argument array that the value of this field should be.

Note: This only applies to attribute mapped fields at this time.

Parameters:

index - the index within the argument array. A value less than zero indicates that this field should not be part of the constructor arguments.

getConstructorArgumentIndex

public int getConstructorArgumentIndex()

Description copied from interface: XMLFieldDescriptor

Returns the index within the constructor argument array where the value of this field should be. A value less than zero indicates that the value of this field is set via a normal setter method and not via the constructor.

Note: This only applies to attribute mapped fields at this time.

Specified by:

getConstructorArgumentIndex in interface XMLFieldDescriptor

Returns:

the index within the constructor argument array for this field.

See Also:

{@inheritDoc}

isConstructorArgument

public boolean isConstructorArgument()

Description copied from interface: XMLFieldDescriptor

Returns true if the value of the field represented by this descriptor should be set via the constructor of the containing class. This is only valid for attribute mapped fields.

Specified by:

isConstructorArgument in interface XMLFieldDescriptor

Returns:

true if the value of the field represented by this descriptor should be set via the constructor of the containing class.

See Also:

{@inheritDoc}

setLocationPath

public void setLocationPath(String path)

Sets the location path for the field being described.

In most cases, this isn't needed. However sometimes a field may be mapped to a nested element. In which case the value of the location path should be the nested element name. If more than one level of nesting is needed each nested element name should be separated by a path separator (forward slash '/').

The location path name is "relative" to the parent Class. The name of the parent should not be included in the path.

For example, give the following two classes: class Root { Bar bar; } class Bar { String value; } And the following XML: <root> <foo> <bar> value of bar </bar> </foo> </root> Since foo has no associated class, the path for 'bar' would be: "foo"

Parameters:

path - the "relative" location path for the field.

See Also:

getLocationPath()

getLocationPath

public String getLocationPath()

Description copied from interface: XMLFieldDescriptor

Returns the "relative" XML path for the field being described.

In most cases, this will be null. However sometimes a field may be mapped to a nested element. In which case the value returned by this method should be the nested element name. If more than one level of nesting is needed each nested element name should be separated by by a path separator (forward slash '/').

The location path name is "relative" to the parent Class. The name of the parent must not be included in the path.

For example, give the following two classes:

    class Root {
        Bar bar;
    }

    class Bar {
       String value;
    }
 

And the following XML:

    <root>
       <foo>
          <bar> value of bar </bar>
       </foo>
    </root>
 

Since <foo> has no associated class, the path for 'bar' would be: "foo"

Specified by:

getLocationPath in interface XMLFieldDescriptor

Returns:

The "relative" XML path for the field being described.

See Also:

{@inheritDoc}

setNameSpacePrefix

public void setNameSpacePrefix(String nsPrefix)

Sets the namespace prefix used when marshaling as XML.

Parameters:

nsPrefix - The namespace prefix used when marshaling the "described" object.

getNameSpacePrefix

public String getNameSpacePrefix()

Description copied from interface: XMLFieldDescriptor

Return the "suggested" namespace prefix to use when marshaling as XML.

Specified by:

getNameSpacePrefix in interface XMLFieldDescriptor

Returns:

the "suggested" namespace prefix.

See Also:

{@inheritDoc}

setUseParentsNamespace

public void setUseParentsNamespace(boolean useParentsNamespace)

Sets whether or not the namespace for the parent "containing" class should be used during marshaling/unmarshaling when no specific namespace URI has been set for this field.

setNameSpaceURI

public void setNameSpaceURI(String nsURI)

Sets the namespace URI used when marshaling and unmarshaling as XML.

Parameters:

nsURI - The namespace URI used when marshaling and unmarshaling the "described" Object.

getNameSpaceURI

public String getNameSpaceURI()

Description copied from interface: XMLFieldDescriptor

Returns the namespace URI to be used when marshaling and unmarshaling as XML.

Specified by:

getNameSpaceURI in interface XMLFieldDescriptor

Returns:

the namespace URI.

See Also:

{@inheritDoc}

setNodeType

public void setNodeType(NodeType nodeType)

Sets the XML node type for the described field.

Parameters:

nodeType - the NodeType for the described field.

getNodeType

public NodeType getNodeType()

Description copied from interface: XMLFieldDescriptor

Returns the node type of the field being described. The NodeType represents the type of node that the field will be marshaled into XML as.

Specified by:

getNodeType in interface XMLFieldDescriptor

Returns:

the NodeType of the Field being described.

See Also:

{@inheritDoc}

setXMLProperty

public void setXMLProperty(String propertyName,
                           String value)

Sets the value property with the given name.

Parameters:

propertyName - The name of the property to set the value of.

value - The value of the property.

See Also:

FieldDescriptorImpl.getProperty(java.lang.String)

getXMLProperty

public String getXMLProperty(String propertyName)

Description copied from interface: XMLFieldDescriptor

Returns the value property with the given name or null if no such property exists. This method is useful for future evolutions of this interface as well as for user-defined extensions. See class declared properties for built-in properties.

Specified by:

getXMLProperty in interface XMLFieldDescriptor

Parameters:

propertyName - the name of the property whose value should be returned.

Returns:

the value of the property, or null.

See Also:

{@inheritDoc}

setSchemaType

public void setSchemaType(String schemaType)

Sets the type of the XML Schema type of the value for the field being described.

Parameters:

schemaType - The value type.

setComponentType

public void setComponentType(String componentType)

Sets the type of the XML Schema type of the value for the field being described.

Parameters:

componentType - The component type for <xs:list>s.

getSchemaType

public String getSchemaType()

Description copied from interface: XMLFieldDescriptor

Returns the XML Schema type of the XML field being described.

Specified by:

getSchemaType in interface XMLFieldDescriptor

Returns:

the XML Schema type of the XML field being described.

See Also:

{@inheritDoc}

getComponentType

public String getComponentType()

Returns the component type of this XMLFieldDescriptor instance, if the field described represents a collection of values.

Specified by:

getComponentType in interface XMLFieldDescriptor

Returns:

The collection's component type.

See Also:

XMLFieldDescriptor.getComponentType()

setValidator

public void setValidator(FieldValidator validator)

getValidator

public FieldValidator getValidator()

Description copied from interface: XMLFieldDescriptor

Returns a specific validator for the field described by this descriptor. A null value may be returned if no specific validator exists.

Specified by:

getValidator in interface XMLFieldDescriptor

Returns:

the field validator for the described field

See Also:

{@inheritDoc}

setXMLName

public void setXMLName(String xmlName)

Sets the xml name for the described field.

Parameters:

xmlName - the XML name for the described field.

getXMLName

public String getXMLName()

Description copied from interface: XMLFieldDescriptor

Returns the XML Name for the field being described.

Specified by:

getXMLName in interface XMLFieldDescriptor

Returns:

the XML name.

See Also:

{@inheritDoc}

setContainer

public void setContainer(boolean isContainer)

Set if the field is a container field or not.

Parameters:

isContainer - a boolean indicating whether or not the field is a container field.

isContainer

public boolean isContainer()

Description copied from interface: XMLFieldDescriptor

Returns true if the field described by this descriptor is a container field. A container is a field that is not a first-class object, and should therefore have no XML representation.

Specified by:

isContainer in interface XMLFieldDescriptor

Returns:

true if the field is a container

See Also:

{@inheritDoc}

setIncremental

public void setIncremental(boolean incremental)

Sets the incremental flag which indicates whether this member can be added before the unmarshaler is finished unmarshaling it.

Parameters:

incremental - the boolean which if true indicated that this member can safely be added before the unmarshaler is finished unmarshaling it.

isIncremental

public boolean isIncremental()

Description copied from interface: XMLFieldDescriptor

Returns the incremental flag which when true indicates that this member may be safely added before the unmarshaler is finished unmarshaling it.

Specified by:

isIncremental in interface XMLFieldDescriptor

Returns:

true if the Object can safely be added before the unmarshaler is finished unmarshaling the Object.

See Also:

{@inheritDoc}

setMapped

public void setMapped(boolean mapped)

Sets whether or not this field has been mapped in a Map or Hashtable.

Parameters:

mapped - a boolean that when true indicates this field is a Hashtable or Map.

isMapped

public boolean isMapped()

Description copied from interface: XMLFieldDescriptor

Returns true if the field described by this descriptor is Map or Hashtable. If this method returns true, it must also return true for any call to XMLFieldDescriptor.isMultivalued().

Specified by:

isMapped in interface XMLFieldDescriptor

Returns:

true if the field described by this desciptor is a Map or Hashtable, otherwise false.

See Also:

{@inheritDoc}

setNillable

public void setNillable(boolean nillable)

Sets whether or not the described field is allowed to be nil. A nillable field can have empty content (text or element content), but may have attribute values, and still be considered value, even if the child elements are required.

Parameters:

nillable - a boolean indicating whether or not the described field may be nillable.

isNillable

public boolean isNillable()

Description copied from interface: XMLFieldDescriptor

Returns true if the field described by this descriptor may be nillable. A nillable field is one that may have empty content and still be valid. Please see the XML Schema 1.0 Recommendation for more information on nillable.

Specified by:

isNillable in interface XMLFieldDescriptor

Returns:

true if the field may be nillable.

See Also:

{@inheritDoc}

setReference

public void setReference(boolean isReference)

Sets the flag indicating that the field described by this descriptor is a reference to another field in the object model.

Parameters:

isReference - true if the field is a reference to another field.

isReference

public boolean isReference()

Description copied from interface: XMLFieldDescriptor

Returns true if the field described by this descriptor is a reference (ie. IDREF) to another object in the "Object Model" (e.g., XML tree).

Specified by:

isReference in interface XMLFieldDescriptor

Returns:

true if the field described by this descriptor is a reference to another object in the "Object Model"

See Also:

{@inheritDoc}

setQNamePrefix

public void setQNamePrefix(String qNamePrefix)

Sets the prefix used in case the value of the field described by this descriptor is of type QName.

Parameters:

qNamePrefix -

getQNamePrefix

public String getQNamePrefix()

Returns the prefix used in case the value of the field described by this descriptor is of type QName. This is helpful for the marshaler but not mandatory.

Returns:

the prefix used in the QName value.

setMatches

public void setMatches(String matchExpr)

This is a space separated list of xml names that this Field descriptor matches. A '*' is wild.

Parameters:

matchExpr - the space separated list of xml names, matched by this descriptor.

matches

public boolean matches(String xmlName)

Description copied from interface: XMLFieldDescriptor

Returns true if this descriptor can be used to handle elements or attributes with the given XML name. By default this method simply compares the given XML name with the internal XML name. This method can be overridden to provide more complex matching.

Specified by:

matches in interface XMLFieldDescriptor

Parameters:

xmlName - the XML name to compare

Returns:

true if this descriptor can be used to handle elements or attributes with the given XML name.

See Also:

{@inheritDoc}

matches

public boolean matches(String xmlName,
                       String namespace)

Description copied from interface: XMLFieldDescriptor

Returns true if this descriptor can be used to handle elements or attributes with the given XML name. By default this method simply compares the given XML name with the internal XML name. This method can be overridden to provide more complex matching.

Specified by:

matches in interface XMLFieldDescriptor

Parameters:

xmlName - the XML name to compare

namespace - the namespace URI

Returns:

true if this descriptor can be used to handle elements or attributes with the given XML name.

See Also:

{@inheritDoc}

equals

public boolean equals(Object obj)

Returns true if two XMLFieldDescriptors should be treated as equal. Any XMLFieldDescriptor that handles the same field is considered equal.

Overrides:

equals in class Object

Parameters:

obj - The object to compare to this

Returns:

true if two XMLFieldDescriptors should be treated as equal.

hashCode

public int hashCode()

Returns the hashCode for this XMLFieldDescriptor

Overrides:

hashCode in class Object

Returns:

the hashCode for this XMLFieldDescriptor

toString

public String toString()

Overrides:

toString in class FieldDescriptorImpl

getSubstitutes

public List<String> getSubstitutes()

Returns the possible substitution groups for this class.

Specified by:

getSubstitutes in interface XMLFieldDescriptor

Returns:

the possible substitution groups for this class.

setSubstitutes

public void setSubstitutes(List<String> substitutes)

Sets the possible substitution groups for this class.

Specified by:

setSubstitutes in interface XMLFieldDescriptor

Parameters:

substitutes - Possible substitution groups for this class.

setDerivedFromXSList

public void setDerivedFromXSList(boolean derivedFromXSList)

Sets whether the field described by this XMLFieldDescriptorImpl is created as a result of a definition.

Specified by:

setDerivedFromXSList in interface XMLFieldDescriptor

Parameters:

derivedFromXSList - A boolean value, true or false.

See Also:

XMLFieldDescriptor.setDerivedFromXSList(boolean)

isDerivedFromXSList

public boolean isDerivedFromXSList()

Indicates whether the field described by this XMLFieldDescriptorImpl is created as a result of a definition.

Specified by:

isDerivedFromXSList in interface XMLFieldDescriptor

See Also:

XMLFieldDescriptor.isDerivedFromXSList()