com.google.gdata.model
Class Element

java.lang.Object
  extended by 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
protected  Element adapt(Element source, ElementMetadata<?,?> sourceMeta, java.lang.String kind)
          Adapts an element based on a key.
protected
<T extends Element>
T
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>
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.
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>
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.
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.
 
Methods inherited from class java.lang.Object
clone, finalize, 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.

narrow

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

adapt

protected Element adapt(Element source,
                        ElementMetadata<?,?> sourceMeta,
                        java.lang.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.

adapt

protected <T extends Element> T adapt(ElementKey<?,T> key,
                                      Element source)
                           throws ContentCreationException
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.

Type Parameters:
T - the type of element to adapt to.
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.
java.lang.NullPointerException - if meta is null.

validate

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.


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

sameClassAs

protected boolean sameClassAs(java.lang.Object o)
Parameters:
o - given object
Returns:
true if the given object is not null and is the same concrete class as this one

eq

protected static boolean eq(java.lang.Object o1,
                            java.lang.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

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