org.jdom
Class Element

public class Element

implements Cloneable, Serializable

Element defines behavior for an XML element, modeled in Java. Methods allow the user to obtain the value of the element's textual content, obtain its attributes, and get its children.

Author:

Brett McLaughlin, Jason Hunter, Lucas Gonze, Kevin Regan, Dan Schaffer, Yusuf Goolamabbas

Version: 1.0

public Element(String name, Namespace namespace)

This will create a new Element with the supplied (local) name, and define the Namespace to be used.

Parameters:

name - String name of element.

namespace Namespace to put element in.

public Element(String name)

This will create an Element in no Namespace.

Parameters:

name - String name of element.

public Element(String name, String uri)

This will create a new Element with the supplied (local) name, and specifies the URI of the Namespace the Element should be in, resulting it being unprefixed (in the default namespace).

Parameters:

name - String name of element.

uri - String URI for Namespace element should be in.

public Element(String name, String prefix, String uri)

This will create a new Element with the supplied (local) name, and specifies the prefix and URI of the Namespace the Element should be in.

Parameters:

name - String name of element.

uri - String URI for Namespace element should be in.

public Element addAttribute(Attribute attribute)

This adds an attribute to this element. Any existing attribute with the same name and namespace URI is removed. (TODO: Code the replacement logic.)

Parameters:

attribute - Attribute to add

Returns: this element modified

public Element addAttribute(String name, String value)

This adds an attribute to this element with the given name and value. To add attributes in namespaces using addAttribute(Attribute).

Parameters:

name - name of the attribute to add

value - value of the attribute to add

Returns: this element modified

public Element addContent(String text)

This adds text content to this element. It does not replace the existing content as does setText().

Parameters:

text - String to add

Returns: this element modified

public Element addContent(Element element)

This adds element content to this element.

Parameters:

element - Element to add

Returns: this element modified

public Element addContent(ProcessingInstruction pi)

This adds a processing instruction as content to this element.

Parameters:

pi - ProcessingInstruction to add

Returns: this element modified

public Element addContent(Entity entity)

This adds entity content to this element.

Parameters:

entity - Entity to add

Returns: this element modified

public Element addContent(CDATA cdata)

This adds a CDATA section as content to this element.

Parameters:

cdata - CDATA to add

Returns: this element modified

public Element addContent(Comment comment)

This adds a comment as content to this element.

Parameters:

comment - Comment to add

Returns: this element modified

public void addNamespaceDeclaration(Namespace additionalNamespace)

This will add a namespace declarations to this element. This should not be used to add the declaration for this element itself; that should be assigned in the construction of the element. Instead, this is for adding namespace declarations on the element not relating directly to itself.

Parameters:

additionalNamespace - Namespace to add.

public Object clone()

This returns a deep clone of this element. The new element is detached from its parent, and getParent() on the clone will return null.

Returns: the clone of this element

public final boolean equals(Object ob)

This tests for equality of this Element to the supplied Object, explicitly using the == operator.

Parameters:

ob - Object to compare to

Returns: whether the elements are equal

public List getAdditionalNamespaces()

This will return any namespace declarations on this element that exist, excluding the namespace of the element itself, which can be obtained through getNamespace(). If there are no additional declarations, this returns null.

Returns: List - the additional namespace declarations.

public Attribute getAttribute(String name)

This returns the attribute for this element with the given name and within no namespace.

Parameters:

name - name of the attribute to return

Returns: attribute for the element

public Attribute getAttribute(String name, Namespace ns)

This returns the attribute for this element with the given name and within the given Namespace.

Parameters:

name - name of the attribute to return

ns - Namespace to search within

Returns: attribute for the element

public List getAttributes()

This returns the complete set of attributes for this element, as a List of Attribute objects in no particular order, or an empty list if there are none. The returned list is "live" and changes to it affect the element's actual attributes.

Returns: attributes for the element

public String getAttributeValue(String name)

This returns the attribute value for the attribute with the given name and within no namespace, null if there is no such attribute, and the empty string if the attribute value is empty.

Parameters:

name - name of the attribute whose value to be returned

Returns: the named attribute's value, or null if no such attribute

public String getAttributeValue(String name, Namespace ns)

This returns the attribute value for the attribute with the given name and within the given Namespace, null if there is no such attribute, and the empty string if the attribute value is empty.

Parameters:

name - name of the attribute whose valud is to be returned

ns - Namespace to search within

Returns: the named attribute's value, or null if no such attribute

public Element getChild(String name, Namespace ns)

This returns the first child element within this element with the given local name and belonging to the given namespace. If no elements exist for the specified name and namespace, null is returned.

Parameters:

name - local name of child element to match

ns - Namespace to search within

Returns: the first matching child element, or null if not found

public Element getChild(String name)

This returns the first child element within this element with the given local name and belonging to no namespace. If no elements exist for the specified name and namespace, null is returned.

Parameters:

name - local name of child element to match

Returns: the first matching child element, or null if not found

public List getChildren()

This returns a List of all the child elements nested directly (one level deep) within this element, as Element objects. If this target element has no nested elements, an empty List is returned. The returned list is "live" and changes to it affect the element's actual contents.

This performs no recursion, so elements nested two levels deep would have to be obtained with:

Iterator itr = currentElement.getChildren().iterator();
while (itr.hasNext()) {
Element oneLevelDeep = (Element)nestedElements.next();
List twoLevelsDeep = oneLevelDeep.getChildren();
// Do something with these children
}

Returns: list of child Element objects for this element

public List getChildren(String name)

This returns a List of all the child elements nested directly (one level deep) within this element with the given local name and belonging to no namespace, returned as Element objects. If this target element has no nested elements with the given name outside a namespace, an empty List is returned. The returned list is "live" and changes to it affect the element's actual contents.

Please see the notes for getChildren() for a code example.

Parameters:

name - local name for the children to match

Returns: all matching child elements

public List getChildren(String name, Namespace ns)

This returns a List of all the child elements nested directly (one level deep) within this element with the given local name and belonging to the given Namespace, returned as Element objects. If this target element has no nested elements with the given name in the given Namespace, an empty List is returned. The returned list is "live" and changes to it affect the element's actual contents.

Please see the notes for getChildren() for a code example.

Parameters:

name - local name for the children to match

ns - Namespace to search within

Returns: all matching child elements

public String getChildText(String name)

This convenience method returns the textual content of the named child element, or returns an empty String ("") if the child has no textual content. However, if the child does not exist, null is returned.

Parameters:

name - the name of the child

Returns: text content for the named child, or null if none

public String getChildText(String name, Namespace ns)

This convenience method returns the textual content of the named child element, or returns null if there's no such child.

Parameters:

name - the name of the child

ns - the namespace of the child

Returns: text content for the named child, or null if none

public String getChildTextTrim(String name)

This convenience method returns the trimmed textual content of the named child element, or returns null if there's no such child. See getTextTrim() for details of text trimming.

Parameters:

name - the name of the child

Returns: trimmed text content for the named child, or null if none

public String getChildTextTrim(String name, Namespace ns)

This convenience method returns the trimmed textual content of the named child element, or returns null if there's no such child. See getTextTrim() for details of text trimming.

Parameters:

name - the name of the child

ns - the namespace of the child

Returns: trimmed text content for the named child, or null if none

public Element getCopy(String name, Namespace ns)

This creates a copy of this Element, with the new name specified, and in the specified Namespace.

Parameters:

name - String name of new Element copy.

ns - Namespace to put copy in.

Returns: Element copy of this Element.

public Element getCopy(String name)

This creates a copy of this Element, with the new name specified, and in no namespace.

Parameters:

name - String name of new Element copy.

public Document getDocument()

This retrieves the owning Document for this Element, or null if not a currently a member of a Document.

Returns: Document owning this Element, or null.

public List getMixedContent()

This returns the full content of the element as a List which may contain objects of type String, Element, Comment, ProcessingInstruction, and Entity. When there is technically no mixed content and all contents are of the same type, then all objects returned in the List will be of the same type. The List returned is "live" and modifications to it affect the element's actual contents. Whitespace content is returned in its entirety.

Returns: a List containing the mixed content of the element: may contain String, Element, Comment, ProcessingInstruction, and Entity objects.

public String getName()

This returns the (local) name of the Element, without any namespace prefix, if one exists.

Returns: String - element name.

public Namespace getNamespace()

This will return this Element's Namespace.

Returns: Namespace - Namespace object for this Element

public Namespace getNamespace(String prefix)

This returns the Namespace in scope on this element for the given prefix (this involves searching up the tree, so the results depend on the current location of the element). It returns null if there is no Namespace in scope with the given prefix at this point in the document.

Parameters:

prefix - namespace prefix to look up

Returns: Namespace - namespace in scope for the given prefix on this Element, or null if none.

public String getNamespacePrefix()

This returns the namespace prefix of the Element, if one exists. Otherwise, an empty String is returned.

Returns: String - namespace prefix.

public String getNamespaceURI()

This returns the URI mapped to this Element's prefix (or the default namespace if no prefix). If no mapping is found, an empty String is returned.

Returns: String - namespace URI for this Element.

public Element getParent()

This will return the parent of this Element. If there is no parent, then this returns null. Also note that on its own, this is not 100% sufficient to see if the Element is not in use - this should be used in tandem with isRootElement() to determine this.

Returns: parent of this Element.

public String getQualifiedName()

This returns the full name of the Element, in the form [namespacePrefix]:[localName]. If no namespace prefix exists for the Element, simply the local name is returned.

Returns: String - full name of element.

public final String getSerializedForm()

This will return the Element in XML format, usable in an XML document.

Returns: String - the serialized form of the Element.

public String getText()

This returns the textual content directly held under this element. This will include all text within this single element, including whitespace and CDATA sections if they exist. It's essentially the concatenation of all String nodes returned by getMixedContent(). The call does not recurse into child elements. If no textual value exists for the element, an empty String ("") is returned.

Returns: text content for this element, or null if none

public String getTextTrim()

This returns the textual content of this element with all surrounding whitespace removed and internal whitespace normalized to a single space. If no textual value exists for the element, or if only whitespace exists, the empty string is returned.

Returns: normalized text content for this element, or null if none

public boolean hasChildren()

public final int hashCode()

This returns the hash code for this Element.

Returns: inherited hash code

public boolean hasMixedContent()

This will indicate whether the element has mixed content or not. Mixed content is when an element contains both textual and element data within it. When this evaluates to true, getMixedContent() should be used for getting element data.

Returns: boolean - indicating whether there is mixed content (both textual data and elements).

public boolean isRootElement()

This returns a boolean value indicating whether this Element is a root Element for a JDOM Document. This should be used in tandem with getParent() to determine if an Element has no "attachments" to parents.

Returns: boolean - whether this is a root element.

public boolean removeAttribute(String name, String uri)

This removes the attribute with the given name and within the given namespace URI.

Parameters:

name - name of attribute to remove

uri - namespace URI of attribute to remove

Returns: whether the attribute was removed

public boolean removeAttribute(String name)

This removes the attribute with the given name and within no namespace.

Parameters:

name - name of attribute to remove

Returns: whether the attribute was removed

public boolean removeAttribute(String name, Namespace ns)

This removes the attribute with the given name and within the given Namespace.

Parameters:

name - name of attribute to remove

ns - namespace URI of attribute to remove

Returns: whether the attribute was removed

public boolean removeChild(String name)

This removes the first child element (one level deep) with the given local name and belonging to no namespace. Returns true if a child was removed.

Parameters:

name - the name of child elements to remove

Returns: whether deletion occurred

public boolean removeChild(String name, Namespace ns)

This removes the first child element (one level deep) with the given local name and belonging to the given namespace. Returns true if a child was removed.

Parameters:

name - the name of child element to remove

ns - Namespace to search within

Returns: whether deletion occurred

public boolean removeChildren(String name)

This removes all child elements (one level deep) with the given local name and belonging to no namespace. Returns true if any were removed.

Parameters:

name - the name of child elements to remove

Returns: whether deletion occurred

public boolean removeChildren(String name, Namespace ns)

This removes all child elements (one level deep) with the given local name and belonging to the given namespace. Returns true if any were removed.

Parameters:

name - the name of child elements to remove

ns - Namespace to search within

Returns: whether deletion occurred

public boolean removeChildren()

This removes all child elements. Returns true if any were removed.

Returns: whether deletion occurred

public boolean removeContent(Element element)

This removes the specified Element.

Parameters:

child - Element to delete

Returns: whether deletion occurred

public boolean removeContent(ProcessingInstruction pi)

This removes the specified ProcessingInstruction.

Parameters:

child - ProcessingInstruction to delete

Returns: whether deletion occurred

public boolean removeContent(Entity entity)

This removes the specified Entity.

Parameters:

child - Entity to delete

Returns: whether deletion occurred

public boolean removeContent(Comment comment)

This removes the specified Comment.

Parameters:

comment - Comment to delete

Returns: whether deletion occurred

public Element setAttributes(List attributes)

This sets all the attributes for this element to be those in the given List; all existing attributes are removed.

Parameters:

attributes - List of attributes to set

Returns: this element modified

public Element setChildren(List children)

This sets the content of the element to be the List of Element objects within the supplied List. All existing element and non-element content of the element is removed.

Parameters:

children - List of Element objects to add

Returns: this element modified

public Element setMixedContent(List mixedContent)

This sets the content of the element. The passed in List should contain only objects of type String, Element, Comment, ProcessingInstruction, and Entity. Passing a null List simply clears the existing content.

Returns: this element modified

public Element setText(String text)

This sets the content of the element to be the text given. All existing text content and non-text context is removed. If this element should have both textual content and nested elements, use setMixedContent(java.util.List) instead. Setting a null text value is equivalent to setting an empty string value.

Parameters:

text - new content for the element

Returns: this element modified

public String toString()

This returns a String representation of the Element, suitable for debugging. If the XML representation of the Element is desired, getSerializedForm() should be used.

Returns: String - information about the Element

Association Links

to Class java.lang.String

The local name of the Element

to Class org.jdom.Namespace

The {@link Namespace} of the Element

to Class java.util.LinkedList

Additional {@link Namespace} declarations on this element

to Class org.jdom.Element

Parent element, or null if none

to Class org.jdom.Document

The Document containing this element, if it is the root element

to Class java.util.List

The attributes of the Element

to Class java.util.LinkedList

The mixed content of the Element