public class

Element

extends Object
java.lang.Object
   ↳ com.google.gdata.model.Element
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Data element in an instance document. Contains attributes, child elements, and a text node.

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.

See Also

Summary

Fields
private static final Logger LOGGER
private final ElementKey<?, ?> key The element key associated with this element.
private final Element.ElementState state The state of this element, contains all actual data.
Public Constructors
Element(ElementKey<?, ?> elementKey)
Construct element and associate with a key.
Element(QName qName)
Construct a generic undeclared element with the specified qualified name.
Element(ElementKey<?, ?> elementKey, Element source)
Copy constructor that initializes a new Element instance to be a wrapper around another element instance.
Public Methods
Element addElement(QName id, Element element)
Add a child element with the given ID.
Element addElement(ElementKey<?, ?> key, Element element)
Add a child element with the given key.
Element addElement(Element element)
Add a child element, using the key of the child element as the key into this element's children.
void clear()
Clears internal state of all attributes, child elements, and text content.
static <E extends Element> E createElement(ElementKey<?, E> key, Element source)
Helper method that constructs a new Element instance of the type defined by the type parameter E.
static <E extends Element> E createElement(ElementKey<?, E> key)
Helper method that constructs a new Element instance of the type defined by the type parameter E.
boolean equals(Object obj)
int getAttributeCount()
Returns the number of attributes present on this element.
Iterator<Attribute> getAttributeIterator(ElementMetadata<?, ?> metadata)
Returns an iterator over the attributes of this element with a well-defined iteration order based on the metadata.
Iterator<Attribute> getAttributeIterator()
Returns an iterator over all attributes on this element.
Object getAttributeValue(QName id)
Get the value of an attribute by id.
<T> T getAttributeValue(AttributeKey<T> key)
Returns the attribute value cast to the appropriate type, based on the given key.
static ElementKey<?, ?> getDefaultKey(Class<? extends Element> type)
Returns the default ElementKey for an Element type.
<D, T extends Element> T 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.
Iterator<Element> getElementIterator()
Returns an iterator over all child elements of this element.
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> Set<T> getElementSet(ElementKey<?, T> key)
Get child elements matching the specified key.
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.
Object getElementValue(QName id)
Convenience method to return child element's text node as an object.
List<Element> getElements(QName id)
Returns an immutable list of elements matching the given id.
<T extends Element> List<T> getElements(ElementKey<?, T> key)
Get child elements matching the specified key.
<V> V getTextValue(ElementKey<V, ?> key)
Returns the element value adapted to the key's datatype.
Object getTextValue()
Returns the untyped element value or null if it has no value.
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(QName id)
Returns true if the element has child element(s) with the given id.
boolean hasElement(ElementKey<?, ?> childKey)
Returns true if the element has child element(s) with the given key.
boolean hasTextValue()
int hashCode()
final boolean isLocked()
Returns true if this element has been locked using lock().
Element lock()
Locks this element.
Object removeAttribute(AttributeKey<?> key)
This method is deprecated. use removeAttributeValue instead.
Object removeAttribute(QName id)
This method is deprecated. use removeAttributeValue instead.
Object removeAttributeValue(AttributeKey<?> key)
Remove attribute (if present).
Object removeAttributeValue(QName id)
Remove attribute (if present).
boolean removeElement(Element element)
Remove a single child element from this element.
Element removeElement(QName id)
Remove child element(s) of a given name.
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.
boolean replaceElement(Element toRemove, Element toAdd)
Replace one element with another.
Element resolve(ElementMetadata<?, ?> metadata, ValidationContext vc)
Resolve this element's state against the metadata.
Element resolve(ElementMetadata<?, ?> metadata)
Resolve the state of all elements in the tree, rooted at this element, against the metadata.
Element setAttributeValue(AttributeKey<?> key, Object attrValue)
Add attribute by value.
Element setAttributeValue(QName id, Object attrValue)
Add attribute by id and value.
Element setElement(Element element)
Sets a child element to the given value.
Element setElement(QName id, Element element)
Sets the value of the child element(s) with the given id.
Element setElement(ElementKey<?, ?> key, Element element)
Sets the value of the child element(s) with the key.
Element setTextValue(Object newValue)
Sets the value of the element and returns the element to allow chaining.
String toString()
void visit(ElementVisitor ev, ElementMetadata<?, ?> meta)
Visits the element using the specified ElementVisitor and metadata.
Protected Methods
Element adapt(Element source, ElementMetadata<?, ?> sourceMeta, String kind)
Adapts an element based on a key.
<T extends Element> T adapt(ElementKey<?, T> key, Element source)
Adapts an element based on a different key.
static boolean eq(Object o1, Object o2)
Helper method to check for equality between two object, including null checks.
Element narrow(ElementMetadata<?, ?> metadata, ValidationContext vc)
Narrow down element's type to the most specific one possible.
boolean sameClassAs(Object o)
void validate(ElementMetadata<?, ?> metadata, ValidationContext vc)
Validate the element using the given metadata, and placing any errors into the validation context.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

private static final Logger LOGGER

private final ElementKey<?, ?> key

The element key associated with this element.

private final Element.ElementState state

The state of this element, contains all actual data. This allows shallow copies to be very efficient.

Public Constructors

public Element (ElementKey<?, ?> elementKey)

Construct element and associate with a key.

Parameters
elementKey The key to this element, contains the ID and datatype.

public Element (QName qName)

Construct a generic undeclared element with the specified qualified name.

Parameters
qName Qualified name

public Element (ElementKey<?, ?> elementKey, Element source)

Copy constructor that initializes a new Element instance to be a wrapper around another element instance. The element will use the given element as its source for any content.

Parameters
elementKey The element key to associate with the copy.
source The element to copy data from.

Public Methods

public Element addElement (QName id, Element element)

Add a child element with the given ID. This will add the given element to the end of the collection of elements with the same ID. If you want to replace any existing elements use setElement(QName, Element) instead.

Parameters
id The qualified name to use for the child
element Child element
Returns
  • this element for chaining
Throws
NullPointerException if element is null.

public Element addElement (ElementKey<?, ?> key, Element element)

Add a child element with the given key. This will add the given element to the end of the collection of elements with the same ID. If you want to replace any existing elements use setElement(ElementKey, Element) instead.

Parameters
key The key of the child.
element Child element
Returns
  • this element for chaining

public Element addElement (Element element)

Add a child element, using the key of the child element as the key into this element's children.

Parameters
element Child element
Returns
  • this element for chaining
Throws
NullPointerException if element is null.

public void clear ()

Clears internal state of all attributes, child elements, and text content.

public static E createElement (ElementKey<?, E> key, Element source)

Helper method that constructs a new Element instance of the type defined by the type parameter E.

Parameters
key The element key to create the element for.
source The source element to use, or null if a fresh instance should be created.
Returns
  • element that was created
Throws
ContentCreationException if content cannot be created

public static E createElement (ElementKey<?, E> key)

Helper method that constructs a new Element instance of the type defined by the type parameter E.

Parameters
key The element key to create the element from
Returns
  • element that was created
Throws
ContentCreationException if content cannot be created

public boolean equals (Object obj)

Parameters
obj

public int getAttributeCount ()

Returns the number of attributes present on this element.

Returns
  • count of attributes

public Iterator<Attribute> getAttributeIterator (ElementMetadata<?, ?> metadata)

Returns an iterator over the attributes of this element with a well-defined iteration order based on the metadata. All declared attributes are returned first, in the order of declaration, followed by undeclared attributes in the order in which they were added to this element. If the metadata declares virtual attributes, those attributes will be included in the iterator, likewise any attributes which are hidden will be excluded.

Parameters
metadata The element metadata to use for iteration
Returns
  • an iterator over the attributes of this element

public Iterator<Attribute> getAttributeIterator ()

Returns an iterator over all attributes on this element.

public Object getAttributeValue (QName id)

Get the value of an attribute by id.

Parameters
id

public T getAttributeValue (AttributeKey<T> key)

Returns the attribute value cast to the appropriate type, based on the given key.

Parameters
key The attribute key to use to cast the attribute value
Returns
  • typed attribute value
Throws
IllegalArgumentException if the value cannot be converted to the key type

public static ElementKey<?, ?> getDefaultKey (Class<? extends Element> type)

Returns the default ElementKey for an Element type.

Parameters
type Element type
Returns
  • default element key for type

public T getElement (ElementKey<D, T> childKey)

Get child element matching the specified key. Will try to adapt the element to the given key if it is not already an instance of the requested class. This will fail with an exception if the adaptation was not valid.

Parameters
childKey The metadata key for the child element to retrieve
Returns
  • child element, or null if none was found
Throws
IllegalArgumentException if the key referenced a repeating element

public Element getElement (QName id)

Get a child element matching the specified qualified name.

Parameters
id The qualified name of the child to retrieve
Returns
  • the matching child element, or null if none was found
Throws
IllegalArgumentException if the id referenced a repeating element

