org.exolab.castor.xml.util

Class XMLFieldDescriptorImpl

public class XMLFieldDescriptorImpl extends Object implements XMLFieldDescriptor

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

Version: $Revision: 1.12 $ $Date: 2005/08/18 04:06:28 $

Author: Keith Visco

Field Summary
boolean_isReference
True if the field is a reference to another Object in the hierarchy.
boolean_required
indicates a required field when true
Constructor Summary
XMLFieldDescriptorImpl(Class fieldType, String fieldName, String xmlName, NodeType nodeType)
XMLFieldDescriptorImpl(XMLFieldDescriptor fieldDesc)
Makes a new copy of the given XMLFieldDescriptorImpl
XMLFieldDescriptorImpl(FieldDescriptor fieldDesc, String xmlName, NodeType nodeType)
Construct a new field descriptor for the specified field.
XMLFieldDescriptorImpl(FieldDescriptor fieldDesc, String xmlName, NodeType nodeType, NodeType primitiveNodeType)
Construct a new field descriptor for the specified field.
Method Summary
booleanequals(Object obj)
Returns true if two XMLFieldDescriptors should be treated as equal.
ClassDescriptorgetClassDescriptor()
Returns the class descriptor related to the field type.
CollectionHandlergetCollectionHandler()
Return the collection handler of this field type.
intgetConstructorArgumentIndex()
Returns the index within the constructor argument array where the value of this field should be.
ClassDescriptorgetContainingClassDescriptor()
StringgetFieldName()
Returns the name of the field.
ClassgetFieldType()
Returns the Java type of the field.
FieldHandlergetHandler()
Returns the handler of the field.
StringgetLocationPath()
Returns the "relative" XML path for the field being described.
StringgetNameSpacePrefix()
Return the "suggested" namespace prefix to use when marshalling as XML.
StringgetNameSpaceURI()
Returns the namespace URI to be used when marshalling and unmarshalling as XML.
NodeTypegetNodeType()
StringgetProperty(String propertyName)
Returns the value property with the given name or null if no such property exists.
StringgetQNamePrefix()
Returns the prefix used in case the value of the field described by this descriptor is of type QName.
StringgetSchemaType()
Returns the XML Schema type of the value of the field described by this descriptor.
FieldValidatorgetValidator()
Returns a specific validator for the field described by this descriptor.
StringgetXMLName()
Returns the XML Name for the field being described.
inthashCode()
Returns the hashCode for this XMLFieldDescriptor
protected booleanhasNonDefaultMatching()
Returns true if a call to #setMatches has been made with a non-null, or non-zero-length value.
booleanisConstructorArgument()
Returns true if the value of the field represented by this descriptor should be set via the constructor of the containing class.
booleanisContainer()
Returns true if the field described by this descriptor is a container field.
booleanisImmutable()
Returns true if the field type is immutable.
booleanisIncremental()
Returns the incremental flag which when true indicates that this member may be safely added before the unmarshaller is finished unmarshalling it.
booleanisMapped()
Returns true if the field described by this descriptor is Map or Hashtable.
booleanisMultivalued()
Returns true if the Object described by this descriptor can contain more than one value
booleanisNillable()
protected static booleanisPrimitive(Class type)
Returns true if the given class should be treated as a primitive type.
booleanisReference()
Returns true if the field described by this descriptor is a reference (ie.
booleanisRequired()
Returns true if the field described by this descriptor is a required field
booleanisTransient()
Returns true if the field is transient.
booleanmatches(String xmlName)
Returns true if this descriptor can be used to handle elements or attributes with the given XML name.
booleanmatches(String xmlName, String namespace)
Returns true if this descriptor can be used to handle elements or attributes with the given XML name.
voidsetClassDescriptor(XMLClassDescriptor classDescriptor)
Sets the XMLClassDescriptor for the described field
voidsetConstructorArgumentIndex(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.
voidsetContainer(boolean isContainer)
Set if the field is a container field or not.
voidsetContainingClassDescriptor(ClassDescriptor contClsDesc)
Set the class which contains this field
voidsetHandler(FieldHandler handler)
Sets the FieldHandler for the field being described by this FieldDescriptor
voidsetImmutable(boolean immutable)
Sets the immutable flag which indicates that changes to this Field result in a new Object to be created, such as java.lang.String.
voidsetIncremental(boolean incremental)
Sets the incremental flag which indicates whether this member can be added before the unmarshaller is finished unmarshalling it.
voidsetLocationPath(String path)
Sets the location path for the field being described.
voidsetMapped(boolean mapped)
Sets whether or not this field has been mapped in a Map or Hashtable.
voidsetMatches(String matchExpr)
This is a space separated list of xml names that this Field descriptor matches.
voidsetMultivalued(boolean multivalued)
voidsetNameSpacePrefix(String nsPrefix)
Sets the namespace prefix used when marshalling as XML.
voidsetNameSpaceURI(String nsURI)
Sets the namespace URI used when marshalling and unmarshalling as XML.
voidsetNillable(boolean nillable)
Sets whether or not the described field is allowed to be nil.
voidsetNodeType(NodeType nodeType)
Sets the XML node type for the described field
voidsetProperty(String propertyName, String value)
Sets the value property with the given name
voidsetQNamePrefix(String qNamePrefix)
Sets the prefix used in case the value of the field described by this descriptor is of type QName.
voidsetReference(boolean isReference)
Sets the flag indicating that the field described by this descriptor is a reference to another field in the object model.
voidsetRequired(boolean required)
Sets the whether or not the described field is required
voidsetSchemaType(String schemaType)
Sets the type of the XML Schema type of the value for the field being described.
voidsetTransient(boolean isTransient)
Sets whether or not the describled field is transient
voidsetUseParentsNamespace(boolean useParentsNamespace)
Sets whether or not the namespace for the parent "containing" class should be used during marshalling/unmarshalling when no specific namespace URI has been set for this field.
voidsetValidator(FieldValidator validator)
voidsetXMLName(String xmlName)
Sets the xml name for the described field
StringtoString()

Field Detail

_isReference

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

_required

public boolean _required
indicates a required field when true

Constructor Detail

XMLFieldDescriptorImpl

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

XMLFieldDescriptorImpl

public XMLFieldDescriptorImpl(XMLFieldDescriptor fieldDesc)
Makes a new copy of the given XMLFieldDescriptorImpl

Parameters: fieldDesc The XMLFieldDescriptor to copy

Throws: MappingException Invalid mapping information

XMLFieldDescriptorImpl

public XMLFieldDescriptorImpl(FieldDescriptor fieldDesc, String xmlName, NodeType nodeType)
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

Throws: MappingException Invalid mapping information

XMLFieldDescriptorImpl

public XMLFieldDescriptorImpl(FieldDescriptor fieldDesc, String xmlName, NodeType nodeType, NodeType primitiveNodeType)
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

Throws: MappingException Invalid mapping information

Method Detail

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.

getClassDescriptor

public ClassDescriptor getClassDescriptor()
Returns the class descriptor related to the field type. If the field type is a class for which a descriptor exists, this descriptor is returned. If the field type is a class for which no mapping is provided, null is returned.

Returns: The class descriptor of the field type, or null

getCollectionHandler

public CollectionHandler getCollectionHandler()
Return the collection handler of this field type. Returns null if the field is not a collection.

Returns: The collection handler

getConstructorArgumentIndex

public int getConstructorArgumentIndex()
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.

Returns: the index within the constructor argument array for this field.

getContainingClassDescriptor

public ClassDescriptor getContainingClassDescriptor()

Returns: the class which contains this field

getFieldName

public String getFieldName()
Returns the name of the field.

Returns: Field name

getFieldType

public Class getFieldType()
Returns the Java type of the field.

Returns: Field type

getHandler

public FieldHandler getHandler()
Returns the handler of the field. In order to persist or marshal a field descriptor will be associated with a handler.

Returns: The field handler

getLocationPath

public String getLocationPath()
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 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"

UNKNOWN: the "relative" XML path for the field being described.

getNameSpacePrefix

public String getNameSpacePrefix()
Return the "suggested" namespace prefix to use when marshalling as XML.

Returns: the "suggested" namespace prefix.

getNameSpaceURI

public String getNameSpaceURI()
Returns the namespace URI to be used when marshalling and unmarshalling as XML.

Returns: the namespace URI.

getNodeType

public NodeType getNodeType()

getProperty

public String getProperty(String propertyName)
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.

Parameters: propertyName the name of the property whose value should be returned.

Returns: the value of the property, or null.

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 Marshaller but not mandatory.

Returns: the prefix used in the QName value.

getSchemaType

public String getSchemaType()
Returns the XML Schema type of the value of the field described by this descriptor.

getValidator

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

Returns: the type validator for the described field

getXMLName

public String getXMLName()
Returns the XML Name for the field being described.

Returns: the XML name.

hashCode

public int hashCode()
Returns the hashCode for this XMLFieldDescriptor

hasNonDefaultMatching

protected boolean hasNonDefaultMatching()
Returns true if a call to #setMatches has been made with a non-null, or non-zero-length value. This method is used by the XML Mapping Loader

Returns: true if a call to #setMatches has been made with a legal value.

isConstructorArgument

public boolean isConstructorArgument()
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.

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

isContainer

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

Returns: true if the field is a container

isImmutable

public boolean isImmutable()
Returns true if the field type is immutable.

Returns: True if the field type is immutable

isIncremental

public boolean isIncremental()
Returns the incremental flag which when true indicates that this member may be safely added before the unmarshaller is finished unmarshalling it.

Returns: true if the Object can safely be added before the unmarshaller is finished unmarshalling the Object.

isMapped

public boolean isMapped()
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 #isMultivalued.

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

isMultivalued

public boolean isMultivalued()
Returns true if the Object described by this descriptor can contain more than one value

Returns: true if the Object described by this descriptor can contain more than one value

isNillable

public boolean isNillable()

isPrimitive

protected static boolean isPrimitive(Class type)
Returns true if the given class should be treated as a primitive type. This method will return true for all Java primitive types, the set of primitive object wrappers, as well as Strings.

Returns: true if the given class should be treated as a primitive type

isReference

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

isRequired

public boolean isRequired()
Returns true if the field described by this descriptor is a required field

Returns: true if the field described by this descriptor is a required field

isTransient

public boolean isTransient()
Returns true if the field is transient. Transient fields are never persisted or marshalled.

Returns: True if transient field

matches

public boolean matches(String xmlName)
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.

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.

matches

public boolean matches(String xmlName, String namespace)
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.

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.

setClassDescriptor

public void setClassDescriptor(XMLClassDescriptor classDescriptor)
Sets the XMLClassDescriptor for the described field

Parameters: classDescriptor the XMLClassDescriptor for the described field.

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.

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.

setContainingClassDescriptor

public void setContainingClassDescriptor(ClassDescriptor contClsDesc)
Set the class which contains this field

setHandler

public void setHandler(FieldHandler handler)
Sets the FieldHandler for the field being described by this FieldDescriptor

Parameters: handler the FieldHandler for the field being described by this FieldDescriptor

setImmutable

public void setImmutable(boolean immutable)
Sets the immutable flag which indicates that changes to this Field result in a new Object to be created, such as java.lang.String. It serves to identify fields which should not be constructed...until after all the data is available.

Parameters: immutable the boolean which if true indicated that this described field is immutable

setIncremental

public void setIncremental(boolean incremental)
Sets the incremental flag which indicates whether this member can be added before the unmarshaller is finished unmarshalling it.

Parameters: incremental the boolean which if true indicated that this member can safely be added before the unmarshaller is finished unmarshalling it.

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 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.

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.

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

setMultivalued

public void setMultivalued(boolean multivalued)

setNameSpacePrefix

public void setNameSpacePrefix(String nsPrefix)
Sets the namespace prefix used when marshalling as XML.

Parameters: nsPrefix the namespace prefix used when marshalling the "described" object

setNameSpaceURI

public void setNameSpaceURI(String nsURI)
Sets the namespace URI used when marshalling and unmarshalling as XML.

Parameters: nsURI the namespace URI used when marshalling and unmarshalling the "described" Object.

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.

setNodeType

public void setNodeType(NodeType nodeType)
Sets the XML node type for the described field

Parameters: nodeType the NodeType for the described field

setProperty

public void setProperty(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: getProperty

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

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.

setRequired

public void setRequired(boolean required)
Sets the whether or not the described field is required

Parameters: required the flag indicating whether or not the described field is required

setSchemaType

public void setSchemaType(String schemaType)
Sets the type of the XML Schema type of the value for the field being described.

Parameters: type the value type.

setTransient

public void setTransient(boolean isTransient)
Sets whether or not the describled field is transient

Parameters: isTransient the flag indicating whether or not the described field is "transient".

See Also: XMLFieldDescriptorImpl

setUseParentsNamespace

public void setUseParentsNamespace(boolean useParentsNamespace)
Sets whether or not the namespace for the parent "containing" class should be used during marshalling/unmarshalling when no specific namespace URI has been set for this field.

setValidator

public void setValidator(FieldValidator validator)

setXMLName

public void setXMLName(String xmlName)
Sets the xml name for the described field

Parameters: name the XML name for the described field

toString

public String toString()
Intalio Inc. (C) 1999-2004. All rights reserved http://www.intalio.com