org.apache.commons.betwixt
Class ElementDescriptor

java.lang.Object
  extended by org.apache.commons.betwixt.Descriptor
      extended by org.apache.commons.betwixt.NodeDescriptor
          extended by org.apache.commons.betwixt.ElementDescriptor

public class ElementDescriptor
extends NodeDescriptor

ElementDescriptor describes the XML elements to be created for a bean instance.

It contains AttributeDescriptor's for all it's attributes and ElementDescriptor's for it's child elements.

Author:
James Strachan, Martin van den Bemt

Constructor Summary
ElementDescriptor()
          Constructs an ElementDescriptor that refers to a primitive type.
ElementDescriptor(boolean primitiveType)
          Deprecated. 0.6 PrimitiveType property has been removed
ElementDescriptor(java.lang.String localName)
          Creates a ElementDescriptor with no namespace URI or prefix.
ElementDescriptor(java.lang.String localName, java.lang.String qualifiedName, java.lang.String uri)
          Creates a ElementDescriptor with namespace URI and qualified name
 
Method Summary
 void addAttributeDescriptor(AttributeDescriptor descriptor)
          Adds an attribute to the element this ElementDescriptor describes
 void addContentDescriptor(Descriptor descriptor)
          Adds a descriptor for child content.
 void addElementDescriptor(ElementDescriptor descriptor)
          Adds a descriptor for a child element.
 ElementDescriptor findParent(ElementDescriptor elementDescriptor)
          Finds the parent of the given descriptor.
 AttributeDescriptor getAttributeDescriptor(java.lang.String name)
          Returns an attribute descriptor with a given name or null.
 AttributeDescriptor[] getAttributeDescriptors()
          Returns the attribute descriptors for this element
protected  java.util.List getAttributeList()
          Lazily creates the mutable List.
 Descriptor[] getContentDescriptors()
          Returns descriptors for the child content of the element this describes.
protected  java.util.List getContentList()
          Lazily creates the mutable List of child content descriptors.
 Expression getContextExpression()
          Returns the expression used to evaluate the new context of this element.
 ElementDescriptor getElementDescriptor(java.lang.String name)
          Gets a child ElementDescriptor matching the given name if one exists.
 ElementDescriptor[] getElementDescriptors()
          Returns descriptors for the child elements of the element this describes.
protected  java.util.List getElementList()
          Lazily creates the mutable List of child elements.
 java.lang.Class getImplementationClass()
          Gets the class which should be used for instantiation.
 TextDescriptor getPrimaryBodyTextDescriptor()
          Gets the primary descriptor for body text of this element.
 boolean hasAttributes()
          Returns true if this element has AttributeDescriptors
 boolean hasChildren()
          Returns true if this element has child ElementDescriptors
 boolean hasContent()
          Returns true if this element has child content.
 boolean isCollective()
          Does this describe a collective?
 boolean isHollow()
          Is this decriptor hollow?
 boolean isPolymorphic()
          Is this a polymorphic element?
 boolean isPrimitiveType()
          Deprecated. 0.6 moved to a declarative style of descriptors where the alrogithmic should be done during introspection
 boolean isSimple()
          Is this a simple element?
 boolean isUseBindTimeTypeForMapping()
          Is the bind time type to be used to determine the mapping?
 boolean isWrapCollectionsInElement()
          Deprecated. 0.6 moved to a declarative style of descriptors where the alrogithmic should be done during introspection
 void removeAttributeDescriptor(AttributeDescriptor descriptor)
          Removes an attribute descriptor from this element descriptor.
 void removeElementDescriptor(ElementDescriptor descriptor)
          Removes an element descriptor from this element descriptor.
 void setAttributeDescriptors(AttributeDescriptor[] attributeDescriptors)
          Sets the AttributesDescriptors for this element.
 void setCollective(boolean isCollectiveType)
          Sets whether the element described is a collective.
 void setContentDescriptors(Descriptor[] contentDescriptors)
          Sets the descriptors for the child content of the element this describes.
 void setContextExpression(Expression contextExpression)
          Sets the expression used to evaluate the new context of this element
 void setElementDescriptors(ElementDescriptor[] elementDescriptors)
          Sets the descriptors for the child element of the element this describes.
 void setHollow(boolean isHollow)
          Sets whether this descriptor is hollow.
 void setImplementationClass(java.lang.Class implementationClass)
          Sets the class which should be used for instantiation.
 void setPrimitiveType(boolean primitiveType)
          Deprecated. 0.6 moved to a declarative style of descriptors where the alrogithmic should be done during introspection
 void setUseBindTimeTypeForMapping(boolean useBindTimeTypeForMapping)
          Sets whether the bind time type to be used to determine the mapping.
 void setWrapCollectionsInElement(boolean wrapCollectionsInElement)
          Deprecated. 0.6 moved to a declarative style of descriptors where the alrogithmic should be done during introspection
 java.lang.String toString()
          Returns something useful for logging.
 
