nu.xom
public class Element extends ParentNode
This class represents an XML element. Each element has the following properties:
Version: 1.2b1
Constructor Summary | |
---|---|
Element(String name) Creates a new element in no namespace. | |
Element(String name, String uri) Creates a new element in a namespace. | |
Element(Element element) Creates a deep copy of an element. |
Method Summary | |
---|---|
void | addAttribute(Attribute attribute) Adds an attribute to this element, replacing any existing attribute with the same local name and namespace URI. |
void | addNamespaceDeclaration(String prefix, String uri) Declares a namespace prefix. |
void | appendChild(String text) Converts a string to a text node and appends that node to the children of this node. |
Node | copy() Creates a deep copy of this element with no parent, that can be added to this document or a different one. |
Attribute | getAttribute(String name) Returns the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name in no namespace. |
Attribute | getAttribute(String localName, String namespaceURI) Returns the attribute with the specified name and namespace URI, or null if this element does not have an attribute with that name in that namespace. |
Attribute | getAttribute(int index) Selects an attribute by index. |
int | getAttributeCount()
Returns the number of attributes of this |
String | getAttributeValue(String name) Returns the value of the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name. |
String | getAttributeValue(String localName, String namespaceURI) Returns the value of the attribute with the specified name and namespace URI, or null if this element does not have such an attribute. |
String | getBaseURI() Returns the absolute base URI against which relative URIs in this element should be resolved. |
Elements | getChildElements(String name) Returns a list of the child elements of this element with the specified name in no namespace. |
Elements | getChildElements(String localName, String namespaceURI) Returns a list of the immediate child elements of this element with the specified local name and namespace URI. |
Elements | getChildElements() Returns a list of all the child elements of this element in document order. |
Element | getFirstChildElement(String name) Returns the first child element with the specified name in no namespace. |
Element | getFirstChildElement(String localName, String namespaceURI) Returns the first child element with the specified local name and namespace URI. |
String | getLocalName() Returns the local name of this element, not including the namespace prefix or colon. |
int | getNamespaceDeclarationCount() Returns the number of namespace declarations on this element. |
String | getNamespacePrefix() Returns the prefix of this element, or the empty string if this element does not have a prefix. |
String | getNamespacePrefix(int index) Returns the indexth namespace prefix declared on this element. |
String | getNamespaceURI() Returns the namespace URI of this element, or the empty string if this element is not in a namespace. |
String | getNamespaceURI(String prefix) Returns the namespace URI mapped to the specified prefix within this element. |
String | getQualifiedName() Returns the complete name of this element, including the namespace prefix if this element has one. |
String | getValue() Returns the value of the element as defined by XPath 1.0. |
void | insertChild(String text, int position) Converts a string to a text node and inserts that node at the specified position. |
Attribute | removeAttribute(Attribute attribute) Removes an attribute from this element. |
Nodes | removeChildren() Detaches all children from this node. |
void | removeNamespaceDeclaration(String prefix) Removes the mapping of the specified prefix. |
void | setBaseURI(String URI)
Sets the URI from which this element was loaded,
and against which relative URLs in this element will be
resolved, unless an |
void | setLocalName(String localName) Sets the local name of this element. |
void | setNamespacePrefix(String prefix) Sets the namespace prefix of this element. |
void | setNamespaceURI(String uri) Sets the namespace URI of this element. |
protected Element | shallowCopy() Creates a very shallow copy of the element with the same name and namespace URI, but no children, attributes, base URI, or namespace declaration. |
String | toString() Returns a string representation of this element suitable for debugging and diagnosis. |
String | toXML() Returns a string containing the XML serialization of this element. |
Creates a new element in no namespace.
Parameters: name the name of the element
Throws: IllegalNameException if name
is not a legal XML 1.0 non-colonized name
Creates a new element in a namespace.
Parameters: name the qualified name of the element uri the namespace URI of the element
Throws: IllegalNameException if name
is not a legal XML 1.0 name NamespaceConflictException if name
's prefix
cannot be used with uri
MalformedURIException if uri
is not an RFC 3986 absolute URI reference
Creates a deep copy of an element. The copy is disconnected from the tree, and does not have a parent.
Parameters: element the element to copy
Adds an attribute to this element, replacing any existing attribute with the same local name and namespace URI.
Parameters: attribute the attribute to add
Throws: MultipleParentException if the attribute is already attached to an element NamespaceConflictException if the attribute's prefix is mapped to a different namespace URI than the same prefix is mapped to by this element, another attribute of this element, or an additional namespace declaration of this element
Declares a namespace prefix. This is only necessary when prefixes are used in element content and attribute values, as in XSLT and the W3C XML Schema Language. Do not use this method to declare prefixes for element and attribute names.
If you do redeclare a prefix that is already used by an element or attribute name, the additional namespace is added if and only if the URI is the same. Conflicting namespace declarations will throw an exception.
Parameters: prefix the prefix to declare uri the absolute URI reference to map the prefix to
Throws: MalformedURIException if URI
is not an RFC 3986 URI reference IllegalNameException if prefix
is not
a legal XML non-colonized name NamespaceConflictException if the mapping conflicts
with an existing element, attribute,
or additional namespace declaration
Converts a string to a text node and appends that node to the children of this node.
Parameters: text String to add to this node
Throws: IllegalAddException if this node cannot
have children of this type NullPointerException if text
is null
Creates a deep copy of this element with no parent, that can be added to this document or a different one.
Subclassers should be wary. Implementing this method is trickier
than it might seem, especially if you wish to avoid potential
stack overflows in deep documents. In particular, you should not
rely on the obvious recursive algorithm. Most subclasses should
override the shallowCopy
method instead.
Returns: a deep copy of this element with no parent
Returns the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name in no namespace.
Parameters: name the name of the attribute
Returns: the attribute of this element with the specified name
Returns the attribute with the specified name and namespace URI, or null if this element does not have an attribute with that name in that namespace.
Parameters: localName the local name of the attribute namespaceURI the namespace of the attribute
Returns: the attribute of this element with the specified name and namespace
Selects an attribute by index.
The index is purely for convenience and has no particular
meaning. In particular, it is not necessarily the
position of this attribute in the original document from
which this Element
object was read.
As with most lists in Java, attributes are numbered
from 0 to one less than the length of the list.
In general, you should not add attributes to or remove
attributes from the list while iterating across it.
Doing so will change the indexes of the other attributes in
the list. it is, however, safe to remove an attribute from
either end of the list (0 or getAttributeCount()-1
)
until there are no attributes left.
Parameters: index the attribute to return
Returns: the indexth attribute of this element
Throws: IndexOutofBoundsException if the index is negative or greater than or equal to the number of attributes of this element
Returns the number of attributes of this Element
,
not counting namespace declarations.
This is always a non-negative number.
Returns: the number of attributes in the container
Returns the value of the attribute with the specified name in no namespace, or null if this element does not have an attribute with that name.
Parameters: name the name of the attribute
Returns: the value of the attribute of this element with the specified name
Returns the value of the attribute with the specified name and namespace URI, or null if this element does not have such an attribute.
Parameters: localName the name of the attribute namespaceURI the namespace of the attribute
Returns: the value of the attribute of this element with the specified name and namespace
Returns the absolute base URI against which relative URIs in
this element should be resolved. xml:base
attributes in the same entity take precedence over the
actual base URI of the document where the element was found
or which was set by setBaseURI
.
This URI is made absolute before it is returned by resolving the information in this element against the information in its parent element and document entity. However, it is not always possible to fully absolutize the URI in all circumstances. In this case, this method returns the empty string to indicate the base URI of the current entity.
If the element's xml:base
attribute contains a
value that is a syntactically illegal URI (e.g. %GF.html"),
then the base URI is application dependent. XOM's choice is
to behave as if the element did not have an xml:base
attribute.
Returns: the base URI of this element
Returns a list of the child elements of this element with the specified name in no namespace. The elements returned are in document order.
Parameters: name the name of the elements included in the list
Returns: a comatose list containing the child elements of this element with the specified name
Returns a list of the immediate child elements of this element with the specified local name and namespace URI. Passing the empty string or null as the local name returns all elements in the specified namespace. Passing null or the empty string as the namespace URI returns elements with the specified name in no namespace. The elements returned are in document order.
Parameters: localName the name of the elements included in the list namespaceURI the namespace URI of the elements included in the list
Returns: a comatose list containing the child elements of this element with the specified name in the specified namespace
Returns a list of all the child elements of this element in document order.
Returns: a comatose list containing all child elements of this element
Returns the first child element with the specified name in no namespace. If there is no such element, it returns null.
Parameters: name the name of the element to return
Returns: the first child element with the specified local name in no namespace or null if there is no such element
Returns the first child element with the specified local name and namespace URI. If there is no such element, it returns null.
Parameters: localName the local name of the element to return namespaceURI the namespace URI of the element to return
Returns: the first child with the specified local name in the specified namespace, or null if there is no such element
Returns the local name of this element, not including the namespace prefix or colon.
Returns: the local name of this element
Returns the number of namespace declarations on this
element. This counts the namespace of the element
itself (which may be the empty string), the namespace
of each attribute, and each namespace added
by addNamespaceDeclaration
.
However, prefixes used multiple times are only counted
once; and the xml
prefix used for
xml:base
, xml:lang
, and
xml:space
is not counted even if one of these
attributes is present on the element.
The return value is almost always positive. It can be zero
if and only if the element itself has the prefix
xml
; e.g. <xml:space />
.
This is not endorsed by the XML specification. The prefix
xml
is reserved for use by the W3C, which has only
used it for attributes to date. You really shouldn't do this.
Nonetheless, this is not malformed so XOM allows it.
Returns: the number of namespaces declared by this element
Returns the prefix of this element, or the empty string if this element does not have a prefix.
Returns: the prefix of this element
Returns the indexth namespace prefix declared on
this element. Namespaces inherited from ancestors are not included.
The index is purely for convenience, and has no
meaning in itself. This includes the namespaces of the element
name and of all attributes' names (except for those with the
prefix xml
such as xml:space
) as well
as additional declarations made for attribute values and element
content. However, prefixes used multiple times (e.g. on several
attribute values) are only reported once. The default
namespace is reported with an empty string prefix if present.
Like most lists in Java, the first prefix is at index 0.
If the namespaces on the element change for any reason (adding or removing an attribute in a namespace, adding or removing a namespace declaration, changing the prefix of an element, etc.) then this method may skip or repeat prefixes. Don't change the prefixes of an element while iterating across them.
Parameters: index the prefix to return
Returns: the prefix
Throws: IndexOutOfBoundsException if index
is
negative or greater than or equal to the number of
namespaces declared by this element.
Returns the namespace URI of this element, or the empty string if this element is not in a namespace.
Returns: the namespace URI of this element
Returns the namespace URI mapped to the specified prefix within this element. Returns null if this prefix is not associated with a URI.
Parameters: prefix the namespace prefix whose URI is desired
Returns: the namespace URI mapped to prefix
Returns the complete name of this element, including the namespace prefix if this element has one.
Returns: the qualified name of this element
Returns the value of the element as defined by XPath 1.0. This is the complete PCDATA content of the element, without any tags, comments, or processing instructions after all entity and character references have been resolved.
Returns: XPath string value of this element
Converts a string to a text node and inserts that node at the specified position.
Parameters: position where to insert the child text the string to convert to a text node and insert
Throws: NullPointerException if text is null IndexOutOfBoundsException if the position is negative or greater than the number of children of the node
Removes an attribute from this element.
Parameters: attribute the attribute to remove
Returns: the attribute that was removed
Throws: NoSuchAttributeException if this element is not the parent of attribute
Detaches all children from this node.
Subclassers should note that the default implementation of this
method does not call removeChild
or detach
. If you override
removeChild
, you'll probably need to override this
method as well.
Returns: a list of all the children removed in the order they appeared in the element
Removes the mapping of the specified prefix. This method only
removes additional namespaces added with
addNamespaceDeclaration
.
It has no effect on namespaces of elements and attributes.
If the prefix is not used on this element, this method
does nothing.
Parameters: prefix the prefix whose declaration should be removed
Sets the URI from which this element was loaded,
and against which relative URLs in this element will be
resolved, unless an xml:base
attribute overrides
this. Setting the base URI to null or the empty string removes
any existing base URI.
Parameters: URI the new base URI for this element
Throws: MalformedURIException if URI
is
not a legal RFC 3986 absolute URI
Sets the local name of this element.
Parameters: localName the new local name
Throws: IllegalNameException if localName
is not
a legal, non-colonized name
Sets the namespace prefix of this element. You can pass null or the empty string to remove the prefix.
Parameters: prefix the new namespace prefix
Throws: IllegalNameException if prefix
is
not a legal XML non-colonized name NamespaceConflictException if prefix
is
already in use by an attribute or additional
namespace with a different URI than the element
itself
Sets the namespace URI of this element.
Parameters: uri the new namespace URI
Throws: MalformedURIException if uri
is not an absolute RFC 3986 URI reference NamespaceException if this element has a prefix
and uri
is null or the empty string;
or if the element's prefix is shared by an attribute
or additional namespace
Creates a very shallow copy of the element with the same name
and namespace URI, but no children, attributes, base URI, or
namespace declaration. This method is invoked as necessary
by the copy
method
and the
copy constructor
.
Subclasses should override this method so that it returns an instance of the subclass so that types are preserved when copying. This method should not add any attributes, namespace declarations, or children to the shallow copy. Any such items will be overwritten.
Returns: an empty element with the same name and namespace as this element
Returns a string representation of this element suitable for debugging and diagnosis. This is not the XML representation of the element.
Returns: a non-XML string representation of this element
Returns a string containing the XML serialization of this element. This includes the element and all its attributes and descendants. However, it does not contain namespace declarations for namespaces inherited from ancestor elements.
Returns: the XML representation of this element