XPath (JDOM v1.1.1)
Date: 2019-09-02

org.jdom.xpath

## Class XPath

- java.lang.Object
- - org.jdom.xpath.XPath

- All Implemented Interfaces:
    java.io.Serializable

      public abstract class XPath
      extends java.lang.Object
      implements java.io.Serializable

  A utility class for performing XPath calls on JDOM nodes, with a factory interface for obtaining a first XPath instance. Users operate against this class while XPath vendors can plug-in implementations underneath. Users can choose an implementation using either `setXPathClass(java.lang.Class)` or the system property "org.jdom.xpath.class".
  Version:
    $Revision: 1.17 $, $Date: 2007/11/10 05:29:02 $
  Author:
    Laurent Bihanic
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `JDOM_OBJECT_MODEL_URI` The string passable to the JAXP 1.3 XPathFactory isObjectModelSupported() method to query an XPath engine regarding its support for JDOM.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XPath()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `addNamespace(Namespace namespace)` Adds a namespace definition to the list of namespaces known of this XPath expression.
    `void` | `addNamespace(java.lang.String prefix, java.lang.String uri)` Adds a namespace definition (prefix and URI) to the list of namespaces known of this XPath expression.
    `abstract java.lang.String` | `getXPath()` Returns the wrapped XPath expression as a string.
    `static XPath` | `newInstance(java.lang.String path)` Creates a new XPath wrapper object, compiling the specified XPath expression.
    `abstract java.lang.Number` | `numberValueOf(java.lang.Object context)` Returns the number value of the first node selected by applying the wrapped XPath expression to the given context.
    `abstract java.util.List` | `selectNodes(java.lang.Object context)` Evaluates the wrapped XPath expression and returns the list of selected items.
    `static java.util.List` | `selectNodes(java.lang.Object context, java.lang.String path)` Evaluates an XPath expression and returns the list of selected items.
    `abstract java.lang.Object` | `selectSingleNode(java.lang.Object context)` Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).
    `static java.lang.Object` | `selectSingleNode(java.lang.Object context, java.lang.String path)` Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).
    `abstract void` | `setVariable(java.lang.String name, java.lang.Object value)` Defines an XPath variable and sets its value.
    `static void` | `setXPathClass(java.lang.Class aClass)` Sets the concrete XPath subclass to use when allocating XPath instances.
    `abstract java.lang.String` | `valueOf(java.lang.Object context)` Returns the string value of the first node selected by applying the wrapped XPath expression to the given context.
    `protected java.lang.Object` | `writeReplace()` [Serialization support] Returns the alternative object to write to the stream when serializing this object.

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

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

- - ### Field Detail

    - #### JDOM_OBJECT_MODEL_URI

          public static final java.lang.String JDOM_OBJECT_MODEL_URI

      The string passable to the JAXP 1.3 XPathFactory isObjectModelSupported() method to query an XPath engine regarding its support for JDOM. Defined to be the well-known URI "http://jdom.org/jaxp/xpath/jdom".
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XPath

          public XPath()

  - ### Method Detail

    - #### newInstance

          public static XPath newInstance(java.lang.String path)
                                   throws JDOMException

      Creates a new XPath wrapper object, compiling the specified XPath expression.
      Parameters:
        `path` - the XPath expression to wrap.
      Throws:
        `JDOMException` - if the XPath expression is invalid.

    - #### setXPathClass

          public static void setXPathClass(java.lang.Class aClass)
                                    throws JDOMException

      Sets the concrete XPath subclass to use when allocating XPath instances.
      Parameters:
        `aClass` - the concrete subclass of XPath.
      Throws:
        `java.lang.IllegalArgumentException` - if `aClass` is `null`.
        `JDOMException` - if `aClass` is not a concrete subclass of XPath.

    - #### selectNodes

          public abstract java.util.List selectNodes(java.lang.Object context)
                                              throws JDOMException

      Evaluates the wrapped XPath expression and returns the list of selected items.
      Parameters:
        `context` - the node to use as context for evaluating the XPath expression.
      Returns:
        the list of selected items, which may be of types: `Element`, `Attribute`, `Text`, `CDATA`, `Comment`, `ProcessingInstruction`, Boolean, Double, or String.
      Throws:
        `JDOMException` - if the evaluation of the XPath expression on the specified context failed.

    - #### selectSingleNode

          public abstract java.lang.Object selectSingleNode(java.lang.Object context)
                                                     throws JDOMException

      Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).
      Parameters:
        `context` - the node to use as context for evaluating the XPath expression.
      Returns:
        the first selected item, which may be of types: `Element`, `Attribute`, `Text`, `CDATA`, `Comment`, `ProcessingInstruction`, Boolean, Double, String, or `null` if no item was selected.
      Throws:
        `JDOMException` - if the evaluation of the XPath expression on the specified context failed.

    - #### valueOf

          public abstract java.lang.String valueOf(java.lang.Object context)
                                            throws JDOMException

      Returns the string value of the first node selected by applying the wrapped XPath expression to the given context.
      Parameters:
        `context` - the element to use as context for evaluating the XPath expression.
      Returns:
        the string value of the first node selected by applying the wrapped XPath expression to the given context.
      Throws:
        `JDOMException` - if the XPath expression is invalid or its evaluation on the specified context failed.

    - #### numberValueOf

          public abstract java.lang.Number numberValueOf(java.lang.Object context)
                                                  throws JDOMException

      Returns the number value of the first node selected by applying the wrapped XPath expression to the given context.
      Parameters:
        `context` - the element to use as context for evaluating the XPath expression.
      Returns:
        the number value of the first node selected by applying the wrapped XPath expression to the given context, `null` if no node was selected or the special value `Double.NaN` (Not-a-Number) if the selected value can not be converted into a number value.
      Throws:
        `JDOMException` - if the XPath expression is invalid or its evaluation on the specified context failed.

    - #### setVariable

          public abstract void setVariable(java.lang.String name,
                                           java.lang.Object value)

      Defines an XPath variable and sets its value.
      Parameters:
        `name` - the variable name.
        `value` - the variable value.
      Throws:
        `java.lang.IllegalArgumentException` - if `name` is not a valid XPath variable name or if the value type is not supported by the underlying implementation

    - #### addNamespace

          public abstract void addNamespace(Namespace namespace)

      Adds a namespace definition to the list of namespaces known of this XPath expression.

      Note: In XPath, there is no such thing as a 'default namespace'. The empty prefix always resolves to the empty namespace URI.

      Parameters:
        `namespace` - the namespace.

    - #### addNamespace

          public void addNamespace(java.lang.String prefix,
                                   java.lang.String uri)

      Adds a namespace definition (prefix and URI) to the list of namespaces known of this XPath expression.

      Note: In XPath, there is no such thing as a 'default namespace'. The empty prefix always resolves to the empty namespace URI.

      Parameters:
        `prefix` - the namespace prefix.
        `uri` - the namespace URI.
      Throws:
        `IllegalNameException` - if the prefix or uri are null or empty strings or if they contain illegal characters.

    - #### getXPath

          public abstract java.lang.String getXPath()

      Returns the wrapped XPath expression as a string.
      Returns:
        the wrapped XPath expression as a string.

    - #### selectNodes

          public static java.util.List selectNodes(java.lang.Object context,
                                                   java.lang.String path)
                                            throws JDOMException

      Evaluates an XPath expression and returns the list of selected items.

      Note: This method should not be used when the same XPath expression needs to be applied several times (on the same or different contexts) as it requires the expression to be compiled before being evaluated. In such cases, `allocating` an XPath wrapper instance and `evaluating` it several times is way more efficient.

      Parameters:
        `context` - the node to use as context for evaluating the XPath expression.
        `path` - the XPath expression to evaluate.
      Returns:
        the list of selected items, which may be of types: `Element`, `Attribute`, `Text`, `CDATA`, `Comment`, `ProcessingInstruction`, Boolean, Double, or String.
      Throws:
        `JDOMException` - if the XPath expression is invalid or its evaluation on the specified context failed.

    - #### selectSingleNode

          public static java.lang.Object selectSingleNode(java.lang.Object context,
                                                          java.lang.String path)
                                                   throws JDOMException

      Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).

      Note: This method should not be used when the same XPath expression needs to be applied several times (on the same or different contexts) as it requires the expression to be compiled before being evaluated. In such cases, `allocating` an XPath wrapper instance and `evaluating` it several times is way more efficient.

      Parameters:
        `context` - the element to use as context for evaluating the XPath expression.
        `path` - the XPath expression to evaluate.
      Returns:
        the first selected item, which may be of types: `Element`, `Attribute`, `Text`, `CDATA`, `Comment`, `ProcessingInstruction`, Boolean, Double, String, or `null` if no item was selected.
      Throws:
        `JDOMException` - if the XPath expression is invalid or its evaluation on the specified context failed.

    - #### writeReplace

          protected final java.lang.Object writeReplace()
                                                 throws java.io.ObjectStreamException

      [Serialization support] Returns the alternative object to write to the stream when serializing this object. This method returns an instance of a dedicated nested class to serialize XPath expressions independently of the concrete implementation being used.

      Note: Subclasses are not allowed to override this method to ensure valid serialization of all implementations.

      Returns:
        an XPathString instance configured with the wrapped XPath expression.
      Throws:
        `java.io.ObjectStreamException` - never.

Copyright ? 2007 Jason Hunter, Brett McLaughlin. All Rights Reserved.