Methods inherited from class org.apache.commons.betwixt.NodeDescriptor
getLocalName, getQualifiedName, getURI, setLocalName, setQualifiedName, setURI
 
Methods inherited from class org.apache.commons.betwixt.Descriptor
getOptions, getPropertyName, getPropertyType, getSingularPropertyType, getTextExpression, getUpdater, setOptions, setPropertyName, setPropertyType, setSingularPropertyType, setTextExpression, setUpdater
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ElementDescriptor

public ElementDescriptor()
Constructs an ElementDescriptor that refers to a primitive type.


ElementDescriptor

public ElementDescriptor(boolean primitiveType)
Deprecated. 0.6 PrimitiveType property has been removed

Base constructor.

Parameters:
primitiveType - if true, this element refers to a primitive type

ElementDescriptor

public ElementDescriptor(java.lang.String localName)
Creates a ElementDescriptor with no namespace URI or prefix.

Parameters:
localName - the (xml) local name of this node. This will be used to set both qualified and local name for this name.

ElementDescriptor

public ElementDescriptor(java.lang.String localName,
                         java.lang.String qualifiedName,
                         java.lang.String uri)
Creates a ElementDescriptor with namespace URI and qualified name

Parameters:
localName - the (xml) local name of this node
qualifiedName - the (xml) qualified name of this node
uri - the (xml) namespace prefix of this node
Method Detail

hasChildren

public boolean hasChildren()
Returns true if this element has child ElementDescriptors

Returns:
true if this element has child elements
See Also:
getElementDescriptors()

hasAttributes

public boolean hasAttributes()
Returns true if this element has AttributeDescriptors

Returns:
true if this element has attributes
See Also:
getAttributeDescriptors()

hasContent

public boolean hasContent()
Returns true if this element has child content.

Returns:
true if this element has either child mixed content or child elements
Since:
0.5
See Also:
getContentDescriptors()

isSimple

public boolean isSimple()

Is this a simple element?

A simple element is one without child elements or attributes. This corresponds to the simple type concept used in XML Schema. TODO: need to consider whether it's sufficient to calculate which are simple types (and so don't get IDs assigned etc).

Returns:
true if it is a SimpleType element

setWrapCollectionsInElement

public void setWrapCollectionsInElement(boolean wrapCollectionsInElement)
Deprecated. 0.6 moved to a declarative style of descriptors where the alrogithmic should be done during introspection

Sets whether Collection bean properties should wrap items in a parent element. In other words, should the mapping for bean properties which are Collections enclosed the item elements within a parent element. Normally only used when this describes a collection bean property.

Parameters:
wrapCollectionsInElement - true if the elements for the items in the collection should be contained in a parent element

isWrapCollectionsInElement

public boolean isWrapCollectionsInElement()
Deprecated. 0.6 moved to a declarative style of descriptors where the alrogithmic should be done during introspection

Returns true if collective bean properties should wrap the items in a parent element. In other words, should the mapping for bean properties which are Collections enclosed the item elements within a parent element. Normally only used when this describes a collection bean property.

Returns:
true if the elements for the items in the collection should be contained in a parent element

addAttributeDescriptor

public void addAttributeDescriptor(AttributeDescriptor descriptor)
Adds an attribute to the element this ElementDescriptor describes

Parameters:
descriptor - the AttributeDescriptor that will be added to the attributes associated with element this ElementDescriptor describes

removeAttributeDescriptor