public int getElementCount ()

Returns the number of child elements present on this element.

Returns
  • number of elements.

public QName getElementId ()

Get the id of this element.

public Iterator<Element> getElementIterator ()

Returns an iterator over all child elements of this element.

public Iterator<Element> getElementIterator (ElementMetadata<?, ?> metadata)

Returns an iterator over all child elements with a well-defined iteration order based on this metadata. All declared elements are returned first, in the order of declaration, followed by undeclared elements in the order in which they were added to this element. If the metadata declares virtual elements, those elements will be included in the iterator, likewise any elements which are hidden will be excluded.

Parameters
metadata The metadata to use for iteration
Returns
  • iterator over the child elements of the element

public ElementKey<?, ?> getElementKey ()

Returns the key to this element.

public Set<T> getElementSet (ElementKey<?, T> key)

Get child elements matching the specified key. This set cannot be used to add new child elements, instead the addElement(Element) method should be used. If the elements at the given key are not of the correct type an IllegalArgumentException will be thrown.

Parameters
key The child key to lookup child elements based on.
Returns
  • elements children, or an empty set if there are no children with the given key's id.

public Set<Element> getElementSet (QName id)

Get child elements matching the specified id. This set cannot be used to add new child elements, instead the addElement(Element) method should be used.

Parameters
id

public V getElementValue (ElementKey<V, ? extends Element> key)

Convenience method to return child element's text node cast to the specified type. Returns null if child element does not exist or has no text node.

Parameters
key Identifying the child element.
Returns
  • child element's text node, cast to type V, or null if child element does not exist or has no text node

public Object getElementValue (QName id)

Convenience method to return child element's text node as an object. Returns null if child doesn't exist or child does not have a text node.

Parameters
id

public List<Element> getElements (QName id)

Returns an immutable list of elements matching the given id.

Parameters
id

public List<T> getElements (ElementKey<?, T> key)

Get child elements matching the specified key. This list cannot be used to add new child elements, instead the addElement(Element) method should be used. If the elements at the given key are not of the correct type an IllegalArgumentException will be thrown.

Parameters
key Child key to lookup child elements based on.
Returns
  • element's children, or an empty list if there are no children with the given key's id.

public V getTextValue (ElementKey<V, ?> key)

Returns the element value adapted to the key's datatype.

Parameters
key The element key used to convert the value.
Returns
  • typed element value.

public Object getTextValue ()

Returns the untyped element value or null if it has no value.

Returns
  • untyped element value

public boolean hasAttribute (AttributeKey<?> childKey)

Returns true if the element has an attribute with the given key.

Parameters
childKey

public boolean hasAttribute (QName id)

Returns true if the element has an attribute with the given id.

Parameters
id

public boolean hasElement (QName id)

Returns true if the element has child element(s) with the given id.

Parameters
id

public boolean hasElement (ElementKey<?, ?> childKey)

Returns true if the element has child element(s) with the given key.

Parameters
childKey

public boolean hasTextValue ()

Returns
  • true if element has a text node value

public int hashCode ()

public final boolean isLocked ()

Returns true if this element has been locked using lock(). Once an element has been locked it cannot be unlocked.

public Element lock ()

Locks this element. A locked element cannot have any changes made to its content or its attributes or child elements. This will also lock all attributes and child elements as well. Once this method has been called, this element can be safely published to other threads.

public Object removeAttribute (AttributeKey<?> key)

This method is deprecated.
use removeAttributeValue instead.

Parameters
key

public Object removeAttribute (QName id)

This method is deprecated.
use removeAttributeValue instead.

Parameters
id

public Object removeAttributeValue (AttributeKey<?> key)

Remove attribute (if present).

Parameters
key The key of the attribute.
Returns
  • this element

public Object removeAttributeValue (QName id)

Remove attribute (if present).

Parameters
id The qualified name of the attribute.
Returns
  • this element

public boolean removeElement (Element element)

Remove a single child element from this element. This method returns true if the element was found and removed, or false if it was not. It uses identity and not equality to find a match.

Parameters
element The child element to remove.
Returns
  • true if the child element was removed from this element.

public Element removeElement (QName id)

Remove child element(s) of a given name. All elements with the given id will be removed.

Parameters
id The id of the child element(s) to remove.
Returns
  • this element for chaining.

public Element removeElement (ElementKey<?, ?> childKey)

Remove child element(s) of a given name. All elements with the same ID as the given key will be removed.

Parameters
childKey Key of the element(s) to remove.
Returns
  • this element for chaining.

public boolean removeElement (ElementKey<?, ?> childKey, Element element)

Remove a single child element from this element. This method returns true if the element was found and removed, or false if it was not. It uses identity and not equality to find a match.

Parameters
childKey The key for the child element to remove.
element The child element to remove.
Returns
  • true if the child element was removed from this element.

public boolean replaceElement (Element toRemove, Element toAdd)

Replace one element with another. If the element to add has the same id as the one that is being replaced, it will be switch in place, maintaining order in repeating or undeclared elements.

Parameters
toRemove Element to remove.
toAdd Element to add.
Returns
  • true if the replacement succeeded.

public Element resolve (ElementMetadata<?, ?> metadata, ValidationContext vc)

Resolve this element's state against the metadata. Accumulates errors in caller's validation context.

Parameters
metadata
vc Validation context
Returns
  • the narrowed element if narrowing took place.

public Element resolve (ElementMetadata<?, ?> metadata)

Resolve the state of all elements in the tree, rooted at this element, against the metadata. Throws an exception if the tree cannot be resolved.

Parameters
metadata The metadata to resolve against.
Returns
  • the narrowed element if narrowing took place
Throws
ContentValidationException if tree cannot be resolved

public Element setAttributeValue (AttributeKey<?> key, Object attrValue)

Add attribute by value. If the value is null the value will be removed.

Parameters
key Attribute key that is being added
attrValue Attribute value or null to remove

public Element setAttributeValue (QName id, Object attrValue)

Add attribute by id and value. If the value is null this is equivalent to removing the attribute with the given id.

Parameters
id
attrValue

public Element setElement (Element element)

Sets a child element to the given value. Uses the element key of the element as the key. This is equivalent to calling setElement(element.getElementKey(), element);.

Parameters
element
Throws
NullPointerException if element is null.

public Element setElement (QName id, Element element)

Sets the value of the child element(s) with the given id. The given element will replace all existing elements at the given id. If the given element is null, this is equivalent to removeElement(QName).

Parameters
id
element

public Element setElement (ElementKey<?, ?> key, Element element)

Sets the value of the child element(s) with the key. The element will replace all existing elements with the same key. If element is null, this is equivalent to removeElement(ElementKey).

Parameters
key The key for the child element
element Child element
Returns
  • this element for chaining

public Element setTextValue (Object newValue)

Sets the value of the element and returns the element to allow chaining.

Parameters
newValue Element's value
Returns
  • this element
Throws
IllegalStateException if the element is immutable
IllegalArgumentException if the object is of an invalid type or if this element does not allow a value

public String toString ()

public void visit (ElementVisitor ev, ElementMetadata<?, ?> meta)

Visits the element using the specified 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.

Parameters
ev The element visitor instance to use.
meta The metadata for the element, or null for undeclared metadata.
Throws
ElementVisitor.StoppedException if traversal must be stopped

Protected Methods

protected Element adapt (Element source, ElementMetadata<?, ?> sourceMeta, String kind)

Adapts an element based on a key. This will find an adaptation in the metadata and adapt to that metadata type (and element type). If no adaptation is found this will return the source element.

Parameters
source The element we are narrowing from.
sourceMeta The source metadata to adapt from.
kind The kind name to lookup the adaptation for.
Returns
  • the adapted element if one was found.

protected T adapt (ElementKey<?, T> key, Element source)

Adapts an element based on a different key. If the key represents a more narrow type than 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.

Parameters
key The element key to adapt to.
source The element we are adapting from.
Returns
  • the adapted element if one was found.
Throws
ContentCreationException if the metadata cannot be used to adapt.
NullPointerException if meta is null.

protected static boolean eq (Object o1, Object o2)

Helper method to check for equality between two object, including null checks.

Parameters
o1 Object 1 or null
o2 Object 2 or null
Returns
  • true if the specified arguments are equal, or both null

protected Element narrow (ElementMetadata<?, ?> metadata, ValidationContext vc)

Narrow down element's type to the most specific one possible.

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.

Parameters
metadata The element metadata to narrow to.
vc Validation context
Returns
  • element narrowed down to the most specific type

protected boolean sameClassAs (Object o)

Parameters
o Given object
Returns
  • true if the given object is not null and is the same concrete class as this one

protected void validate (ElementMetadata<?, ?> metadata, ValidationContext vc)

Validate the element using the given metadata, and placing any errors into the validation context. The default behavior is to use the metadata validation, subclasses may override this to add their own validation. If the metadata is null (undeclared), no validation will be performed.

Parameters
metadata
vc