com.google.gdata.model
Class Element

java.lang.Object
  com.google.gdata.model.Element

Direct Known Subclasses:

Accept, AdditionalName, Agent, AttendeeStatus, AttendeeType, BatchId, BatchInterrupted, BatchOperation, BatchStatus, Categories, Category, City, Collection, Comments, Content, Control, Country, CreateId, CustomProperty, Deleted, Draft, Edited, Email, Entry, EntryLink, EventStatus, ExtendedProperty, FamilyName, FeedLink, FormattedAddress, FullName, GeoPt, GivenName, HouseName, Im, LastViewed, Link, Money, Name, NamePrefix, NameSuffix, Neighborhood, Ordering, Organization, OrgDepartment, OrgJobDescription, OrgName, OrgSymbol, OrgTitle, OriginalEvent, Person, PhoneNumber, PoBox, PostalAddress, PostCode, QuotaBytesTotal, QuotaBytesUsed, Rating, Recurrence, RecurrenceException, Region, Reminder, ResourceId, ServiceDocument, Source, Source.Generator, Street, StructuredPostalAddress, Subregion, Transparency, Visibility, When, Where, Who, Workspace, XmlBlob

public class Element
extends java.lang.Object

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:

setTextValue(Object), setAttributeValue(AttributeKey, Object), addElement(Element), addElement(ElementKey, Element)

Constructor Summary

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.

Method Summary

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> E	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> E	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> 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.
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> java.util.List<T>	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> java.util.Set<T>	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.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Element

public Element(ElementKey<?,?> elementKey)

Construct element and associate with a key.

Parameters:

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

Element

public Element(QName qName)

Construct a generic undeclared element with the specified qualified name.

Parameters:

qName - qualified name

Element

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.

Method Detail

getDefaultKey

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

Returns the default ElementKey for an Element type.

Parameters:

type - element type

Returns:

default element key for type

isLocked

public final boolean isLocked()

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

lock

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.

getElementKey

public ElementKey<?,?> getElementKey()

Returns the key to this element.

getElementId

public QName getElementId()

Get the id of this element.

getAttributeIterator

public java.util.Iterator<Attribute> getAttributeIterator()

Returns an iterator over all attributes on this element.

getAttributeIterator

public 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. 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

getAttributeCount

public int getAttributeCount()

Returns the number of attributes present on this element.

Returns:

count of attributes

hasAttribute

public boolean hasAttribute(QName id)

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

hasAttribute

public boolean hasAttribute(AttributeKey<?> childKey)

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

getAttributeValue

public java.lang.Object getAttributeValue(QName id)

Get the value of an attribute by id.

getAttributeValue

public <T> T getAttributeValue(AttributeKey<T> key)

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

Type Parameters:

T - return type

Parameters:

key - the attribute key to use to cast the attribute value

Returns:

typed attribute value

Throws:

java.lang.IllegalArgumentException - if the value cannot be converted to the key type

setAttributeValue

public Element setAttributeValue(QName id,
                                 java.lang.Object attrValue)

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

setAttributeValue

public Element setAttributeValue(AttributeKey<?> key,
                                 java.lang.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

removeAttribute

@Deprecated
public java.lang.Object removeAttribute(QName id)

Deprecated. use removeAttributeValue instead.

removeAttributeValue

public java.lang.Object removeAttributeValue(QName id)

Remove attribute (if present).

Parameters:

id - the qualified name of the attribute.

Returns:

this element

removeAttribute

@Deprecated
public java.lang.Object removeAttribute(AttributeKey<?> key)

Deprecated. use removeAttributeValue instead.

removeAttributeValue

public java.lang.Object removeAttributeValue(AttributeKey<?> key)

Remove attribute (if present).

Parameters:

key - the key of the attribute.

Returns:

this element

getElementIterator

public java.util.Iterator<Element> getElementIterator()

Returns an iterator over all child elements of this element.

getElementIterator

public java.util.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

getElementCount

public int getElementCount()

Returns the number of child elements present on this element.

Returns:

number of elements.

getElement

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:

java.lang.IllegalArgumentException - if the id referenced a repeating element

getElement

public <D,T extends Element> 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.

Type Parameters:

T - the type of element to return

Parameters:

childKey - the metadata key for the child element to retrieve

Returns:

child element, or null if none was found

Throws:

java.lang.IllegalArgumentException - if the key referenced a repeating element

getElementValue

public java.lang.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.

getElementValue

public <V> 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.

Type Parameters:

V - child element's text node type

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

hasElement

public boolean hasElement(QName id)

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

hasElement

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

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

getElements

public java.util.List<Element> getElements(QName id)

Returns an immutable list of elements matching the given id.

getElements

public <T extends Element> java.util.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.

getElementSet

public java.util.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.

getElementSet

public <T extends Element> java.util.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.

setElement

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).

setElement

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);.

Throws:

java.lang.NullPointerException - if element is null.

setElement

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

addElement

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:

java.lang.NullPointerException - if element is null.

addElement

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:

java.lang.NullPointerException - if element is null.

addElement

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

removeElement

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.

removeElement

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.

removeElement

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.

removeElement

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.

replaceElement

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.

clear

public void clear()

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

getTextValue

public java.lang.Object getTextValue()

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

Returns:

untyped element value

getTextValue

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

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

Type Parameters:

V - data type of the key.

Parameters:

key - the element key used to convert the value.

Returns:

typed element value.

setTextValue

public Element setTextValue(java.lang.Object newValue)

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

Parameters:

newValue - element's value

Returns:

this element

Throws:

java.lang.IllegalStateException - if the element is immutable

java.lang.IllegalArgumentException - if the object is of an invalid type or if this element does not allow a value

hasTextValue

public boolean hasTextValue()

Returns:

true if element has a text node value

resolve

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

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

resolve

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

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

Parameters:

vc - validation context

Returns:

the narrowed element if narrowing took place.

visit

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

createElement

public static <E extends Element> E createElement(ElementKey<?,E> key)
                                       throws ContentCreationException

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

createElement

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

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

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object