public void removeAttributeDescriptor(AttributeDescriptor descriptor)
Removes an attribute descriptor from this element descriptor.

Parameters:
descriptor - the AttributeDescriptor to be removed, not null
Since:
0.8

getAttributeDescriptors

public AttributeDescriptor[] getAttributeDescriptors()
Returns the attribute descriptors for this element

Returns:
descriptors for the attributes of the element that this ElementDescriptor describes

getAttributeDescriptor

public AttributeDescriptor getAttributeDescriptor(java.lang.String name)
Returns an attribute descriptor with a given name or null.

Parameters:
name - to search for; will be checked against the attributes' qualified name.
Returns:
AttributeDescriptor with the given name, or null if no descriptor has that name
Since:
0.8

setAttributeDescriptors

public void setAttributeDescriptors(AttributeDescriptor[] attributeDescriptors)
Sets the AttributesDescriptors for this element. This sets descriptors for the attributes of the element describe by the ElementDescriptor.

Parameters:
attributeDescriptors - the AttributeDescriptor describe the attributes of the element described by this ElementDescriptor

addElementDescriptor

public void addElementDescriptor(ElementDescriptor descriptor)
Adds a descriptor for a child element.

Parameters:
descriptor - the ElementDescriptor describing the child element to add

removeElementDescriptor

public void removeElementDescriptor(ElementDescriptor descriptor)
Removes an element descriptor from this element descriptor.

Parameters:
descriptor - the ElementDescriptor that will be removed.
Since:
0.8

getElementDescriptors

public ElementDescriptor[] getElementDescriptors()
Returns descriptors for the child elements of the element this describes.

Returns:
the ElementDescriptor describing the child elements of the element that this ElementDescriptor describes

getElementDescriptor

public ElementDescriptor getElementDescriptor(java.lang.String name)
Gets a child ElementDescriptor matching the given name if one exists. Note that (so long as there are no better matches), a null name acts as a wildcard. In other words, an ElementDescriptor the first descriptor with a null name will match any name passed in, unless some other matches the name exactly.

Parameters:
name - the localname to be matched, not null
Returns:
the child ElementDescriptor with the given name if one exists, otherwise null

setElementDescriptors

public void setElementDescriptors(ElementDescriptor[] elementDescriptors)
Sets the descriptors for the child element of the element this describes. Also sets the child content descriptors for this element

Parameters:
elementDescriptors - the ElementDescriptors of the element that this describes

addContentDescriptor

public void addContentDescriptor(Descriptor descriptor)
Adds a descriptor for child content.

Parameters:
descriptor - the Descriptor describing the child content to add
Since:
0.5

getContentDescriptors

public Descriptor[] getContentDescriptors()
Returns descriptors for the child content of the element this describes.

Returns:
the Descriptor describing the child elements of the element that this ElementDescriptor describes
Since:
0.5

getPrimaryBodyTextDescriptor

public TextDescriptor getPrimaryBodyTextDescriptor()

Gets the primary descriptor for body text of this element. Betwixt collects all body text for any element together. This makes it rounds tripping difficult for beans that write more than one mixed content property.

The algorithm used in the default implementation is that the first TextDescriptor found amongst the descriptors is returned.

Returns:
the primary descriptor or null if this element has no mixed body content
Since:
0.5

setContentDescriptors

public void setContentDescriptors(Descriptor[] contentDescriptors)
Sets the descriptors for the child content of the element this describes.

Parameters:
contentDescriptors - the Descriptors of the element that this describes
Since:
0.5

getContextExpression

public Expression getContextExpression()
Returns the expression used to evaluate the new context of this element.

Returns:
the expression used to evaluate the new context of this element

setContextExpression

public void setContextExpression(Expression contextExpression)
Sets the expression used to evaluate the new context of this element

Parameters:
contextExpression - the expression used to evaluate the new context of this element

isPrimitiveType

public boolean isPrimitiveType()
Deprecated. 0.6 moved to a declarative style of descriptors where the alrogithmic should be done during introspection

Returns true if this element refers to a primitive type property

Returns:
whether this element refers to a primitive type (or property of a parent object)

setPrimitiveType

