|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnu.xom.Node
nu.xom.ParentNode
nu.xom.Element
Represents an XML element. Each element has the following properties:
Constructor Summary | |
Element(Element element)
Creates a deep copy of an element. |
|
Element(java.lang.String name)
Creates a new element in no namespace. |
|
Element(java.lang.String name,
java.lang.String uri)
Creates a new element in a namespace. |
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(java.lang.String prefix,
java.lang.String uri)
Declares a namespace prefix. |
void |
appendChild(java.lang.String text)
Converts a string to a text node and appends that node to the children of this node. |
protected void |
checkAddAttribute(Attribute attribute)
Subclasses can override this method to perform additional checks on the specific attributes added to this element beyond what XML 1.0 requires. |
protected void |
checkAddNamespaceDeclaration(java.lang.String prefix,
java.lang.String uri)
Subclasses can override this method to perform additional checks on the specific namespace declarations added to this element beyond what Namespaces in XML requires. |
protected void |
checkLocalName(java.lang.String localName)
Subclasses can override this method to perform additional checks on the local name of the element. |
protected void |
checkNamespacePrefix(java.lang.String prefix)
Subclasses can override this method to perform additional checks on the namespace prefix of the element. |
protected void |
checkNamespaceURI(java.lang.String URI)
Subclasses can override this method to perform additional checks on the namespace URI of the element. |
protected void |
checkRemoveAttribute(Attribute attribute)
Subclasses can override this method to perform additional checks on the specific attributes removed from this element. |
protected void |
checkRemoveNamespaceDeclaration(java.lang.String prefix)
Subclasses can override this method to perform additional checks on the specific namespace declarations removed from elements beyond what Namespaces in XML requires. |
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(int index)
Selects an attribute by index. |
Attribute |
getAttribute(java.lang.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. |
Attribute |
getAttribute(java.lang.String localName,
java.lang.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. |
int |
getAttributeCount()
Returns the number of attributes of this Element ,
not counting namespace declarations. |
java.lang.String |
getAttributeValue(java.lang.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. |
java.lang.String |
getAttributeValue(java.lang.String localName,
java.lang.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. |
java.lang.String |
getBaseURI()
Returns the base URI against which relative URLs in this element should be resolved. |
Elements |
getChildElements()
Returns a list of all the immediate child elements of this element. |
Elements |
getChildElements(java.lang.String name)
Returns a list of the immediate child elements of this element with the specified name in no namespace. |
Elements |
getChildElements(java.lang.String localName,
java.lang.String namespaceURI)
Returns a list of the immediate child elements of this element with the specified local name and namespace URI. |
Element |
getFirstChildElement(java.lang.String name)
Returns the first child element with the specified name in no namespace. |
Element |
getFirstChildElement(java.lang.String localName,
java.lang.String namespaceURI)
Returns the first child element with the specified local name and namespace URI. |
java.lang.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. |
java.lang.String |
getNamespacePrefix()
Returns the prefix of this element, or the empty string if this element does not have a prefix. |
java.lang.String |
getNamespacePrefix(int index)
Returns the indexth namespace prefix declared on this element. |
java.lang.String |
getNamespaceURI()
Returns the namespace URI of this element, or the empty string if this element is not in a namespace. |
java.lang.String |
getNamespaceURI(java.lang.String prefix)
Returns the namespace URI mapped to the specified prefix within this element. |
java.lang.String |
getQualifiedName()
Returns the complete name of this element, including the namespace prefix if this element has one. |
java.lang.String |
getValue()
Returns the value of the element as defined by XPath 1.0. |
void |
insertChild(Node child,
int position)
Inserts a child node at the specified position. |
void |
insertChild(java.lang.String text,
int position)
Converts a string to a text node and inserts that node at the specified position. |
void |
removeAttribute(Attribute attribute)
Removes an attribute from this element. |
void |
removeChildren()
Detaches all children from this node. |
void |
removeNamespaceDeclaration(java.lang.String prefix)
Removes the mapping of the specified prefix. |
void |
setBaseURI(java.lang.String URI)
Sets the URI from which this element was loaded, and against which relative URLs in this node will be resolved, unless an xml:base attribute overrides this. |
void |
setLocalName(java.lang.String localName)
Sets the local name of this element. |
void |
setNamespacePrefix(java.lang.String prefix)
Sets the namespace prefix of this element. |
void |
setNamespaceURI(java.lang.String uri)
Sets the namespace URI of this element. |
java.lang.String |
toString()
Returns a string representation of this element suitable for debugging and diagnosis. |
java.lang.String |
toXML()
Returns a string containing the XML serialization of this element. |
Methods inherited from class nu.xom.ParentNode |
appendChild, checkInsertChild, checkRemoveChild, getChild, getChildCount, hasChildren, indexOf, removeChild, removeChild, replaceChild |
Methods inherited from class nu.xom.Node |
checkDetach, detach, equals, getDocument, getParent, hashCode |
Methods inherited from class java.lang.Object |
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Constructor Detail |
public Element(java.lang.String name)
Creates a new element in no namespace.
name
- the name of the element
IllegalNameException
- if name
is not a legal XML 1.0 non-colonized namepublic Element(java.lang.String name, java.lang.String uri)
Creates a new element in a namespace.
name
- the qualified name of the elementuri
- the namespace URI of the element
IllegalNameException
- if name
is not a legal XML 1.0 non-colonized name
NamespaceConflictException
- if name
's prefix
cannot be used with uri
MalformedURIException
- if uri
is not an RFC 2396 absolute URI referencepublic Element(Element element)
Creates a deep copy of an element. The copy is disconnected from the tree, and does not have a parent.
element
- the element to copyMethod Detail |
public final Elements getChildElements(java.lang.String name)
Returns a list of the immediate child elements of this element with the specified name in no namespace.
name
- the name of the elements included in the list
public final Elements getChildElements(java.lang.String localName, java.lang.String namespaceURI)
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.
localName
- the name of the elements included in the listnamespaceURI
- the namespace URI of the elements included
in the list
public final Elements getChildElements()
Returns a list of all the immediate child elements of this element.
public final Element getFirstChildElement(java.lang.String name)
Returns the first child element with the specified name in no namespace. If there is no such element, it returns null.
name
- the name of the element to return
public final Element getFirstChildElement(java.lang.String localName, java.lang.String namespaceURI)
Returns the first child element with the specified local name and namespace URI. If there is no such element, it returns null.
localName
- the local name of the element to returnnamespaceURI
- the namespace URI of the element to return
public final void addAttribute(Attribute attribute)
Adds an attribute to this element, replacing any existing attribute with the same local name and namespace URI.
attribute
- the attribute to add
IllegalAddException
- if the attribute already has a parent
NamespaceConflictException
- if the attribute's prefix
is mapped to a different namespace URI than the same prefix
is mapped to by the element itself, another attribute of
the same element, or an additional namespace declaration
of that element
XMLException
- if a subclass has rejected this attributeprotected void checkAddAttribute(Attribute attribute)
Subclasses can override this method to perform additional checks
on the specific attributes added to this element beyond what XML 1.0
requires. For example, an HTMLSpan
subclass might throw an exception
if any attribute were passed to this method which was not allowed
on an HTML span
element.
attribute
- The attribute to check.
XMLException
- if the proposed attribute
does not satisfy the local constraintspublic final void removeAttribute(Attribute attribute)
Removes an attribute from this element.
attribute
- the attribute to remove
java.lang.NullPointerException
- if the argument is null
XMLException
- if this element is not the parent
of attribute, or if removing the attribute
does not satisfy the local constraintsprotected void checkRemoveAttribute(Attribute attribute)
Subclasses can override this method to perform additional
checks on the specific attributes removed from this element.
For example, an XIncludeElement
subclass might
throw an exception if you tried to remove the href
attribute.
attribute
- The attribute to check.
XMLException
- if the proposed attribute
does not satisfy the local constraintspublic final Attribute getAttribute(java.lang.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.
name
- the name of the attribute
public final Attribute getAttribute(java.lang.String localName, java.lang.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.
localName
- the name of the attributenamespaceURI
- the namespace of the attribute
public final java.lang.String getAttributeValue(java.lang.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.
name
- the name of the attribute
public final int getAttributeCount()
Returns the number of attributes of this Element
,
not counting namespace declarations.
This is always a non-negative number.
public final Attribute getAttribute(int index)
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
attriubtes 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.
index
- the attribute to return
IndexOutofBoundsException
- if the index is negative
or greater than or equal to the number of attributes
of this elementpublic final java.lang.String getAttributeValue(java.lang.String localName, java.lang.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.
localName
- the name of the attributenamespaceURI
- the namespace of the attribute
public final java.lang.String getLocalName()
Returns the local name of this element, not including the namespace prefix or colon.
public final java.lang.String getQualifiedName()
Returns the complete name of this element, including the namespace prefix if this element has one.
public final java.lang.String getNamespacePrefix()
Returns the prefix of this element, or the empty string if this element does not have a prefix.
public final java.lang.String getNamespaceURI()
Returns the namespace URI of this element, or the empty string if this element is not in a namespace.
public final java.lang.String getNamespaceURI(java.lang.String prefix)
Returns the namespace URI mapped to the specified prefix within this element. Returns null if this prefix is not associated with a URI.
prefix
- the namespace prefix whose URI is desired
prefix
public final void setLocalName(java.lang.String localName)
Sets the local name of this element.
localName
- the new local name
IllegalNameException
- if localName
is not
a legal, non-colonized nameprotected void checkLocalName(java.lang.String localName)
Subclasses can override this method to perform
additional checks on the local name of the element.
For example, an SVGTextElement
subclass
might throw an exception if the local name were anything
other than text
.
localName
- the new local name for the element
XMLException
- if the local name is disallowedpublic final void setNamespaceURI(java.lang.String uri)
Sets the namespace URI of this element.
uri
- the new namespace URI
MalformedURIException
- if uri
is not an absolute RFC2396 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 namespaceprotected void checkNamespaceURI(java.lang.String URI)
Subclasses can override this method to perform additional
checks on the namespace URI of the element.
For example, an SVGElement
subclass
might throw an exception
if the namespace URI were anything other than
http://www.w3.org/TR/2000/svg/.
URI
- the new URI of the element.
XMLException
- if the namespace URI is disallowedpublic final void setNamespacePrefix(java.lang.String prefix)
Sets the namespace prefix of this element. You can pass null or the empty string to remove the prefix.
prefix
- the new namespace prefix
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
itselfprotected void checkNamespacePrefix(java.lang.String prefix)
Subclasses can override this method to perform additional
checks on the namespace prefix of the element.
For example, an XHTMLElement
subclass
might throw an exception
if the namespace prefix were anything other than
an empty string.
prefix
- the new prefix of the element
XMLException
- if the namespace prefix is disallowedpublic final void insertChild(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. 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.
insertChild
in class ParentNode
position
- where to insert the childchild
- the node to insert
IllegalAddException
- if child
is a Document
MultipleParentException
- if child
already has a parent
java.lang.NullPointerException
- if child
is null
java.lang.IndexOutOfBoundsException
- if the position is negative
or greater than the number of children of this element.public final void insertChild(java.lang.String text, int position)
Converts a string to a text node and inserts that node at the specified position.
position
- where to insert the childtext
- the string to convert to a text node and insert
IllegalAddException
- if this node cannot have this
text child
java.lang.NullPointerException
- if text is null
java.lang.IndexOutOfBoundsException
- if the position is negative
or greater than the number of children of the nodepublic final void appendChild(java.lang.String text)
Converts a string to a text node and appends that node to the children of this node.
text
- String to add to this node
IllegalAddException
- if this node cannot
have children of this type
java.lang.NullPointerException
- if text
is nullpublic final void removeChildren()
Detaches all children from this node.
public final void addNamespaceDeclaration(java.lang.String prefix, java.lang.String uri)
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.
prefix
- the prefix to declareuri
- the absolute URI reference to map the prefix to
MalformedURIException
- if URI
is not an RFC2396 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
XMLException
- if the namespace prefix and/or URI
is disallowed by a subclassprotected void checkAddNamespaceDeclaration(java.lang.String prefix, java.lang.String uri)
Subclasses can override this method to perform additional checks on the specific namespace declarations added to this element beyond what Namespaces in XML requires.
prefix
- the prefix to adduri
- the URI to add
XMLException
- if the namespace prefix
and/or URI is disallowedpublic final void removeNamespaceDeclaration(java.lang.String prefix)
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.
prefix
- the prefix whose declaration should be removed
XMLException
- if the namespace prefix cannot be removed
due to subclass constraintsprotected void checkRemoveNamespaceDeclaration(java.lang.String prefix)
Subclasses can override this method to perform additional checks on the specific namespace declarations removed from elements beyond what Namespaces in XML requires.
prefix
- The prefix that will be removed.
XMLException
- if the prefix cannot be removedpublic final int getNamespaceDeclarationCount()
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.
public final java.lang.String getNamespacePrefix(int index)
Returns the indexth namespace prefix declared on
this element. 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 changes 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.
index
- the prefix to return
java.lang.IndexOutOfBoundsException
- if index
is
negative or greater than or equal to the number of
namespaces declared by this element.public final void setBaseURI(java.lang.String URI)
Sets the URI from which this element was loaded,
and against which relative URLs in this node will be resolved,
unless an xml:base
attribute overrides this.
setBaseURI
in class ParentNode
URI
- the new base URI for this node
MalformedURIException
- if URI
is
not a legal RFC 2396 URIpublic final java.lang.String getBaseURI()
Returns the base URI against which relative URLs in this
element should be resolved.
xml:base
attributes take precedence over the
actual base URI.
If possible, 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. Sometimes, a relative URI may be returned instead. If the base URI cannot be determined, this method returns null.
getBaseURI
in class Node
Node.getBaseURI()
public final java.lang.String toXML()
Returns a string containing the XML serialization of this element. This includes the element and all its attributes and descendants. However, it may not contain namespace declarations for namespaces inherited from ancestor elements.
toXML
in class Node
Node.toXML()
public final java.lang.String getValue()
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.
getValue
in class Node
Node.getValue()
public Node copy()
Creates a deep copy of this element with no parent, that can be added to this document or a different one.
copy
in class Node
Node.copy()
public final java.lang.String toString()
Returns a string representation of this element suitable for debugging and diagnosis. This is not the XML representation of the element.
toString
in class Node
Object.toString()
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |