nu.xom

## Class Node

- Object
- - nu.xom.Node

- Direct Known Subclasses:
    Attribute, Comment, DocType, Namespace, ParentNode, ProcessingInstruction, Text

      public abstract class Node
      extends Object

  The generic superclass for all the contents of an XML document. There are exactly eight kinds of nodes in XOM:

  - `Element`
  - `Document`
  - `Text`
  - `Comment`
  - `Attribute`
  - `ProcessingInstruction`
  - `DocType`
  - `Namespace`

  Every instance of `Node` is an instance of one of these eight classes (including, possibly, one of their subclasses).

  Version:
    1.3.1
  Author:
    Elliotte Rusty Harold

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Node` | `copy()` Returns a deep copy of this node with no parent, that can be added to the current document or a different one.
    `void` | `detach()` Removes this node from its parent so that it can be added to a different parent node or document.
    `boolean` | `equals(Object o)` Tests for node identity.
    `String` | `getBaseURI()` Returns the base URI of this node as specified by XML Base, or the empty string if this is not known.
    `abstract Node` | `getChild(int position)` Returns the child of this node at the specified position.
    `abstract int` | `getChildCount()` Returns the number of children of this node.
    `Document` | `getDocument()` Returns the document that contains this node, or null if this node is not currently part of a document.
    `ParentNode` | `getParent()` Returns the node that contains this node, or null if this node does not have a parent.
    `abstract String` | `getValue()` Returns the XPath 1.0 string-value of this node.
    `int` | `hashCode()` Returns a unique identifier for this node.
    `Nodes` | `query(String xpath)` Returns the nodes selected by the XPath expression in the context of this node in document order as defined by XSLT.
    `Nodes` | `query(String xpath, XPathContext namespaces)` Returns the nodes selected by the XPath expression in the context of this node in document order as defined in XSLT.
    `abstract String` | `toXML()` Returns the actual XML form of this node, such as might be copied and pasted from the original document.

    - ### Methods inherited from class Object

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

- - ### Method Detail

    - #### getValue

          public abstract String getValue()

      Returns the XPath 1.0 string-value of this node.

      Returns:
        the XPath 1.0 string-value of this node

    - #### getDocument

          public final Document getDocument()

      Returns the document that contains this node, or null if this node is not currently part of a document. Each node belongs to no more than one document at a time. If this node is a `Document`, then it returns this node.

      Returns:
        the document this node is a part of

    - #### getBaseURI

          public String getBaseURI()

      Returns the base URI of this node as specified by XML Base, or the empty string if this is not known. In most cases, this is the URL against which relative URLs in this node should be resolved.

      The base URI of a non-parent node is the base URI of the element containing the node. The base URI of a document node is the URI from which the document was parsed, or which was set by calling `setBaseURI` on on the document.

      The base URI of an element is determined as follows:

      - If the element has an `xml:base` attribute, then the value of that attribute is converted from an IRI to a URI, absolutized if possible, and returned.
      - Otherwise, if any ancestor element of the element loaded from the same entity has an `xml:base` attribute, then the value of that attribute from the nearest such ancestor is converted from an IRI to a URI, absolutized if possible, and returned. `xml:base` attributes from other entities are not considered.
      - Otherwise, if `setBaseURI()` has been invoked on this element, then the URI most recently passed to that method is absolutized if possible and returned.
      - Otherwise, if the element comes from an externally parsed entity or the document entity, and the original base URI has not been changed by invoking `setBaseURI()`, then the URI of that entity is returned.
      - Otherwise, (the element was created by a constructor rather then being parsed from an existing document), the base URI of the nearest ancestor that does have a base URI is returned. If no ancestors have a base URI, then the empty string is returned.

      Absolutization takes place as specified by the XML Base specification. However, it is not always possible to absolutize a relative URI, in which case the empty string will be returned.

      Returns:
        the base URI of this node

    - #### getParent

          public final ParentNode getParent()

      Returns the node that contains this node, or null if this node does not have a parent.

      Returns:
        the element or document that most immediately contains this node

    - #### detach

          public void detach()

      Removes this node from its parent so that it can be added to a different parent node or document. This method does nothing if the node does not have a parent.

      Throws:
        `XMLException` - if the parent refuses to detach this node

    - #### getChild

          public abstract Node getChild(int position)

      Returns the child of this node at the specified position.

      Parameters:
        `position` - the index of the child node to return
      Returns:
        the positionth child node of this node
      Throws:
        `IndexOutOfBoundsException` - if this node does not have children

    - #### getChildCount

          public abstract int getChildCount()

      Returns the number of children of this node. This is always non-negative (greater than or equal to zero).

      Returns:
        the number of children of this node

    - #### copy

          public abstract Node copy()

      Returns a deep copy of this node with no parent, that can be added to the current document or a different one.

      Per Bloch, the `Cloneable` interface is just a mess and should be avoided. However, I do not follow his suggestion of a copy constructor exclusively because it is useful to be able to copy a node without knowing its more specific type. Ken Arnold agrees with this. It's more effective for subclasses that can return an instance of the subclass.

      Returns:
        a copy of this node without a parent

    - #### toXML

          public abstract String toXML()

      Returns the actual XML form of this node, such as might be copied and pasted from the original document. However, this does not preserve semantically insignificant details such as white space inside tags or the use of empty-element tags vs. start-tag end-tag pairs.

      Returns:
        an XML representation of this node

    - #### equals

          public final boolean equals(Object o)

      Tests for node identity. That is, two `Node` objects are equal if and only if they are the same object.

      Overrides:
        `equals` in class `Object`
      Parameters:
        `o` - the object compared for equality to this node
      Returns:
        true if `o` is this node; false otherwise
      See Also:
        `Object.equals(Object)`

    - #### hashCode

          public final int hashCode()

      Returns a unique identifier for this node. The value returned is the same as returned by `super.hashCode()` because nodes use identity semantics.

      Overrides:
        `hashCode` in class `Object`
      Returns:
        a probably unique identifier for this node
      See Also:
        `Object.hashCode()`

    - #### query

          public final Nodes query(String xpath,
                                   XPathContext namespaces)

      Returns the nodes selected by the XPath expression in the context of this node in document order as defined in XSLT. All namespace prefixes used in the expression should be bound to namespace URIs by the second argument.

      Note that XPath expressions operate on the XPath data model, not the XOM data model. XPath counts all adjacent `Text` objects as a single text node, and does not consider empty `Text` objects. For instance, an element that has exactly three text children in XOM, will have exactly one text child in XPath, whose value is the concatenation of all three XOM `Text` objects.

      You can use XPath expressions that use the namespace axis. However, namespace nodes are never returned. If an XPath expression only selects namespace nodes, then this method will return an empty list.

      No variables are bound.

      The context position is the index of this node among its parents children, counting adjacent text nodes as one. The context size is the number of children this node's parent has, again counting adjacent text nodes as one node. If the parent is a `Document`, then the `DocType` (if any) is not counted. If the node has no parent, then the context position is 1, and the context size is 1.

      Queries such as /*, //, and /*//p that refer to the root node do work when operating with a context node that is not part of a document. However, the query / (return the root node) throws an `XPathException` when applied to a node that is not part of the document. Furthermore the top-level node in the tree is treated as the first and only child of the root node, not as the root node itself. For instance, this query stores `parent` in the `result` variable, not `child`:

            Element parent = new Element("parent");
             Element child = new Element("child");
             parent.appendChild(child);
             Nodes results = child.query("/*");
             Node result = result.get(0);

      Parameters:
        `xpath` - the XPath expression to evaluate
        `namespaces` - a collection of namespace prefix bindings used in the XPath expression
      Returns:
        a list of all matched nodes; possibly empty
      Throws:
        `XPathException` - if there's a syntax error in the expression, the query returns something other than a node-set

    - #### query

          public final Nodes query(String xpath)

      Returns the nodes selected by the XPath expression in the context of this node in document order as defined by XSLT. This XPath expression must not contain any namespace prefixes.

      No variables are bound. No namespace prefixes are bound.

      Parameters:
        `xpath` - the XPath expression to evaluate
      Returns:
        a list of all matched nodes; possibly empty
      Throws:
        `XPathException` - if there's a syntax error in the expression; or the query returns something other than a node-set

Copyright 2002-2020 Elliotte Rusty Harold
elharo@ibiblio.org