public class Element
extends java.lang.Object
The various setter methods provided by this class return this
so setter invocations can be chained, as in the following example:
Element who = new Element(KEY) .setAttributeValue(ATTR_KEY, "value") .addElement( new Element(EXT_KEY_NOEXT) .setTextValue("yolk"));
Subclasses are expected to follow the same model for any setter methods they provide.
Constructor and Description |
---|
Element(ElementKey<?,?> elementKey)
Construct element and associate with a key.
|
Element(ElementKey<?,?> elementKey,
Element source)
Copy constructor that initializes a new Element instance to be a wrapper
around another element instance.
|
Element(QName qName)
Construct a generic undeclared element with the specified qualified name.
|
Modifier and Type | Method and Description |
---|---|
Element |
addElement(Element element)
Add a child element, using the key of the child element as the key into
this element's children.
|
Element |
addElement(ElementKey<?,?> key,
Element element)
Add a child element with the given key.
|
Element |
addElement(QName id,
Element element)
Add a child element with the given ID.
|
void |
clear()
Clears internal state of all attributes, child elements, and text content.
|
static <E extends Element> |
createElement(ElementKey<?,E> key)
Helper method that constructs a new
Element instance of the type
defined by the type parameter E . |
static <E extends Element> |
createElement(ElementKey<?,E> key,
Element source)
Helper method that constructs a new
Element instance of the type
defined by the type parameter E . |
boolean |
equals(java.lang.Object obj) |
int |
getAttributeCount()
Returns the number of attributes present on this element.
|
java.util.Iterator<Attribute> |
getAttributeIterator()
Returns an iterator over all attributes on this element.
|
java.util.Iterator<Attribute> |
getAttributeIterator(ElementMetadata<?,?> metadata)
Returns an iterator over the attributes of this element with a well-defined
iteration order based on the metadata.
|
<T> T |
getAttributeValue(AttributeKey<T> key)
Returns the attribute value cast to the appropriate type, based on the
given key.
|
java.lang.Object |
getAttributeValue(QName id)
Get the value of an attribute by id.
|
static ElementKey<?,?> |
getDefaultKey(java.lang.Class<? extends Element> type)
Returns the default
ElementKey for an Element type. |
<D,T extends Element> |
getElement(ElementKey<D,T> childKey)
Get child element matching the specified key.
|
Element |
getElement(QName id)
Get a child element matching the specified qualified name.
|
int |
getElementCount()
Returns the number of child elements present on this element.
|
QName |
getElementId()
Get the id of this element.
|
java.util.Iterator<Element> |
getElementIterator()
Returns an iterator over all child elements of this element.
|
java.util.Iterator<Element> |
getElementIterator(ElementMetadata<?,?> metadata)
Returns an iterator over all child elements with a well-defined iteration
order based on this metadata.
|
ElementKey<?,?> |
getElementKey()
Returns the key to this element.
|
<T extends Element> |
getElements(ElementKey<?,T> key)
Get child elements matching the specified key.
|
java.util.List<Element> |
getElements(QName id)
Returns an immutable list of elements matching the given id.
|
<T extends Element> |
getElementSet(ElementKey<?,T> key)
Get child elements matching the specified key.
|
java.util.Set<Element> |
getElementSet(QName id)
Get child elements matching the specified id.
|
<V> V |
getElementValue(ElementKey<V,? extends Element> key)
Convenience method to return child element's text node cast to
the specified type.
|
java.lang.Object |
getElementValue(QName id)
Convenience method to return child element's text node as an object.
|
java.lang.Object |
getTextValue()
Returns the untyped element value or null if it has no value.
|
<V> V |
getTextValue(ElementKey<V,?> key)
Returns the element value adapted to the key's datatype.
|
boolean |
hasAttribute(AttributeKey<?> childKey)
Returns true if the element has an attribute with the given key.
|
boolean |
hasAttribute(QName id)
Returns true if the element has an attribute with the given id.
|
boolean |
hasElement(ElementKey<?,?> childKey)
Returns true if the element has child element(s) with the given key.
|
boolean |
hasElement(QName id)
Returns true if the element has child element(s) with the given id.
|
int |
hashCode() |
boolean |
hasTextValue() |
boolean |
isLocked()
Returns true if this element has been locked using
lock() . |
Element |
lock()
Locks this element.
|
java.lang.Object |
removeAttribute(AttributeKey<?> key)
Deprecated.
use removeAttributeValue instead.
|
java.lang.Object |
removeAttribute(QName id)
Deprecated.
use removeAttributeValue instead.
|
java.lang.Object |
removeAttributeValue(AttributeKey<?> key)
Remove attribute (if present).
|
java.lang.Object |
removeAttributeValue(QName id)
Remove attribute (if present).
|
boolean |
removeElement(Element element)
Remove a single child element from this element.
|
Element |
removeElement(ElementKey<?,?> childKey)
Remove child element(s) of a given name.
|
boolean |
removeElement(ElementKey<?,?> childKey,
Element element)
Remove a single child element from this element.
|
Element |
removeElement(QName id)
Remove child element(s) of a given name.
|
boolean |
replaceElement(Element toRemove,
Element toAdd)
Replace one element with another.
|
Element |
resolve(ElementMetadata<?,?> metadata)
Resolve the state of all elements in the tree, rooted at this
element, against the metadata.
|
Element |
resolve(ElementMetadata<?,?> metadata,
ValidationContext vc)
Resolve this element's state against the metadata.
|
Element |
setAttributeValue(AttributeKey<?> key,
java.lang.Object attrValue)
Add attribute by value.
|
Element |
setAttributeValue(QName id,
java.lang.Object attrValue)
Add attribute by id and value.
|
Element |
setElement(Element element)
Sets a child element to the given value.
|
Element |
setElement(ElementKey<?,?> key,
Element element)
Sets the value of the child element(s) with the
key . |
Element |
setElement(QName id,
Element element)
Sets the value of the child element(s) with the given id.
|
Element |
setTextValue(java.lang.Object newValue)
Sets the value of the element and returns the element to allow chaining.
|
java.lang.String |
toString() |
void |
visit(ElementVisitor ev,
ElementMetadata<?,?> meta)
Visits the element using the specified
ElementVisitor and metadata. |
public Element(ElementKey<?,?> elementKey)
elementKey
- the key to this element, contains the ID and datatype.public Element(QName qName)
qName
- qualified namepublic Element(ElementKey<?,?> elementKey, Element source)
elementKey
- the element key to associate with the copy.source
- the element to copy data from.public static ElementKey<?,?> getDefaultKey(java.lang.Class<? extends Element> type)
ElementKey
for an Element
type.type
- element typepublic final boolean isLocked()
lock()
. Once an
element has been locked it cannot be unlocked.public Element lock()
public ElementKey<?,?> getElementKey()
public QName getElementId()
public java.util.Iterator<Attribute> getAttributeIterator()
public java.util.Iterator<Attribute> getAttributeIterator(ElementMetadata<?,?> metadata)
metadata
- the element metadata to use for iterationpublic int getAttributeCount()
public boolean hasAttribute(QName id)
public boolean hasAttribute(AttributeKey<?> childKey)
public java.lang.Object getAttributeValue(QName id)
public <T> T getAttributeValue(AttributeKey<T> key)
T
- return typekey
- the attribute key to use to cast the attribute valuejava.lang.IllegalArgumentException
- if the value cannot be converted to the
key typepublic Element setAttributeValue(QName id, java.lang.Object attrValue)
null
this is
equivalent to removing the attribute with the given id.public Element setAttributeValue(AttributeKey<?> key, java.lang.Object attrValue)
null
the value will be
removed.key
- attribute key that is being addedattrValue
- attribute value or null
to remove@Deprecated public java.lang.Object removeAttribute(QName id)
public java.lang.Object removeAttributeValue(QName id)
id
- the qualified name of the attribute.@Deprecated public java.lang.Object removeAttribute(AttributeKey<?> key)
public java.lang.Object removeAttributeValue(AttributeKey<?> key)
key
- the key of the attribute.public java.util.Iterator<Element> getElementIterator()
public java.util.Iterator<Element> getElementIterator(ElementMetadata<?,?> metadata)
metadata
- the metadata to use for iterationpublic int getElementCount()
public Element getElement(QName id)
id
- the qualified name of the child to retrievenull
if none was foundjava.lang.IllegalArgumentException
- if the id referenced a repeating elementpublic <D,T extends Element> T getElement(ElementKey<D,T> childKey)
T
- the type of element to returnchildKey
- the metadata key for the child element to retrievenull
if none was foundjava.lang.IllegalArgumentException
- if the key referenced a repeating elementpublic java.lang.Object getElementValue(QName id)
null
if child doesn't exist or child does not have a text
node.public <V> V getElementValue(ElementKey<V,? extends Element> key)
null
if child element does
not exist or has no text node.V
- child element's text node typekey
- identifying the child element.V
,
or null
if child element does not exist or has no
text nodepublic boolean hasElement(QName id)
public boolean hasElement(ElementKey<?,?> childKey)
public java.util.List<Element> getElements(QName id)
public <T extends Element> java.util.List<T> getElements(ElementKey<?,T> key)
addElement(Element)
method should be used. If the elements at the given key are not of the
correct type an IllegalArgumentException
will be thrown.key
- child key to lookup child elements based on.public java.util.Set<Element> getElementSet(QName id)
addElement(Element)
method
should be used.public <T extends Element> java.util.Set<T> getElementSet(ElementKey<?,T> key)
addElement(Element)
method should be used. If the elements at the given key are not of the
correct type an IllegalArgumentException
will be thrown.key
- the child key to lookup child elements based on.public Element setElement(QName id, Element element)
null
, this is equivalent to removeElement(QName)
.public Element setElement(Element element)
setElement(element.getElementKey(), element);
.java.lang.NullPointerException
- if element is null.public Element setElement(ElementKey<?,?> key, Element element)
key
. The
element
will replace all existing elements with the same key. If
element is null, this is equivalent to removeElement(ElementKey)
.key
- the key for the child elementelement
- child elementpublic Element addElement(Element element)
element
- child elementjava.lang.NullPointerException
- if element is null.public Element addElement(QName id, Element element)
setElement(QName, Element)
instead.id
- the qualified name to use for the childelement
- child elementjava.lang.NullPointerException
- if element is null.public Element addElement(ElementKey<?,?> key, Element element)
setElement(ElementKey, Element)
instead.key
- the key of the child.element
- child elementpublic Element removeElement(QName id)
id
- the id of the child element(s) to remove.public Element removeElement(ElementKey<?,?> childKey)
childKey
- key of the element(s) to remove.public boolean removeElement(Element element)
element
- the child element to remove.public boolean removeElement(ElementKey<?,?> childKey, Element element)
childKey
- the key for the child element to remove.element
- the child element to remove.public boolean replaceElement(Element toRemove, Element toAdd)
toRemove
- element to remove.toAdd
- element to add.public void clear()
public java.lang.Object getTextValue()
public <V> V getTextValue(ElementKey<V,?> key)
V
- data type of the key.key
- the element key used to convert the value.public Element setTextValue(java.lang.Object newValue)
newValue
- element's valuejava.lang.IllegalStateException
- if the element is immutablejava.lang.IllegalArgumentException
- if the object is of an invalid type or
if this element does not allow a valuepublic boolean hasTextValue()
public Element resolve(ElementMetadata<?,?> metadata) throws ContentValidationException
metadata
- the metadata to resolve against.ContentValidationException
- if tree cannot be resolvedpublic Element resolve(ElementMetadata<?,?> metadata, ValidationContext vc)
vc
- validation contextpublic void visit(ElementVisitor ev, ElementMetadata<?,?> meta)
ElementVisitor
and metadata.
A null
metadata indicates that the element is undeclared, and
child elements will be visited in the order they were added to the element.ev
- the element visitor instance to use.meta
- the metadata for the element, or null
for undeclared
metadata.ElementVisitor.StoppedException
- if traversal must be stoppedpublic static <E extends Element> E createElement(ElementKey<?,E> key) throws ContentCreationException
Element
instance of the type
defined by the type parameter E
.key
- the element key to create the element fromContentCreationException
- if content cannot be createdpublic static <E extends Element> E createElement(ElementKey<?,E> key, Element source) throws ContentCreationException
Element
instance of the type
defined by the type parameter E
.key
- the element key to create the element for.source
- the source element to use, or null if a fresh instance should
be created.ContentCreationException
- if content cannot be createdpublic int hashCode()
hashCode
in class java.lang.Object
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object