Package net.sf.saxon.s9api

Class XdmNode

  • All Implemented Interfaces:
    java.lang.Iterable<XdmItem>
    public class XdmNode
extends XdmItem
    This class represents a node in the XDM data model. A Node is an 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:
    SaplingDocument.toXdmNode(Processor), SaplingElement.toXdmNode(Processor)

    • Constructor Detail

      • XdmNode

        public XdmNode​(NodeInfo node)
        Construct an XdmNode as a wrapper around an existing NodeInfo object
        Parameters:
        node - the NodeInfo object to be wrapped. This can be retrieved using the getUnderlyingNode() method.
        Since:
        9.2 (previously a protected constructor)

    • Method Detail

      • getProcessor

        public Processor getProcessor()
        Get a Processor suitable for use with this XdmNode.

        In most cases this will be the original Processor object used to create the DocumentBuilder that built the document that contains this node. If that Processor is not available, it will be a compatible Processor, one that shares the same underlying Configuration, 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 same Configuration 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 an XPathCompiler.
        Since:
        9.9

      • getUnderlyingValue

        public NodeInfo 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 class XdmItem
        Returns:
        the underlying implementation object representing the value
        Since:
        9.8 (previously inherited from XdmValue which returns a Sequence)

      • getNodeName

        public QName 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

        public XdmValue getTypedValue()
                       throws SaxonApiException
        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

      • getTypeAnnotationName

        public QName getTypeAnnotationName()
        Get the name of the type annotation of this node.

        If the node is an element or attribute node that has been validated against a schema, the result will be the name of the schema type (complex or simple type) against which it was validated. If this is an anonymous type, a system-generated name is returned, having the namespace http://ns.saxonica.com/anonymous-type.

        If the node is an element or attribute node that has not been validated against a schema, the result will be xs:untyped or xs:untypedAtomic respectively.

        For a document node, the method returns xs:anyType if the document has been validated, or xs:untyped otherwise.

        If the node is any other kind of node, the result will be null.

        Returns:
        the type annotation of the node, or null

      • 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

        public javax.xml.transform.Source 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

        public java.lang.Iterable<XdmNode> children()
        Get the children of this node
        Returns:
        an Iterable containing all nodes on the child axis
        Since:
        9.9

      • children

        public java.lang.Iterable<XdmNode> children​(java.lang.String localName)
        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

        public java.lang.Iterable<XdmNode> children​(java.lang.String uri,
                                            java.lang.String localName)
        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 namespace
        localName - 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

        public java.lang.Iterable<XdmNode> children​(java.util.function.Predicate<? super XdmNode> filter)
        Get the nodes found on the child axis that satisfy a supplied Predicate.
        Parameters:
        filter - the predicate to be applied
        Returns:
        an Iterable containing those nodes found on the child axis that satisfy the supplied Predicate.
        Since:
        9.9

      • axisIterator

        public XdmSequenceIterator<XdmNode> axisIterator​(Axis axis)
        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

        public XdmSequenceIterator<XdmNode> 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.

        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
        name - 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

        public XdmNode 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

        public XdmNode 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

      • getOutermostElement

        public XdmNode getOutermostElement()
        Get the outermost element of the tree containing this node.

        If this node is a document node, the method returns the first child node that is an element (ignoring any subsequent element nodes); if there is no element child, the method returns null. In other words, the method returns child::*[1]

        In all other cases, the method finds the outermost ancestor-of-self element whose parent is either a document node or absent: that is, it returns ancestor-or-self::*[last()]. If there is no such ancestor, the method returns null.

        Since:
        12.0

      • getAttributeValue

        public java.lang.String getAttributeValue​(QName name)
        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

        public java.lang.String attribute​(java.lang.String name)
        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

        public java.net.URI 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:
        java.lang.IllegalStateException - if the base URI property of the underlying node is not a valid URI.

      • getDocumentURI

        public java.net.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:
        java.lang.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.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hashCode representing node identity

      • equals

        public boolean equals​(java.lang.Object other)
        The equals() relation between two XdmNode objects is true if they both represent the same node. That is, it corresponds to the "is" operator in XPath.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        other - the object to be compared
        Returns:
        true if and only if the other object is an XdmNode instance representing the same node

      • getUnderlyingNode

        public NodeInfo 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

        public java.lang.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

        public XdmStream<XdmNode> stream()
        Get a stream comprising the items in this value
        Overrides:
        stream in class XdmItem
        Returns:
        a Stream over the items in this value
        Since:
        9.9