public void setPrimitiveType(boolean primitiveType)
Deprecated. 0.6 moved to a declarative style of descriptors where the alrogithmic should be done during introspection

Sets whether this element refers to a primitive type (or property of a parent object)

Parameters:
primitiveType - true if this element refers to a primitive type

getAttributeList

protected java.util.List getAttributeList()
Lazily creates the mutable List. This nullifies the attributeDescriptors array so that as items are added to the list the Array is ignored until it is explicitly asked for.

Returns:
list of AttributeDescriptors's describing the attributes of the element that this ElementDescriptor describes

getElementList

protected java.util.List getElementList()
Lazily creates the mutable List of child elements. This nullifies the elementDescriptors array so that as items are added to the list the Array is ignored until it is explicitly asked for.

Returns:
list of ElementDescriptor's describe the child elements of the element that this ElementDescriptor describes

getContentList

protected java.util.List getContentList()
Lazily creates the mutable List of child content descriptors. This nullifies the contentDescriptors array so that as items are added to the list the Array is ignored until it is explicitly asked for.

Returns:
list of Descriptor's describe the child content of the element that this Descriptor describes
Since:
0.5

getImplementationClass

public java.lang.Class getImplementationClass()
Gets the class which should be used for instantiation.

Returns:
the class which should be used for instantiation of beans mapped from this element, null if the standard class should be used

setImplementationClass

public void setImplementationClass(java.lang.Class implementationClass)
Sets the class which should be used for instantiation.

Parameters:
implementationClass - the class which should be used for instantiation or null to use the mapped type
Since:
0.5

isCollective

public boolean isCollective()
Does this describe a collective?


setCollective

public void setCollective(boolean isCollectiveType)
Sets whether the element described is a collective.

Parameters:
isCollectiveType -
Since:
0.7

findParent

public ElementDescriptor findParent(ElementDescriptor elementDescriptor)
Finds the parent of the given descriptor.

Parameters:
elementDescriptor - ElementDescriptor
Returns:
ElementDescriptor, not null

toString

public java.lang.String toString()
Returns something useful for logging.

Overrides:
toString in class java.lang.Object
Returns:
a string useful for logging

isHollow

public boolean isHollow()

Is this decriptor hollow?

A hollow descriptor is one which gives only the class that the subgraph is mapped to rather than describing the entire subgraph. A new XMLBeanInfo should be introspected and that used to describe the subgraph. A hollow descriptor should not have any child descriptors. TODO: consider whether a subclass would be better

Returns:
true if this is hollow

setHollow

public void setHollow(boolean isHollow)
Sets whether this descriptor is hollow. A hollow descriptor is one which gives only the class that the subgraph is mapped to rather than describing the entire subgraph. A new XMLBeanInfo should be introspected and that used to describe the subgraph. A hollow descriptor should not have any child descriptors. TODO: consider whether a subclass would be better

Parameters:
isHollow - true if this is hollow

isUseBindTimeTypeForMapping

public boolean isUseBindTimeTypeForMapping()

Is the bind time type to be used to determine the mapping?

The mapping for an object property value can either be the introspection time type (based on the logical type of the property) or the bind time type (based on the type of the actual instance).

Returns:
true if the bind time type is to be used to determine the mapping, false if the introspection time type is to be used
Since:
0.7

setUseBindTimeTypeForMapping

public void setUseBindTimeTypeForMapping(boolean useBindTimeTypeForMapping)

Sets whether the bind time type to be used to determine the mapping. The mapping for an object property value can either be the introspection time type (based on the logical type of the property) or the bind time type (based on the type of the actual instance).

Note: this property is write once, read many. So, the first time that this method is called the value will be set but subsequent calls will be ignored.

Parameters:
useBindTimeTypeForMapping - true if the bind time type is to be used to determine the mapping, false if the introspection time type is to be used
Since:
0.7

isPolymorphic

public boolean isPolymorphic()

Is this a polymorphic element?

A polymorphic element's name is not fixed at introspection time and it's resolution is postponed to bind time.

Returns:
true if NodeDescriptor.getQualifiedName() is null, false otherwise
Since:
0.7


Copyright 2002-2008 The Apache Software Foundation. All Rights Reserved.