Class XdmNode
XdmItem
, and is therefore an
XdmValue
in its own right, and may also participate as one item within a sequence value.
An XdmNode is implemented as a wrapper around an object of type NodeInfo
.
Because this is a key interface within Saxon, it is exposed via this API.
The XdmNode interface exposes basic properties of the node, such as its name, its string value, and
its typed value. Navigation to other nodes is supported through a single method, axisIterator(net.sf.saxon.s9api.Axis)
,
which allows other nodes to be retrieved by following any of the XPath axes.
Note that node identity cannot be inferred from object identity. The same node may be represented
by different XdmNode
instances at different times, or even at the same time. The equals(java.lang.Object)
method on this class can be used to test for node identity.
Navigation from a node to other related nodes can be achieved using the XdmValue.select(Step)
method which this class inherits. Simple navigation to children or attributes can also be achieved using
the children()
and attribute(java.lang.String)
methods.
- Since:
- 9.0
- See Also:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionasSource()
Get a JAXP Source object corresponding to this node, allowing the node to be used as input to transformations or queries.Get the string value of a named attribute (in no namespace) of this elementaxisIterator
(Axis axis) Get an iterator over the nodes reachable from this node via a given axis.axisIterator
(Axis axis, QName name) Get an iterator over the nodes reachable from this node via a given axis, selecting only those nodes with a specified name.children()
Get the children of this nodeGet the element children of this node having a specified local name, irrespective of the namespaceGet the element children having a specified namespace URI and local nameGet the nodes found on the child axis that satisfy a suppliedPredicate
.boolean
Theequals()
relation between two XdmNode objects is true if they both represent the same node.getAttributeValue
(QName name) Get the string value of a named attribute of this elementGet the base URI of this nodeint
Get the column number of the node in a source document.Get the document URI of this node.In the case of an XdmNode that wraps a node in an external object model such as DOM, JDOM, XOM, or DOM4J, get the underlying wrapped nodeint
Get the line number of the node in a source document.Get the kind of node.Get the name of the node, as a QNameGet the parent of this nodegetRoot()
Get the root of the tree containing this node (which may or may not be a document node)Get the typed value of this node, as defined in XDMGet the underlying Saxon implementation object representing this node.Get the underlying implementation object representing the value.int
hashCode()
The hashcode is such that two XdmNode instances have the same hashCode if they represent the same node.stream()
Get a stream comprising the items in this valuetoString()
The toString() method returns a simple XML serialization of the node with defaulted serialization parameters.Methods inherited from class net.sf.saxon.s9api.XdmItem
asMap, getStringValue, getUnicodeStringValue, isAtomicValue, isNode, matches, size, wrapItem, wrapItem, wrapItem
Methods inherited from class net.sf.saxon.s9api.XdmValue
append, documentOrder, isEmpty, itemAt, iterator, makeSequence, makeValue, select, subsequence, wrap, wrap
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
Constructor Details
-
XdmNode
Construct an XdmNode as a wrapper around an existing NodeInfo object- Parameters:
node
- the NodeInfo object to be wrapped. This can be retrieved using thegetUnderlyingNode()
method.- Since:
- 9.2 (previously a protected constructor)
-
-
Method Details
-
getNodeKind
Get the kind of node.- Returns:
- the kind of node, for example
XdmNodeKind.ELEMENT
orXdmNodeKind.ATTRIBUTE
-
getProcessor
Get aProcessor
suitable for use with thisXdmNode
.In most cases this will be the original
Processor
object used to create theDocumentBuilder
that built the document that contains this node. If thatProcessor
is not available, it will be a compatibleProcessor
, one that shares the same underlyingConfiguration
, and hence is initialized with the same configuration settings, schema components, license features, and so on.Note: the only case where the original
Processor
is not available is when the sameConfiguration
is used with multiple APIs, for example mixing s9api and JAXP or XQJ in the same application.- Returns:
- a Processor suitable for performing further operations on this node, for example
for creating a
Serializer
or anXPathCompiler
. - Since:
- 9.9
-
getUnderlyingValue
Get the underlying implementation object representing the value. This method allows access to lower-level Saxon functionality, including classes and methods that offer no guarantee of stability across releases.- Overrides:
getUnderlyingValue
in classXdmItem
- Returns:
- the underlying implementation object representing the value
- Since:
- 9.8 (previously inherited from XdmValue which returns a Sequence)
-
getNodeName
Get the name of the node, as a QName- Returns:
- the name of the node. In the case of unnamed nodes (for example, text and comment nodes) return null.
-
getTypedValue
Get the typed value of this node, as defined in XDM- Returns:
- the typed value. If the typed value is a single atomic value, this will be returned
as an instance of
XdmAtomicValue
- Throws:
SaxonApiException
- if an error occurs obtaining the typed value, for example because the node is an element with element-only content
-
getLineNumber
public int getLineNumber()Get the line number of the node in a source document. For a document constructed using the document builder, this is available only if the line numbering option was set when the document was built (and then only for element nodes). If the line number is not available, the value -1 is returned. Line numbers will typically be as reported by a SAX parser: this means that the line number for an element node is the line number containing the closing ">" of the start tag.- Returns:
- the line number of the node, or -1 if not available.
-
getColumnNumber
public int getColumnNumber()Get the column number of the node in a source document. For a document constructed using the document builder, this is available only if the line numbering option was set when the document was built (and then only for element nodes). If the column number is not available, the value -1 is returned. Column numbers will typically be as reported by a SAX parser: this means that the column number for an element node is the position of the closing ">" of the start tag.- Returns:
- the column number of the node, or -1 if not available.
-
asSource
Get a JAXP Source object corresponding to this node, allowing the node to be used as input to transformations or queries.The Source object that is returned will generally be one that is acceptable to Saxon interfaces that expect an instance of
javax.xml.transform.Source
. However, there is no guarantee that it will be recognized by other products.In fact, the current implementation always returns an instance of
net.sf.saxon.om.NodeInfo
.- Returns:
- a Source object corresponding to this node
-
children
Get the children of this node- Returns:
- an
Iterable
containing all nodes on the child axis - Since:
- 9.9
-
children
Get the element children of this node having a specified local name, irrespective of the namespace- Parameters:
localName
- the local name of the child elements to be selected, or "*" to select all children that are element nodes- Returns:
- an
Iterable
containing the element children of this node that have the required local name. - Since:
- 9.9
-
children
Get the element children having a specified namespace URI and local name- Parameters:
uri
- the namespace URI of the child elements to be selected: supply a zero-length string to indicate the null namespacelocalName
- the local name of the child elements to be selected- Returns:
- an
Iterable
containing the element children of this node that have the required local name and namespace URI. - Since:
- 9.9
-
children
Get the nodes found on the child axis that satisfy a suppliedPredicate
.- Parameters:
filter
- the predicate to be applied- Returns:
- an
Iterable
containing those nodes found on the child axis that satisfy the suppliedPredicate
. - Since:
- 9.9
-
axisIterator
Get an iterator over the nodes reachable from this node via a given axis.Note: a more powerful way of achieving this is to use the
XdmValue.select(Step)
method which this class inherits.- Parameters:
axis
- identifies which axis is to be navigated- Returns:
- an iterator over the nodes on the specified axis, starting from this node as the context node. The nodes are returned in axis order, that is, in document order for a forwards axis and in reverse document order for a reverse axis.
-
axisIterator
Get an iterator over the nodes reachable from this node via a given axis, selecting only those nodes with a specified name.Note: a more powerful way of achieving this is to use the
XdmValue.select(Step)
method which this class inherits.- Parameters:
axis
- identifies which axis is to be navigatedname
- identifies the name of the nodes to be selected. The selected nodes will be those whose node kind is the principal node kind of the axis (that is, attributes for the attribute axis, namespaces for the namespace axis, and elements for all other axes) whose name matches the specified name.For example, specify
new QName("", "item")
to select nodes with local name "item", in no namespace.- Returns:
- an iterator over the nodes on the specified axis, starting from this node as the context node. The nodes are returned in axis order, that is, in document order for a forwards axis and in reverse document order for a reverse axis.
-
getParent
Get the parent of this node- Returns:
- the parent of this node (a document or element node), or null if this node has no parent.
-
getRoot
Get the root of the tree containing this node (which may or may not be a document node)- Returns:
- the root of the tree containing this node. Returns this node itself if it has no parent.
- Since:
- 9.9
-
getAttributeValue
Get the string value of a named attribute of this element- Parameters:
name
- the name of the required attribute- Returns:
- null if this node is not an element, or if this element has no attribute with the specified name. Otherwise return the string value of the selected attribute node.
-
attribute
Get the string value of a named attribute (in no namespace) of this element- Parameters:
name
- the name of the required attribute, interpreted as a no-namespace name- Returns:
- null if this node is not an element, or if this element has no attribute with the specified name. Otherwise return the string value of the selected attribute node.
- Since:
- 9.9
-
getBaseURI
Get the base URI of this node- Returns:
- the base URI, as defined in the XDM model. The value may be null if no base URI is known for the node, for example if the tree was built from a StreamSource with no associated URI, or if the node has no parent.
- Throws:
IllegalStateException
- if the base URI property of the underlying node is not a valid URI.
-
getDocumentURI
Get the document URI of this node.- Returns:
- the document URI, as defined in the XDM model. Returns null if no document URI is known
- Throws:
IllegalStateException
- if the document URI property of the underlying node is not a valid URI.- Since:
- 9.1
-
hashCode
public int hashCode()The hashcode is such that two XdmNode instances have the same hashCode if they represent the same node. Note that the same node might be represented by different XdmNode objects, but these will compare equal. -
equals
Theequals()
relation between two XdmNode objects is true if they both represent the same node. That is, it corresponds to the "is" operator in XPath. -
toString
The toString() method returns a simple XML serialization of the node with defaulted serialization parameters.In the case of an element node, the result will be a well-formed XML document serialized as defined in the W3C XSLT/XQuery serialization specification, using options method="xml", indent="yes", omit-xml-declaration="yes".
In the case of a document node, the result will be a well-formed XML document provided that the document node contains exactly one element child, and no text node children. In other cases it will be a well-formed external general parsed entity.
In the case of an attribute node, the output is a string in the form
name="value"
. The name will use the original namespace prefix.In the case of a namespace node, the output is a string in the form of a namespace declaration, that is
xmlns="uri"
orxmlns:pre="uri"
.Other nodes, such as text nodes, comments, and processing instructions, are represented as they would appear in lexical XML. Note: this means that in the case of text nodes, special characters such as
&
and<
are output in escaped form. To get the unescaped string value of a text node, useXdmItem.getStringValue()
instead.For more control over serialization, use the
Serializer
class. -
getUnderlyingNode
Get the underlying Saxon implementation object representing this node. This provides access to classes and methods in the Saxon implementation that may be subject to change from one release to another.- Returns:
- the underlying implementation object
-
getExternalNode
In the case of an XdmNode that wraps a node in an external object model such as DOM, JDOM, XOM, or DOM4J, get the underlying wrapped node- Returns:
- the underlying external node if there is one, or null if this is not an XdmNode that wraps such an external node
- Since:
- 9.1.0.2
-
stream
Get a stream comprising the items in this value
-