org.jdom
public class Element extends Content implements Parent
Version: $Revision: 1.159 $, $Date: 2007/11/14 05:02:08 $
Field Summary | |
---|---|
protected List | additionalNamespaces Additional namespace declarations to store on this element; useful
during output |
protected String | name The local name of the element |
protected Namespace | namespace The namespace of the element |
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)
Creates a new element with the supplied (local) name and namespace. | |
Element(String name)
Create a new element with the supplied (local) name and no namespace.
| |
Element(String name, String uri)
Creates a new element with the supplied (local) name and a namespace
given by a URI. | |
Element(String name, String prefix, String uri)
Creates a new element with the supplied (local) name and a namespace
given by the supplied prefix and URI combination.
|
Method Summary | |
---|---|
Element | addContent(String str)
This adds text content to this element. |
Element | addContent(Content child)
Appends the child to the end of the element's content list.
|
Element | addContent(Collection newContent)
Appends all children in the given collection to the end of
the content list. |
Element | addContent(int index, Content child)
Inserts the child into the content list at the given index.
|
Element | addContent(int index, Collection newContent)
Inserts the content in a collection into the content list
at the given index. |
void | addNamespaceDeclaration(Namespace additionalNamespace)
Adds a namespace declarations to this element. |
Object | clone() This returns a deep clone of this element. |
List | cloneContent() |
List | getAdditionalNamespaces()
Returns a list of the additional namespace declarations on this element.
|
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, 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. |
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. |
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 of all the child elements
nested directly (one level deep) within this element, as
Element objects. |
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. |
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. |
String | getChildText(String name)
Returns the textual content of the named child element, or null if
there's no such child. |
String | getChildText(String name, Namespace ns)
Returns the textual content of the named child element, or null if
there's no such child.
|
String | getChildTextNormalize(String name)
Returns the normalized textual content of the named child element, or
null if there's no such child. |
String | getChildTextNormalize(String name, Namespace ns)
Returns the normalized textual content of the named child element, or
null if there's no such child.
|
String | getChildTextTrim(String name)
Returns the trimmed textual content of the named child element, or null
if there's no such child. |
String | getChildTextTrim(String name, Namespace ns)
Returns the trimmed textual content of the named child element, or 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 Text , Element ,
Comment , ProcessingInstruction ,
CDATA , and EntityRef .
|
List | getContent(Filter filter)
Return a filter view of this Element 's content.
|
Content | getContent(int index) |
int | getContentSize() |
Iterator | getDescendants()
Returns an iterator that walks over all descendants in document order.
|
Iterator | getDescendants(Filter filter)
Returns an iterator that walks over all descendants in document order
applying the Filter to return only elements that match the filter rule.
|
String | getName()
Returns the (local) name of the element (without any namespace prefix).
|
Namespace | getNamespace()
Returns the element's Namespace.
|
Namespace | getNamespace(String prefix)
Returns the Namespace corresponding to the given prefix in scope
for this element. |
String | getNamespacePrefix()
Returns the namespace prefix of the element or an empty string if none
exists.
|
String | getNamespaceURI()
Returns the namespace URI mapped to this element's prefix (or the
in-scope default namespace URI if no prefix). |
String | getQualifiedName()
Returns the full name of the element, in the form
[namespacePrefix]:[localName]. |
String | getText()
Returns the textual content directly held under this element as a string.
|
String | getTextNormalize()
Returns the textual content of this element with all surrounding
whitespace removed and internal whitespace normalized to a single space.
|
String | getTextTrim()
Returns the textual content of this element with all surrounding
whitespace removed. |
String | getValue()
Returns the XPath 1.0 string value of this element, which is the
complete, ordered content of all text node descendants of this element
(i.e. the text that's left after all references are resolved
and all other markup is stripped out.)
|
int | indexOf(Content child) |
boolean | isAncestor(Element element)
Determines if this element is the ancestor of another element.
|
boolean | isRootElement()
Returns whether this element is a root element. |
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. |
List | removeContent()
Removes all child content from this parent.
|
List | removeContent(Filter filter)
Remove all child content from this parent matching the supplied filter.
|
boolean | removeContent(Content child) |
Content | removeContent(int index) |
void | removeNamespaceDeclaration(Namespace additionalNamespace)
Removes an additional 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(Collection newAttributes) This sets the attributes of the element. |
Element | setAttributes(List newAttributes) This sets the attributes of the element. |
Element | setContent(Collection newContent)
This sets the content of the element. |
Element | setContent(int index, Content child)
Replace the current child the given index with the supplied child.
|
Parent | setContent(int index, Collection newContent)
Replace the child at the given index whith the supplied
collection.
|
Element | setContent(Content child)
Set this element's content to be the supplied child.
|
Element | setName(String name)
Sets the (local) name of the element.
|
Element | setNamespace(Namespace namespace)
Sets the element's Namespace. |
Element | setText(String text)
Sets the content of the element to be the text given. |
String | toString()
This returns a |
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.
Parameters: name local name of the element namespace namespace for the element
Throws: IllegalNameException if the given name is illegal as an element name
Parameters: name local name of the element
Throws: IllegalNameException if the given name is illegal as an element name.
Parameters: name name of the element uri namespace URI for the element
Throws: IllegalNameException if the given name is illegal as an element name or the given URI is illegal as a namespace URI
Parameters: name local name of the element prefix namespace prefix uri namespace URI for the element
Throws: IllegalNameException if the given name is illegal as an element name, the given prefix is illegal as a namespace prefix, or the given URI is illegal as a namespace URI
setText()
.
Parameters: str String
to add
Returns: this element modified
Throws: IllegalDataException if str
contains an
illegal character such as a vertical tab (as determined
by Verifier)
Parameters: child child to append to end of content list
Returns: the element on which the method was called
Throws: IllegalAddException if the given child already has a parent.
Parameters: newContent Collection
of content to append
Returns: the element on which the method was called
Throws: IllegalAddException if any item in the collection already has a parent or is of an inappropriate type.
Parameters: index location for adding the collection child child to insert
Returns: the parent on which the method was called
Throws: IndexOutOfBoundsException if index is negative or beyond the current number of children IllegalAddException if the given child already has a parent.
Parameters: index location for adding the collection newContent Collection
of content to insert
Returns: the parent on which the method was called
Throws: IndexOutOfBoundsException if index is negative or beyond the current number of children IllegalAddException if any item in the collection already has a parent or is of an inappropriate type.
Parameters: additionalNamespace 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
Returns: a List of 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 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 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
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
Parameters: name local name of child element to match
Returns: the first matching child element, or null if not found
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
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
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
getChild().getText()
can throw a NullPointerException.
Parameters: name the name of the child
Returns: text content for the named child, or null if 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 no such child
getTextNormalize
for details of text normalizing.
Parameters: name the name of the child
Returns: normalized text content for the named child, or null if no such child
Parameters: name the name of the child ns the namespace of the child
Returns: normalized text content for the named child, or null if no such child
getTextTrim
for
details of text trimming.
Parameters: name the name of the child
Returns: trimmed text content for the named child, or null if no such child
Parameters: name the name of the child ns the namespace of the child
Returns: trimmed text content for the named child, or null if no such child
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.
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
Returns: an iterator to walk descendants
Parameters: filter filter to select which descendants to see
Returns: an iterator to walk descendants within a filter
Returns: local element name
Returns: the element's namespace
Parameters: prefix namespace prefix to look up
Returns: the Namespace for this prefix at this location, or null if none
Returns: the namespace prefix
Returns: the namespace URI for this element
Returns: qualified name of the element (including namespace prefix)
Returns: text content for this element, or empty string if none
Returns: normalized text content for this element, or empty string if none
Returns: trimmed text content for this element, or empty string if none
Returns: a concatentation of all text node descendants
Parameters: element Element
to check against
Returns: true
if this element is the ancestor of the
supplied element
Returns: 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
Returns: list of the old children detached from this parent
Parameters: filter filter to select which content to remove
Returns: list of the old children detached from this parent
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
Throws: IllegalNameException if the given name is illegal as an attribute name. IllegalDataException if the given attribute value is illegal character data (as determined by Verifier).
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
Throws: IllegalNameException if the given name is illegal as an attribute name, or if the namespace is an unprefixed default namespace IllegalDataException if the given attribute value is illegal character data (as determined by Verifier). IllegalAddException if the attribute namespace prefix collides with another namespace prefix on the element.
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 Collection 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: newAttributes Collection
of attributes to set
Returns: this element modified
Throws: IllegalAddException if the List contains objects
that are not instances of Attribute
,
or if any of the Attribute
objects have
conflicting namespace prefixes.
This sets the attributes of the element. It's an alternate form of
the method, accepting a List
instead of a
Collection
, for backward compatibility.
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 Collection
of content to set
Returns: this element modified
Throws: IllegalAddException if the List contains objects of illegal types or with existing parentage.
In event of an exception the original content will be unchanged and the supplied child will be unaltered.
Parameters: index - index of child to replace. child - child to add.
Returns: element on which this method was invoked
Throws: IllegalAddException if the supplied child is already attached or not legal content for this parent. IndexOutOfBoundsException if index is negative or greater than the current number of children.
In event of an exception the original content will be unchanged and the content in the supplied collection will be unaltered.
Parameters: index - index of child to replace. newContent - Collection
of content to replace child.
Returns: object on which this method was invoked
Throws: IllegalAddException if the collection contains objects of illegal types. IndexOutOfBoundsException if index is negative or greater than the current number of children.
If the supplied child is legal content for this parent and before it is added, all content in the current content list will be cleared and all current children will have their parentage set to null.
This has the effect that any active list (previously obtained with a call to one of the Element methods will also change to reflect the new content. In addition, all content in the supplied collection will have their parentage set to this parent. If the user wants to continue working with a "live" list of this parent's child, then a call to setContent should be followed by a call to one of the Element methods to obtain a "live" version of the children.
Passing a null child clears the existing content.
In event of an exception the original content will be unchanged and the supplied child will be unaltered.
Parameters: child new content to replace existing content
Returns: the parent on which the method was called
Throws: IllegalAddException if the supplied child is already attached or not legal content for an Element
Parameters: name the new (local) name of the element
Returns: the target element
Throws: IllegalNameException if the given name is illegal as an Element name
Parameters: namespace the new namespace
Returns: the target element
Element
instead. Setting a null text value is equivalent to setting an empty
string value.
Parameters: text new text content for the element
Returns: the target element
Throws: IllegalDataException if the assigned text contains an illegal character such as a vertical tab (as determined by Verifier)
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