net.sf.saxon.s9api

## Class XdmNode

- java.lang.Object
- - net.sf.saxon.s9api.XdmValue
  - - net.sf.saxon.s9api.XdmItem
    - - net.sf.saxon.s9api.XdmNode

- All Implemented Interfaces:
    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() method on this class can be used to test for node identity.

  Since:
    9.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XdmNode(NodeInfo node)` Construct an XdmNode as a wrapper around an existing NodeInfo object

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Source` | `asSource()` Get a JAXP Source object corresponding to this node, allowing the node to be used as input to transformations or queries.
    `XdmSequenceIterator` | `axisIterator(Axis axis)` Get an iterator over the nodes reachable from this node via a given axis.
    `XdmSequenceIterator` | `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.
    `boolean` | `equals(Object other)` The `equals()` relation between two XdmNode objects is true if they both represent the same node.
    `String` | `getAttributeValue(QName name)` Get the string value of a named attribute of this element
    `URI` | `getBaseURI()` Get the base URI of this node
    `int` | `getColumnNumber()` Get the column number of the node in a source document.
    `URI` | `getDocumentURI()` Get the document URI of this node.
    `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
    `int` | `getLineNumber()` Get the line number of the node in a source document.
    `XdmNodeKind` | `getNodeKind()` Get the kind of node.
    `QName` | `getNodeName()` Get the name of the node, as a QName
    `XdmNode` | `getParent()` Get the parent of this node
    `Processor` | `getProcessor()` Get the Processor that was used to construct this node.
    `XdmValue` | `getTypedValue()` Get the typed value of this node, as defined in XDM
    `NodeInfo` | `getUnderlyingNode()` Get the underlying Saxon implementation object representing this node.
    `int` | `hashCode()` The hashcode is such that two XdmNode instances have the same hashCode if they represent the same node.
    `String` | `toString()` The toString() method returns a simple XML serialization of the node with defaulted serialization parameters.

    - ### Methods inherited from class net.sf.saxon.s9api.XdmItem

      `getStringValue, isAtomicValue, newAtomicValue, size, wrapItem`

    - ### Methods inherited from class net.sf.saxon.s9api.XdmValue

      `append, getUnderlyingValue, itemAt, iterator, setValue, wrap`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

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

    - #### getNodeKind

          public XdmNodeKind getNodeKind()

      Get the kind of node.
      Returns:
        the kind of node, for example `XdmNodeKind.ELEMENT` or `XdmNodeKind.ATTRIBUTE`

    - #### 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 atomic, 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

          public 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

    - #### axisIterator

          public XdmSequenceIterator axisIterator(Axis axis)

      Get an iterator over the nodes reachable from this node via a given axis.
      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 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.
      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.

    - #### getAttributeValue

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

    - #### getBaseURI

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

    - #### getDocumentURI

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

    - #### equals

          public boolean equals(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 `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

    - #### toString

          public String 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"` or `xmlns:pre="uri"`.

      Other nodes, such as text nodes, comments, and processing instructions, are represented as they would appear in lexical XML.

      For more control over serialization, use the `Serializer` class.

      Overrides:
        `toString` in class `Object`
      Returns:
        a simple XML serialization of the node. Under error conditions the method may return an error message which will always begin with the label "Error: ".

    - #### getProcessor

          public Processor getProcessor()

      Get the Processor that was used to construct this node.
      Returns:
        the Processor used to construct this node, either via a `DocumentBuilder`, or by executing XSLT or XQuery code.
      Since:
        9.2

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

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.