org.apache.commons.betwixt
Class ElementDescriptor

java.lang.Object
  org.apache.commons.betwixt.Descriptor
      org.apache.commons.betwixt.NodeDescriptor
          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