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 |
---|---|
protected Element |
adapt(Element source,
ElementMetadata<?,?> sourceMeta,
java.lang.String kind)
Adapts an element based on a key.
|
protected <T extends Element> |
adapt(ElementKey<?,T> key,
Element source)
Adapts an element based on a different key.
|
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 . |
protected static boolean |
eq(java.lang.Object o1,
java.lang.Object o2)
Helper method to check for equality between two object, including null
checks.
|
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.
|
protected Element |
narrow(ElementMetadata<?,?> metadata,
ValidationContext vc)
Narrow down element's type to the most specific one possible.
|
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.
|
protected boolean |
sameClassAs(java.lang.Object o) |
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() |
protected void |
validate(ElementMetadata<?,?> metadata,
ValidationContext vc)
Validate the element using the given metadata, and placing any errors into
the validation context.
|
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 contextprotected Element narrow(ElementMetadata<?,?> metadata, ValidationContext vc)
Any validation errors discovered during narrowing are accumulated in the validation context.
Default action is to not do anything with current element. Subclasses may override this function to narrow the type in some custom fashion.
metadata
- the element metadata to narrow to.vc
- validation contextprotected Element adapt(Element source, ElementMetadata<?,?> sourceMeta, java.lang.String kind)
source
- the element we are narrowing from.sourceMeta
- the source metadata to adapt from.kind
- the kind name to lookup the adaptation for.protected <T extends Element> T adapt(ElementKey<?,T> key, Element source) throws ContentCreationException
source
, an instance of the more narrow
type will be returned, containing the same information as the source. If
the source is null
, a null instance of T
will be returned.T
- the type of element to adapt to.key
- the element key to adapt to.source
- the element we are adapting from.ContentCreationException
- if the metadata cannot be used to adapt.java.lang.NullPointerException
- if meta is null.protected void validate(ElementMetadata<?,?> metadata, ValidationContext vc)
public 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 stoppedprotected boolean sameClassAs(java.lang.Object o)
o
- given objectprotected static boolean eq(java.lang.Object o1, java.lang.Object o2)
o1
- object 1 or null
o2
- object 2 or null
public 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