| java.lang.Object
 nu.xom.Node
nu.xom.ParentNode
nu.xom.Element
| Element | | public class Element extends ParentNode (Code) | |
This class represents an XML element. Each
element has the following properties:
- Local name
- Prefix (which may be null or the empty string)
- Namespace URI (which may be null or the empty string)
- A list of attributes
- A list of namespace declarations for this element
(not including those inherited from its parent)
- A list of child nodes
author:
Elliotte Rusty Harold
version:
1.1b3 |
| Method Summary | |
| public void | addAttribute(Attribute attribute)
Adds an attribute to this element, replacing any existing
attribute with the same local name and namespace URI. | | public void | addNamespaceDeclaration(String prefix, String uri)
Declares a namespace prefix. | | public void | appendChild(String text)
Converts a string to a text node
and appends that node to the children of this node. | | Iterator | attributeIterator()
| | static Element | build(String name, String uri, String localName)
| | public Node | copy()
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. | | void | fastAddAttribute(Attribute attribute)
| | final public 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. | | final public 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. | | final public Attribute | getAttribute(int index)
Selects an attribute by index.
The index is purely for convenience and has no particular
meaning. | | final public int | getAttributeCount()
Returns the number of attributes of this Element,
not counting namespace declarations. | | final public 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. | | final public 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. | | public String | getBaseURI()
Returns the absolute base URI against which relative URIs in
this element should be resolved. | | final public Elements | getChildElements(String name)
Returns a list of the child elements of
this element with the specified name in no namespace. | | final public 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. | | final public Elements | getChildElements()
Returns a list of all the child elements
of this element in document order. | | final public Element | getFirstChildElement(String name)
Returns the first child
element with the specified name in no namespace. | | final public Element | getFirstChildElement(String localName, String namespaceURI)
Returns the first child
element with the specified local name and namespace URI. | | final public String | getLocalName()
Returns the local name of this element, not including the
namespace prefix or colon. | | final String | getLocalNamespaceURI(String prefix)
| | final public int | getNamespaceDeclarationCount()
Returns the number of namespace declarations on this
element. | | final public String | getNamespacePrefix()
Returns the prefix of this element, or the empty string
if this element does not have a prefix. | | final public String | getNamespacePrefix(int index)
Returns the indexth namespace prefix declared on
this element. | | Map | getNamespacePrefixesInScope()
| | final public String | getNamespaceURI()
Returns the namespace URI of this element,
or the empty string if this element is not
in a namespace. | | final public String | getNamespaceURI(String prefix)
Returns the namespace URI mapped to the specified
prefix within this element. | | final public String | getQualifiedName()
Returns the complete name of this element, including the
namespace prefix if this element has one. | | final public String | getValue()
Returns the value of the element as defined by XPath 1.0. | | public void | insertChild(String text, int position)
Converts a string to a text node and inserts that
node at the specified position. | | void | insertionAllowed(Node child, int position)
Inserts a child node at the specified position.
Inserting at position 0 makes the child the first child
of this node. | | boolean | isElement()
| | public Attribute | removeAttribute(Attribute attribute)
Removes an attribute from this element. | | public Nodes | removeChildren()
Detaches all children from this node. | | public void | removeNamespaceDeclaration(String prefix)
Removes the mapping of the specified prefix. | | public 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 xml:base attribute overrides
this. | | public void | setLocalName(String localName)
Sets the local name of this element. | | public void | setNamespacePrefix(String prefix)
Sets the namespace prefix of this element. | | public 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. | | final public String | toString()
Returns a string representation of this element suitable
for debugging and diagnosis. | | final public String | toXML()
Returns a string containing the XML serialization of this
element. |
| Element | | public Element(String name)(Code) | |
Creates a new element in no namespace.
Parameters:
name - the name of the element
throws:
IllegalNameException - if nameis not a legal XML 1.0 non-colonized name |
| Element | | public Element(Element element)(Code) | |
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 |
| addAttribute | | public void addAttribute(Attribute attribute)(Code) | |
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 alreadyattached to an element
throws:
NamespaceConflictException - if the attribute's prefix is mapped to a different namespace URI than the same prefixis mapped to by this element, another attribute of this element, or an additional namespace declarationof this element |
| addNamespaceDeclaration | | public void addNamespaceDeclaration(String prefix, String uri)(Code) | |
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
Parameters:
uri - the absolute URI reference to map the prefix to
throws:
MalformedURIException - if URI is not an RFC 3986 URI reference
throws:
IllegalNameException - if prefix is not a legal XML non-colonized name
throws:
NamespaceConflictException - if the mapping conflicts with an existing element, attribute,or additional namespace declaration |
| appendChild | | public void appendChild(String text)(Code) | |
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
throws:
NullPointerException - if text is null |
| copy | | public Node copy()(Code) | |
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
nu.xom.Element.shallowCopy shallowCopy
method instead.
a deep copy of this element with no parent |
| getAttribute | | final public Attribute getAttribute(String name)(Code) | |
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 the attribute of this element with the specified name |
| getAttribute | | final public Attribute getAttribute(String localName, String namespaceURI)(Code) | |
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
Parameters:
namespaceURI - the namespace of the attribute the attribute of this element with the specified name and namespace |
| getAttribute | | final public Attribute getAttribute(int index)(Code) | |
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 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 |
| getAttributeCount | | final public int getAttributeCount()(Code) | |
Returns the number of attributes of this Element,
not counting namespace declarations.
This is always a non-negative number.
the number of attributes in the container |
| getAttributeValue | | final public String getAttributeValue(String name)(Code) | |
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 the value of the attribute of this element with the specified name |
| getAttributeValue | | final public String getAttributeValue(String localName, String namespaceURI)(Code) | |
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
Parameters:
namespaceURI - the namespace of the attribute the value of the attribute of this element with the specified name and namespace |
| getBaseURI | | public String getBaseURI()(Code) | |
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.
the base URI of this element |
| getChildElements | | final public Elements getChildElements(String name)(Code) | |
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 a comatose list containing the child elements of this element with the specified name |
| getChildElements | | final public Elements getChildElements(String localName, String namespaceURI)(Code) | |
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
Parameters:
namespaceURI - the namespace URI of the elements includedin the list a comatose list containing the child elements of this element with the specifiedname in the specified namespace |
| getChildElements | | final public Elements getChildElements()(Code) | |
Returns a list of all the child elements
of this element in document order.
a comatose list containing all child elements of this element |
| getFirstChildElement | | final public Element getFirstChildElement(String name)(Code) | |
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 the first child element with the specified local name in no namespace or null if there is no such element |
| getFirstChildElement | | final public Element getFirstChildElement(String localName, String namespaceURI)(Code) | |
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
Parameters:
namespaceURI - the namespace URI of the element to return the first child with the specified local name in thespecified namespace, or null if there is no such element |
| getLocalName | | final public String getLocalName()(Code) | |
Returns the local name of this element, not including the
namespace prefix or colon.
the local name of this element |
| getNamespaceDeclarationCount | | final public int getNamespaceDeclarationCount()(Code) | |
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.
the number of namespaces declared by this element |
| getNamespacePrefix | | final public String getNamespacePrefix()(Code) | |
Returns the prefix of this element, or the empty string
if this element does not have a prefix.
the prefix of this element |
| getNamespacePrefix | | final public String getNamespacePrefix(int index)(Code) | |
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 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 the prefix
throws:
IndexOutOfBoundsException - if index is negative or greater than or equal to the number of namespaces declared by this element. |
| getNamespacePrefixesInScope | | Map getNamespacePrefixesInScope()(Code) | | |
| getNamespaceURI | | final public String getNamespaceURI()(Code) | |
Returns the namespace URI of this element,
or the empty string if this element is not
in a namespace.
the namespace URI of this element |
| getNamespaceURI | | final public String getNamespaceURI(String prefix)(Code) | |
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 the namespace URI mapped to prefix |
| getQualifiedName | | final public String getQualifiedName()(Code) | |
Returns the complete name of this element, including the
namespace prefix if this element has one.
the qualified name of this element |
| getValue | | final public String getValue()(Code) | |
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.
XPath string value of this element |
| insertChild | | public void insertChild(String text, int position)(Code) | |
Converts a string to a text node and inserts that
node at the specified position.
Parameters:
position - where to insert the child
Parameters:
text - the string to convert to a text node and insert
throws:
NullPointerException - if text is null
throws:
IndexOutOfBoundsException - if the position is negativeor greater than the number of children of the node |
| insertionAllowed | | void insertionAllowed(Node child, int position)(Code) | |
Inserts a child node at the specified position.
Inserting at position 0 makes the child the first child
of this node. Inserting at the position
getChildCount()
makes the child the last child of the node.
All the other methods that add a node to the tree,
invoke this method ultimately.
Parameters:
position - where to insert the child
Parameters:
child - the node to insert
throws:
IllegalAddException - if child is a Document
throws:
MultipleParentException - if child already has a parent
throws:
NullPointerException - if child is null
throws:
IndexOutOfBoundsException - if the position is negative or greater than the number of children of this element. |
| isElement | | boolean isElement()(Code) | | |
| removeAttribute | | public Attribute removeAttribute(Attribute attribute)(Code) | |
Removes an attribute from this element.
Parameters:
attribute - the attribute to remove the attribute that was removed
throws:
NoSuchAttributeException - if this element is not the parent of attribute |
| removeChildren | | public Nodes removeChildren()(Code) | |
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.
a list of all the children removed in the order theyappeared in the element |
| removeNamespaceDeclaration | | public void removeNamespaceDeclaration(String prefix)(Code) | |
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 |
| setBaseURI | | public void setBaseURI(String URI)(Code) | |
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 |
| setLocalName | | public void setLocalName(String localName)(Code) | |
Sets the local name of this element.
Parameters:
localName - the new local name
throws:
IllegalNameException - if localName is nota legal, non-colonized name |
| setNamespacePrefix | | public void setNamespacePrefix(String prefix)(Code) | |
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
throws:
NamespaceConflictException - if prefix is already in use by an attribute or additionalnamespace with a different URI than the elementitself |
| setNamespaceURI | | public void setNamespaceURI(String uri)(Code) | |
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
throws:
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 attributeor additional namespace |
| shallowCopy | | protected Element shallowCopy()(Code) | |
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
nu.xom.Element.copy copy method
and the
nu.xom.Element.Element(nu.xom.Element) 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.
an empty element with the same name and namespace as this element |
| toString | | final public String toString()(Code) | |
Returns a string representation of this element suitable
for debugging and diagnosis. This is not
the XML representation of the element.
a non-XML string representation of this element |
| toXML | | final public String toXML()(Code) | |
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.
the XML representation of this element |
|
|