public interface NodeInfo extends Item, Location, ActiveSource
Note that several NodeInfo objects may represent the same node. To test node identity, the
method equals(Object)
should be used. An exception to this rule applies for
document nodes, where the correspondence between document nodes and DocumentInfo objects is one to
one. NodeInfo objects are never reused: a given NodeInfo object represents the same node for its entire
lifetime.
This is the primary interface for accessing trees in Saxon, and it forms part of the public Saxon API. Methods that form part of the public API are (since Saxon 8.4) labelled with a JavaDoc "since" tag: classes and methods that have no such label should not be regarded as stable interfaces.
The interface represented by this class is at a slightly higher level than the abstraction described
in the W3C data model specification, in that it includes support for the XPath axes, rather than exposing
the lower-level properties (such as "parent" and "children") directly. All navigation within trees,
except for a few convenience methods, is done by following the axes using the iterateAxis(int)
method.
This allows different implementations of the XPath tree model to implement axis navigation in different ways.
Some implementations may choose to use the helper methods provided in class Navigator
.
Note that the stability of this interface applies to classes that use the interface, not to classes that implement it. The interface may be extended in future to add new methods.
New implementations of NodeInfo are advised also to implement the methods in interface ExtendedNodeInfo, which will be moved into this interface at some time in the future.
Modifier and Type | Method and Description |
---|---|
default ActiveSource |
asActiveSource()
Obtain an
ActiveSource object that allows the node to be used as input
to any method that expects a Source |
AtomicSequence |
atomize()
Get the typed value.
|
default AttributeMap |
attributes() |
default java.lang.Iterable<? extends NodeInfo> |
children()
Return the sequence of children of this node, as an
Iterable . |
default java.lang.Iterable<? extends NodeInfo> |
children(NodePredicate filter) |
int |
compareOrder(NodeInfo other)
Determine the relative position of this node and another node, in document order.
|
default void |
copy(Receiver out,
int copyOptions,
Location locationId)
Copy this node to a given Receiver.
|
default void |
deliver(Receiver receiver,
ParseOptions options)
Implement the
ActiveSource interface by delivering the document to a
Receiver |
boolean |
equals(java.lang.Object other)
The equals() method compares nodes for identity.
|
void |
generateId(java.lang.StringBuilder buffer)
Construct a character string that uniquely identifies this node.
|
NamespaceMap |
getAllNamespaces()
Get all the namespace bindings that are in-scope for this element.
|
java.lang.String |
getAttributeValue(java.lang.String uri,
java.lang.String local)
Get the string value of a given attribute of this node
|
java.lang.String |
getBaseURI()
Get the Base URI for the node, that is, the URI used for resolving a relative URI contained
in the node.
|
default int |
getColumnNumber()
Get column number.
|
default Configuration |
getConfiguration()
Convenience method to get the Configuration.
|
NamespaceBinding[] |
getDeclaredNamespaces(NamespaceBinding[] buffer)
Get all namespace declarations and undeclarations defined on this element.
|
java.lang.String |
getDisplayName()
Get the display name of this node, in the form of a lexical QName.
|
int |
getFingerprint()
Get fingerprint.
|
default Genre |
getGenre()
Get the genre of this item
|
default int |
getLineNumber()
Get line number.
|
java.lang.String |
getLocalPart()
Get the local part of the name of this node.
|
int |
getNodeKind()
Get the kind of node.
|
NodeInfo |
getParent()
Get the NodeInfo object representing the parent of this node
|
java.lang.String |
getPrefix()
Get the prefix of the name of the node.
|
default java.lang.String |
getPublicId()
Get the Public ID of the entity containing the node.
|
NodeInfo |
getRoot()
Get the root node of the tree containing this node
|
default SchemaType |
getSchemaType()
Get the type annotation of this node, if any.
|
java.lang.String |
getSystemId()
Get the System ID for the node.
|
TreeInfo |
getTreeInfo()
Get information about the tree to which this NodeInfo belongs
|
java.lang.String |
getURI()
Get the URI part of the name of this node.
|
boolean |
hasChildNodes()
Determine whether the node has any children.
|
boolean |
hasFingerprint()
Ask whether this NodeInfo implementation holds a fingerprint identifying the name of the
node in the NamePool.
|
int |
hashCode()
The hashCode() method obeys the contract for hashCode(): that is, if two objects are equal
(represent the same node) then they must have the same hashCode()
|
default boolean |
isId()
Ask whether this node has the is-id property
|
default boolean |
isIdref()
Ask whether this node has the is-idref property
|
default boolean |
isNilled()
Ask whether the node has the is-nilled property
|
default boolean |
isSameNodeInfo(NodeInfo other)
Determine whether this is the same node as another node.
|
default boolean |
isStreamed()
Ask whether this is a node in a streamed document
|
default AxisIterator |
iterateAxis(int axisNumber)
Return an iteration over all the nodes reached by the given axis from this node
|
AxisIterator |
iterateAxis(int axisNumber,
NodePredicate predicate)
Return an iteration over all the nodes reached by the given axis from this node
that match a given NodeTest
|
void |
setSystemId(java.lang.String systemId) |
default java.lang.String |
toShortString()
Provide a short string showing the contents of the item, suitable
for use in error messages
|
getLength, getStringValue, getUnicodeStringValue, head, itemAt, iterate, reduce, subsequence
asIterable, concatenate, containsNode, effectiveBooleanValue, materialize
makeRepeatable
saveLocation
TreeInfo getTreeInfo()
default Configuration getConfiguration()
getTreeInfo().getConfiguration()
getTreeInfo().getConfiguration()
.int getNodeKind()
Type.ELEMENT
or Type.ATTRIBUTE
. There are seven kinds of node: documents, elements, attributes,
text, comments, processing-instructions, and namespaces.Type
default boolean isSameNodeInfo(NodeInfo other)
Note that two different NodeInfo instances can represent the same conceptual node. Therefore the "==" operator should not be used to test node identity. The equals() method should give the same result as isSameNodeInfo(), but since this rule was introduced late it might not apply to all implementations.
Note: a.isSameNodeInfo(b) if and only if generateId(a)==generateId(b).
This method has the same semantics as isSameNode() in DOM Level 3, but works on Saxon NodeInfo objects rather than DOM Node objects.
From Saxon 9.9 this method has a default implementation that invokes equals()
,
and all Saxon implementations of NodeInfo
rely on this default implementation.
The method is retained for backwards compatibility, but applications are advised to
use the equals()
method in preference, and user-defined implementations of
NodeInfo
are advised to rely on the default implementation. In particular,
implementations of equals()
should not invoke isSameNodeInfo
.
other
- the node to be compared with this nodeequals(other)
boolean equals(java.lang.Object other)
equals
in class java.lang.Object
other
- the node to be compared with this nodeint hashCode()
hashCode
in class java.lang.Object
java.lang.String getSystemId()
getSystemId
in interface Location
getSystemId
in interface org.xml.sax.Locator
getSystemId
in interface javax.xml.transform.Source
getSystemId
in interface javax.xml.transform.SourceLocator
default java.lang.String getPublicId()
Locator
or SourceLocator
, and many implementations return null.getPublicId
in interface Location
getPublicId
in interface org.xml.sax.Locator
getPublicId
in interface javax.xml.transform.SourceLocator
java.lang.String getBaseURI()
default int getLineNumber()
The granularity of line numbering is normally the element level: for other nodes such as text nodes and attributes, the line number of the parent element will normally be returned.
In the case of a tree constructed by taking input from a SAX parser, the line number will reflect the SAX rules: that is, the line number of an element is the line number where the start tag ends. This may be a little confusing where elements have many attributes spread over multiple lines, or where single attributes (as can easily happen with XSLT 2.0 stylesheets) occupy several lines.
In the case of a tree constructed by a stylesheet or query, the line number may reflect the line in the stylesheet or query that caused the node to be constructed.
The line number can be read from within an XPath expression using the Saxon extension function saxon:line-number()
getLineNumber
in interface Location
getLineNumber
in interface org.xml.sax.Locator
getLineNumber
in interface javax.xml.transform.SourceLocator
default int getColumnNumber()
The granularity of column numbering is normally the element level: for other nodes such as text nodes and attributes, the line number of the parent element will normally be returned.
In the case of a tree constructed by taking input from a SAX parser, the column number will reflect the SAX rules: that is, the column number of an element is the column number where the start tag ends. This may be a little confusing where elements have many attributes spread over multiple lines, or where single attributes (as can easily happen with XSLT 2.0 stylesheets) occupy several lines.
In the case of a tree constructed by a stylesheet or query, the column number may reflect the line in the stylesheet or query that caused the node to be constructed.
The column number can be read from within an XPath expression using the Saxon extension function saxon:column-number()
getColumnNumber
in interface Location
getColumnNumber
in interface org.xml.sax.Locator
getColumnNumber
in interface javax.xml.transform.SourceLocator
int compareOrder(NodeInfo other)
The other node must always be in the same tree; the effect of calling this method when the two nodes are in different trees is undefined. To obtain a global ordering of nodes, the application should first compare the result of getDocumentNumber(), and only if the document number is the same should compareOrder() be called.
other
- The other node, whose position is to be compared with this
nodeboolean hasFingerprint()
getFingerprint()
method must
return the fingerprint of the node. If the answer is false, then the getFingerprint()
method should throw an UnsupportedOperationException
. In the case of unnamed nodes
such as text nodes, the result can be either true (in which case getFingerprint() should
return -1) or false (in which case getFingerprint may throw an exception).FingerprintedNode
as a marker interface.int getFingerprint()
java.lang.UnsupportedOperationException
- if this kind of node does not hold
namepool fingerprints (specifically, if hasFingerprint()
returns false).java.lang.String getLocalPart()
java.lang.String getURI()
java.lang.String getDisplayName()
java.lang.String getPrefix()
default SchemaType getSchemaType()
Types derived from a DTD are not reflected in the result of this method.
The default implementation returns BuiltInAtomicType.UNTYPED_ATOMIC
for attribute
nodes, Untyped.getInstance()
for element and document nodes, and null otherwise
AtomicSequence atomize() throws XPathException
atomize
in interface Item
XPathException
- if the node has no typed value, for example if
it is an element node with element-only contentNodeInfo getParent()
default AxisIterator iterateAxis(int axisNumber)
axisNumber
- an integer identifying the axis; one of the constants
defined in class AxisInfo
iterateAxis(axisNumber, AnyNodeTest.getInstance()
.java.lang.UnsupportedOperationException
- if the namespace axis is
requested and this axis is not supported for this implementation.AxisInfo
AxisIterator iterateAxis(int axisNumber, NodePredicate predicate)
axisNumber
- an integer identifying the axis; one of the constants
defined in class AxisInfo
predicate
- A condition to be satisfied by the returned nodes; nodes
that do not satisfy this condition are not included in the resultjava.lang.UnsupportedOperationException
- if the namespace axis is
requested and this axis is not supported for this implementation.Predicate<NodeInfo>
as the second argument. It is still
possible to supply a NodeTest
, because NodeTest
implements Predicate<NodeInfo>
.AxisInfo
java.lang.String getAttributeValue(java.lang.String uri, java.lang.String local)
uri
- the namespace URI of the attribute name. Supply the empty string for an attribute
that is in no namespacelocal
- the local part of the attribute name.NodeInfo getRoot()
boolean hasChildNodes()
Note: the result is equivalent to
iterateAxis(Axis.CHILD).next() != null
default java.lang.Iterable<? extends NodeInfo> children()
Iterable
. This
method is designed to allow iteration over the children in a Java "for each" loop,
in the form for (NodeInfo child : children()) {...}
Iterable
.default java.lang.Iterable<? extends NodeInfo> children(NodePredicate filter)
default AttributeMap attributes()
void generateId(java.lang.StringBuilder buffer)
buffer
- a buffer which will be updated to hold a string
that uniquely identifies this node, across all documents.Changed in Saxon 8.7 to generate the ID value in a client-supplied buffer
default void copy(Receiver out, int copyOptions, Location locationId) throws XPathException
This method is primarily for internal use. It should not be considered a stable part of the Saxon API.
The default implementation invokes Navigator.copy(this, out, copyOptions, locationId);
which
is always adequate.
out
- the Receiver to which the node should be copied. It is the caller's
responsibility to ensure that this Receiver is open before the method is called
(or that it is self-opening), and that it is closed after use.copyOptions
- a selection of the options defined in CopyOptions
locationId
- If non-null, identifies the location of the instruction
that requested this copy. If null, indicates that the location information
is not availableXPathException
- if any downstream error occursjava.lang.IllegalArgumentException
- if the node is an attribute or namespace nodedefault void deliver(Receiver receiver, ParseOptions options) throws XPathException
ActiveSource
interface by delivering the document to a
Receiver
deliver
in interface ActiveSource
receiver
- the receiver to which events representing the parsed XML document will be sentoptions
- options for parsing the sourceXPathException
- if the receiver reports a failure, for example a validation failuredefault ActiveSource asActiveSource()
ActiveSource
object that allows the node to be used as input
to any method that expects a Source
ActiveSource
object representing this nodevoid setSystemId(java.lang.String systemId)
setSystemId
in interface javax.xml.transform.Source
NamespaceBinding[] getDeclaredNamespaces(NamespaceBinding[] buffer)
This method is intended primarily for internal use. User applications needing
information about the namespace context of a node should use iterateAxis(Axis.NAMESPACE)
.
(However, not all implementations support the namespace axis, whereas all implementations are
required to support this method.)
In many cases (and in particular with Saxon's TinyTree and LinkedTree implementations),
from 10.0 onwards it is more efficient to call getAllNamespaces()
to get all the in-scope
namespaces at once, rather than building up the list be calling getDeclaredNamespaces
on
each ancestor node.
buffer
- If this is non-null, and the result array fits in this buffer, then the result
may overwrite the contents of this array, to avoid the cost of allocating a new array on the heap.For a node other than an element, the method returns null.
NamespaceMap getAllNamespaces()
For an element return all the prefix-to-uri bindings that are in scope. This may include a binding to the default namespace (represented by a prefix of ""). The map does NOT include the implicit binding of the XML namespace. It will never include "undeclarations" - that is, the namespace URI will never be empty; the effect of an undeclaration is to remove a binding from the in-scope namespaces, not to add anything.
For a node other than an element, returns null.
default boolean isId()
default boolean isIdref()
default boolean isNilled()
default boolean isStreamed()
isStreamed
in interface Item
default java.lang.String toShortString()
toShortString
in interface GroundedValue
toShortString
in interface Item
document-node()
for a document node<p:local/>
for an element node@p:local
for an attribute nodetext("In a hole...")
for a text node<--You are old, ...-->
for a comment node<?pi?>
for a processing instruction nodexmlns:p=uri
for a namespace nodedefault Genre getGenre()
getGenre
in interface Item
Genre.NODE
. The default implementation (which should not
be overridden) returns Genre.NODE
.Copyright (c) 2004-2022 Saxonica Limited. All rights reserved.