org.jdom
public class Element extends Object implements Serializable, Cloneable
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.
Version: $Revision: 1.115 $, $Date: 2002/03/28 11:08:12 $
Field Summary | |
---|---|
protected List | additionalNamespaces Additional Namespace declarations on this
element |
protected AttributeList | attributes The attributes of the Element . |
protected ContentList | content The mixed content of the Element . |
protected String | name The local name of the Element |
protected Namespace | namespace The Namespace of the Element |
protected Object | parent Parent element, document, or null if none |
Constructor Summary | |
---|---|
protected | Element() This protected constructor is provided in order to support an Element subclass that wants full control over variable initialization. |
Element(String name, Namespace namespace)
This will create a new | |
Element(String name)
This will create an | |
Element(String name, String uri)
This will create a new | |
Element(String name, String prefix, String uri)
This will create a new |
Method Summary | |
---|---|
Element | addContent(String str) This adds text content to this element. |
Element | addContent(Text text) This adds text content to this element. |
Element | addContent(CDATA cdata) This adds a CDATA section as content to this element. |
Element | addContent(Element element) This adds element content to this element. |
Element | addContent(ProcessingInstruction pi) This adds a processing instruction as content to this element. |
Element | addContent(EntityRef entity) This adds entity content to this element. |
Element | addContent(Comment comment) This adds a comment as content to this element. |
void | addNamespaceDeclaration(Namespace additional) This will add a namespace declarations to this element. |
Object | clone() This returns a deep clone of this element. |
Element | detach() This detaches the element from its parent, or does nothing if the element has no parent. |
boolean | equals(Object ob)
This tests for equality of this |
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
|
Attribute | getAttribute(String name) This returns the attribute for this element with the given name and within no namespace, or null if no such attribute exists. |
Attribute | getAttribute(String name, Namespace ns) This returns the attribute for this element with the given name and within the given Namespace, or null if no such attribute exists. |
List | getAttributes()
This returns the complete set of attributes for this element, as a
|
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. |
String | getAttributeValue(String name, Namespace ns, String def) This returns the attribute value for the attribute with the given name and within the given Namespace, or the passed-in default if there is no such attribute. |
String | getAttributeValue(String name, String def) This returns the attribute value for the attribute with the given name and within no namespace, or the passed-in default if there is no such attribute. |
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. |
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. |
Element | getChild(String name) This returns the first child element within this element with the given local name and belonging to no namespace. |
List | getChildren()
This returns a |
List | getChildren(String name)
This returns a |
List | getChildren(String name, Namespace ns)
This returns a |
String | getChildText(String name)
This convenience method returns the textual content of the named
child element, or returns an empty |
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. |
String | getChildTextNormalize(String name) This convenience method returns the normalized textual content of the named child element, or returns null if there's no such child. |
String | getChildTextNormalize(String name, Namespace ns) This convenience method returns the normalized textual content of the named child element, or returns null if there's no such child. |
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. |
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. |
List | getContent()
This returns the full content of the element as a List which
may contain objects of type |
List | getContent(Filter filter)
Return a filter view of this |
Document | getDocument() |
String | getName()
This returns the (local) name of the
|
Namespace | getNamespace()
This will return this |
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). |
String | getNamespacePrefix()
This returns the namespace prefix
of the |
String | getNamespaceURI()
This returns the URI mapped to this |
Element | getParent()
This will return the parent of this |
String | getQualifiedName()
This returns the full name of the
|
String | getText() This returns the textual content directly held under this element. |
String | getTextNormalize() This returns the textual content of this element with all surrounding whitespace removed and internal whitespace normalized to a single space. |
String | getTextTrim() This returns the textual content of this element with all surrounding whitespace removed. |
boolean | hasChildren() Test whether this element has a child element. |
int | hashCode()
This returns the hash code for this |
boolean | isAncestor(Element element) Determines if this element is the ancestor of another element. |
boolean | isRootElement()
This returns a |
boolean | removeAttribute(String name) This removes the attribute with the given name and within no namespace. |
boolean | removeAttribute(String name, Namespace ns) This removes the attribute with the given name and within the given Namespace. |
boolean | removeAttribute(Attribute attribute) This removes the supplied Attribute should it exist. |
boolean | removeChild(String name) This removes the first child element (one level deep) with the given local name and belonging to no namespace. |
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. |
boolean | removeChildren(String name) This removes all child elements (one level deep) with the given local name and belonging to no namespace. |
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. |
boolean | removeChildren() This removes all child elements. |
boolean | removeContent(Element element)
This removes the specified |
boolean | removeContent(ProcessingInstruction pi)
This removes the specified |
boolean | removeContent(Comment comment)
This removes the specified |
boolean | removeContent(CDATA cdata)
This removes the specified |
boolean | removeContent(Text text)
This removes the specified |
boolean | removeContent(EntityRef entity)
This removes the specified |
void | removeNamespaceDeclaration(Namespace additionalNamespace) This will remove a namespace declarations from this element. |
Element | setAttribute(String name, String value) This sets an attribute value for this element. |
Element | setAttribute(String name, String value, Namespace ns) This sets an attribute value for this element. |
Element | setAttribute(Attribute attribute) This sets an attribute value for this element. |
Element | setAttributes(List newAttributes) This sets the attributes of the element. |
Element | setChildren(List children)
This sets the content of the element the same as Element,
except only |
Element | setContent(List newContent) This sets the content of the element. |
protected Element | setDocument(Document document)
This sets the |
Element | setName(String name)
This sets the (local) name of the |
Element | setNamespace(Namespace namespace)
This sets this |
protected Element | setParent(Element parent)
This will set the parent of this |
Element | setText(String text) This sets the content of the element to be the text given. |
String | toString()
This returns a |
Namespace
declarations on this
elementElement
.Element
.Element
Namespace
of the Element
This protected constructor is provided in order to support an Element subclass that wants full control over variable initialization. It intentionally leaves all instance variables null, allowing a lightweight subclass implementation. The subclass is responsible for ensuring all the get and set methods on Element behave as documented.
When implementing an Element
subclass which doesn't
require full control over variable initialization, be aware that
simply calling super() (or letting the compiler add the implicit
super() call) will not initialize the instance variables which will
cause many of the methods to throw a
NullPointerException
. Therefore, the
constructor for these subclasses should call one of the public
constructors so variable initialization is handled automatically.
This will create a new Element
with the supplied (local) name, and define
the Namespace
to be used.
If the provided namespace is null, the element will have
no namespace.
Parameters: name String
name of element.
UNKNOWN: Namespace
to put element in.
This will create an Element
in no
Namespace
.
Parameters: name String
name of element.
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.
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.
This adds text content to this element. It does not replace the
existing content as does setText()
.
Parameters: str String
to add
Returns: this element modified
This adds text content to this element. It does not replace the
existing content as does setText()
.
Parameters: text Text
to add
Returns: this element modified
This adds a CDATA section as content to this element.
Parameters: cdata CDATA
to add
Returns: this element modified
This adds element content to this element.
Parameters: element Element
to add
Returns: this element modified
Throws: IllegalAddException if the element you're attempting to add already has a parent element, or if you're attempting to add it as a descendent of itself (which would result in a recursive element definition!).
This adds a processing instruction as content to this element.
Parameters: pi ProcessingInstruction
to add
Returns: this element modified
Throws: IllegalAddException if the given processing instruction,
pi
, already has a parent.
This adds entity content to this element.
Parameters: entity EntityRef
to add
Returns: this element modified
Throws: IllegalAddException if the given EntityRef already has a parent.
This adds a comment as content to this element.
Parameters: comment Comment
to add
Returns: this element modified
Throws: IllegalAddException if the given Comment already has a parent.
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: additional Namespace
to add.
Throws: IllegalAddException if the namespace prefix collides with another namespace prefix on the element.
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
This detaches the element from its parent, or does nothing if the element has no parent.
Returns: Element
- this Element
modified.
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
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 an empty list. Note, the returned
list is not live, for performance reasons.
Returns: List
- the additional namespace declarations.
This returns the attribute for this element with the given name and within no namespace, or null if no such attribute exists.
Parameters: name name of the attribute to return
Returns: attribute for the element
This returns the attribute for this element with the given name and within the given Namespace, or null if no such attribute exists.
Parameters: name name of the attribute to return ns Namespace
to search within
Returns: attribute for the element
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
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
This returns the attribute value for the attribute with the given name and within the given Namespace, or the passed-in default if there is no such attribute.
Parameters: name name of the attribute whose valud is to be returned ns Namespace
to search within def a default value to return if the attribute does not exist
Returns: the named attribute's value, or the default if no such attribute
This returns the attribute value for the attribute with the given name and within no namespace, or the passed-in default if there is no such attribute.
Parameters: name name of the attribute whose value to be returned def a default value to return if the attribute does not exist
Returns: the named attribute's value, or the default if no such attribute
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
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
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
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"
in document order and changes to it affect the element's actual
contents.
Sequential traversal through the List is best done with a Iterator since the underlying implement of List.size() may not be the most efficient.
No recursion is performed, so elements nested two levels deep would have to be obtained with:
Iterator itr = (currentElement.getChildren()).iterator();
while(itr.hasNext()) {
Element oneLevelDeep = (Element)itr.next();
List twoLevelsDeep = oneLevelDeep.getChildren();
// Do something with these children
}
Returns: list of child Element
objects for this element
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" in document order
and changes to it affect the element's actual contents.
Please see the notes for Element
for a code example.
Parameters: name local name for the children to match
Returns: all matching child elements
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" in document order
and changes to it affect the element's actual contents.
Please see the notes for Element
for a code example.
Parameters: name local name for the children to match ns Namespace
to search within
Returns: all matching child elements
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
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
This convenience method returns the normalized textual content of the
named child element, or returns null if there's no such child.
See getTextNormalize
for details of text
normalizing.
Parameters: name the name of the child
Returns: normalized text content for the named child, or null if none
This convenience method returns the normalized textual content of the
named child element, or returns null if there's no such child.
See getTextNormalize
for
details of text normalizing.
Parameters: name the name of the child ns the namespace of the child
Returns: normalized text content for the named child, or null if none
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
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
This returns the full content of the element as a List which
may contain objects of type Text
, Element
,
Comment
, ProcessingInstruction
,
CDATA
, and EntityRef
.
The List returned is "live" in document order and modifications
to it affect the element's actual contents. Whitespace content is
returned in its entirety.
Sequential traversal through the List is best done with an Iterator since the underlying implement of List.size() may require walking the entire list.
Returns: a List
containing the mixed content of the
element: may contain Text
,
Element
, Comment
,
ProcessingInstruction
,
CDATA
, and
EntityRef
objects.
Return a filter view of this Element
's content.
Sequential traversal through the List is best done with a Iterator since the underlying implement of List.size() may require walking the entire list.
Parameters: filter Filter
to apply
Returns: List
- filtered Element content
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.
This returns the (local) name of the
Element
, without any
namespace prefix, if one exists.
Returns: String
- element name.
This will return this Element
's
Namespace
.
Returns: Namespace
- Namespace object for this
Element
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.
This returns the namespace prefix
of the Element
, if
one exists. Otherwise, an empty
String
is returned.
Returns: String
- namespace prefix.
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
.
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 Element
to determine this.
Returns: parent of this Element
.
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.
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 Text
and CDATA
nodes returned by
getContent(). 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 empty string if none
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 empty string if none
This returns the textual content of this element with all surrounding whitespace removed. If no textual value exists for the element, or if only whitespace exists, the empty string is returned.
Returns: trimmed text content for this element, or empty string if none
Test whether this element has a child element. This method can be used before a call to Element, which always creates a "live" list, to improve performance.
Returns: true
if this element has at least
one child element
This returns the hash code for this Element
.
Returns: inherited hash code
Determines if this element is the ancestor of another element.
Parameters: element Element
to check against
Returns: true
if this element is the ancestor of the
supplied element
This returns a boolean
value indicating
whether this Element
is a root
Element
for a JDOM Document
.
This should be used in tandem with
Element
to determine
if an Element
has no "attachments" to
parents.
Returns: boolean
- whether this is a root element.
This removes the attribute with the given name and within no namespace. If no such attribute exists, this method does nothing.
Parameters: name name of attribute to remove
Returns: whether the attribute was removed
This removes the attribute with the given name and within the given Namespace. If no such attribute exists, this method does nothing.
Parameters: name name of attribute to remove ns namespace URI of attribute to remove
Returns: whether the attribute was removed
This removes the supplied Attribute should it exist.
Parameters: attribute Reference to the attribute to be removed.
Returns: whether the attribute was removed
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
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
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
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
This removes all child elements. Returns true if any were removed.
Returns: whether deletion occurred
This removes the specified Element
.
If the specified Element
is not a child of
this Element
, this method does nothing.
Parameters: child Element
to delete
Returns: whether deletion occurred
This removes the specified ProcessingInstruction
.
If the specified ProcessingInstruction
is not a child of
this Element
, this method does nothing.
Parameters: child ProcessingInstruction
to delete
Returns: whether deletion occurred
This removes the specified Comment
.
If the specified Comment
is not a child of
this Element
, this method does nothing.
Parameters: comment Comment
to delete
Returns: whether deletion occurred
This removes the specified CDATA
.
If the specified CDATA
is not a child of
this Element
, this method does nothing.
Parameters: cdata CDATA
to delete
Returns: whether deletion occurred
This removes the specified Text
.
If the specified Text
is not a child of
this Element
, this method does nothing.
Parameters: text Text
to delete
Returns: whether deletion occurred
This removes the specified EntityRef
.
If the specified EntityRef
is not a child of
this Element
, this method does nothing.
Parameters: child EntityRef
to delete
Returns: whether deletion occurred
This will remove a namespace declarations from this element. This should not be used to remove the declaration for this element itself; that should be handled in the construction of the element. Instead, this is for removing namespace declarations on the element not relating directly to itself. If the declaration is not present, this method does nothing.
Parameters: additionalNamespace Namespace
to remove.
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
Parameters: name name of the attribute to set value value of the attribute to set
Returns: this element modified
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
Parameters: name name of the attribute to set value value of the attribute to set ns namespace of the attribute to set
Returns: this element modified
This sets an attribute value for this element. Any existing attribute with the same name and namespace URI is removed.
Parameters: attribute Attribute
to set
Returns: this element modified
Throws: IllegalAddException if the attribute being added already has a parent or if the attribute namespace prefix collides with another namespace prefix on the element.
This sets the attributes of the element. The supplied List should
contain only objects of type Attribute
.
When all objects in the supplied List are legal and before the new attributes are added, all old attributes will have their parentage set to null (no parent) and the old attribute list will be cleared. This has the effect that any active attribute list (previously obtained with a call to Element) will also change to reflect the new attributes. In addition, all attributes in the supplied List will have their parentage set to this element, but the List itself will not be "live" and further removals and additions will have no effect on this elements attributes. If the user wants to continue working with a "live" attribute list, then a call to setAttributes should be followed by a call to Element to obtain a "live" version of the attributes.
Passing a null or empty List clears the existing attributes.
In cases where the List contains duplicate attributes, only the last one will be retained. This has the same effect as calling setAttribute sequentially.
In event of an exception the original attributes will be unchanged and the attributes in the supplied attributes will be unaltered.
Parameters: attributes List
of attributes to set
Returns: this element modified
Throws: IllegalAddException if the List contains objects of illegal types.
This sets the content of the element the same as Element,
except only Element
objects are allowed in the supplied
list.
Parameters: children List
of Element
objects to add
Returns: this element modified
This sets the content of the element. The supplied List should
contain only objects of type Element
, Text
,
CDATA
, Comment
,
ProcessingInstruction
, and EntityRef
.
When all objects in the supplied List are legal and before the new content is added, all objects in the old content will have their parentage set to null (no parent) and the old content list will be cleared. This has the effect that any active list (previously obtained with a call to Element or Element) will also change to reflect the new content. In addition, all objects in the supplied List will have their parentage set to this element, but the List itself will not be "live" and further removals and additions will have no effect on this elements content. If the user wants to continue working with a "live" list, then a call to setContent should be followed by a call to Element or Element to obtain a "live" version of the content.
Passing a null or empty List clears the existing content.
In event of an exception the original content will be unchanged and the objects in the supplied content will be unaltered.
Parameters: newContent List
of content to set
Returns: this element modified
Throws: IllegalAddException if the List contains objects of illegal types.
This sets the Document
parent of this element
and makes it the root element. The caller is responsible for
ensuring the element doesn't have a pre-existing parent.
Parameters: document Document
parent
Returns: Document
this Element
modified
This sets the (local) name of the Element
.
Returns: Element
- the element modified.
Throws: IllegalNameException if the given name is illegal as an Element name.
This sets this Element
's Namespace
.
If the provided namespace is null, the element will have no namespace.
Returns: Element
- the element modified.
This will set the parent of this Element
.
The caller is responsible for handling pre-existing parentage.
Parameters: parent Element
to be new parent.
Returns: Element
- this Element
modified.
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 Element
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
This returns a String
representation of the
Element
, suitable for debugging. If the XML
representation of the Element
is desired,
outputString
should be used.
Returns: String
- information about the
Element