Package net.sf.saxon.xpath

## Class XPathExpressionImpl

- java.lang.Object
- - net.sf.saxon.xpath.XPathExpressionImpl

- All Implemented Interfaces:
    `javax.xml.xpath.XPathExpression`

      public class XPathExpressionImpl
      extends java.lang.Object
      implements javax.xml.xpath.XPathExpression

  The JAXP XPathExpression interface represents a compiled XPath expression that can be repeatedly evaluated. This class is Saxon's implementation of that interface.

  The class also includes some methods retained from Saxon's original XPath API. When these methods are used, the object contains the context node and other state, so it is not thread-safe.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `XPathExpressionImpl​(Expression exp, Executable exec)` | The constructor is protected, to ensure that instances can only be created using the compile() method of XPathEvaluator

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `evaluate​(java.lang.Object node)` | Evaluate the expression to return a string value
    `java.lang.Object` | `evaluate​(java.lang.Object node, javax.xml.namespace.QName qName)` | JAXP 1.3 evaluate() method
    `java.lang.String` | `evaluate​(org.xml.sax.InputSource inputSource)` | Evaluate the XPath expression against an input source to obtain a string result.
    `java.lang.Object` | `evaluate​(org.xml.sax.InputSource inputSource, javax.xml.namespace.QName qName)` | Evaluate the XPath expression against an input source to obtain a result of a specified type
    `Configuration` | `getConfiguration()` | Get the Configuration under which this XPath expression was compiled
    `Expression` | `getInternalExpression()` | Low-level method to get the internal Saxon expression object.
    `SlotManager` | `getStackFrameMap()` | Get the stack frame map.
    `protected void` | `setStackFrameMap​(SlotManager map)` | Define the number of slots needed for local variables within the expression.

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

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

    - ### Methods inherited from interface javax.xml.xpath.XPathExpression

      `evaluateExpression, evaluateExpression, evaluateExpression, evaluateExpression`

- - ### Constructor Detail

    - #### XPathExpressionImpl

          protected XPathExpressionImpl​(Expression exp,
                                        Executable exec)

      The constructor is protected, to ensure that instances can only be created using the compile() method of XPathEvaluator
      Parameters:
        `exp` - the compiled expression
        `exec` - the executable

  - ### Method Detail

    - #### setStackFrameMap

          protected void setStackFrameMap​(SlotManager map)

      Define the number of slots needed for local variables within the expression. This method is for internal use only.
      Parameters:
        `map` - description of the stack frame

    - #### getStackFrameMap

          public SlotManager getStackFrameMap()

      Get the stack frame map. This holds information about the allocation of slots to variables. This is needed by applications using low-level interfaces for evaluating the expression
      Returns:
        a description of the stack frame

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Configuration under which this XPath expression was compiled
      Returns:
        the Saxon configuration

    - #### evaluate

          public java.lang.Object evaluate​(java.lang.Object node,
                                           javax.xml.namespace.QName qName)
                                    throws javax.xml.xpath.XPathExpressionException

      JAXP 1.3 evaluate() method
      Specified by:
        `evaluate` in interface `javax.xml.xpath.XPathExpression`
      Parameters:
        `node` - The context node. This must use a representation of nodes that this implementation understands. This may be a Saxon NodeInfo, or a node in one of the external object models supported, for example DOM, DOM4J, JDOM, or XOM, provided the support module for that object model is loaded.

        An instance of `TreeInfo` is also accepted.

        Contrary to the interface specification, Saxon does not supply an empty document when the value is null. This is because XPath 2.0 allows the context item to be "absent" (null). So Saxon executes the XPath expression with the context item undefined.

        `qName` - Indicates the type of result required. This must be one of the constants defined in the JAXP `XPathConstants` class. Saxon will attempt to convert the actual result of the expression to the required type using the XPath 1.0 conversion rules.
      Returns:
        the result of the evaluation, as a Java object of the appropriate type. Saxon interprets the rules as follows:

        Return value types
        QName | Return Value
        BOOLEAN | The effective boolean value of the actual result, as a Java Boolean object
        STRING | The result of applying the string() function to the actual result, as a Java String object
        NUMBER | The result of applying the number() function to the actual result, as a Java Double object
        NODE | A single node, in the native data model supplied as input. If the expression returns more than one node, the first is returned. If the expression returns an empty sequence, null is returned. If the expression returns an atomic value, or if the first item in the result sequence is an atomic value, an exception is thrown.
        NODESET | This is interpreted as allowing any sequence, of nodes or atomic values. If the first argument is a wrapper around a DOM Node, then the result is returned as a DOM NodeList, and an exception is then thrown if the result sequence contains a value that is not a DOM Node. In all other cases the result is returned as a Java List object, unless it is empty, in which case null is returned. The contents of the list may be node objects (in the native data model supplied as input), or Java objects representing the XPath atomic values in the actual result: String for an xs:string, Double for a xs:double, Long for an xs:integer, and so on. (For safety, cast the values to a type such as xs:string within the XPath expression).

      Throws:
        `javax.xml.xpath.XPathExpressionException` - if evaluation of the expression fails or if the result cannot be converted to the requested type.

    - #### evaluate

          public java.lang.String evaluate​(java.lang.Object node)
                                    throws javax.xml.xpath.XPathExpressionException

      Evaluate the expression to return a string value
      Specified by:
        `evaluate` in interface `javax.xml.xpath.XPathExpression`
      Parameters:
        `node` - the initial context node. This must be either an instance of NodeInfo or a node recognized by a known external object model.

        Contrary to the interface specification, Saxon does not supply an empty document when the value is null. This is because XPath 2.0 allows the context item to be "absent" (null). So Saxon executes the XPath expression with the context item undefined.

      Returns:
        the results of the expression, converted to a String
      Throws:
        `javax.xml.xpath.XPathExpressionException` - if evaluation fails

    - #### evaluate

          public java.lang.Object evaluate​(org.xml.sax.InputSource inputSource,
                                           javax.xml.namespace.QName qName)
                                    throws javax.xml.xpath.XPathExpressionException

      Evaluate the XPath expression against an input source to obtain a result of a specified type
      Specified by:
        `evaluate` in interface `javax.xml.xpath.XPathExpression`
      Parameters:
        `inputSource` - The input source document against which the expression is evaluated.

        If any error occurs reading or parsing this document, the error is notified to the `ErrorListener` registered with the `Configuration`, and also causes an exception to be thrown.

        (Note that there is no caching. This will be parsed, and the parsed result will be discarded.)

        If the supplied value is null then (contrary to the JAXP specifications), the XPath expression is evaluated with the context item undefined.

        `qName` - The type required, identified by a constant in `XPathConstants`
      Returns:
        the result of the evaluation, as a Java object of the appropriate type: see `evaluate(Object, javax.xml.namespace.QName)`
      Throws:
        `javax.xml.xpath.XPathExpressionException`

    - #### evaluate

          public java.lang.String evaluate​(org.xml.sax.InputSource inputSource)
                                    throws javax.xml.xpath.XPathExpressionException

      Evaluate the XPath expression against an input source to obtain a string result.
      Specified by:
        `evaluate` in interface `javax.xml.xpath.XPathExpression`
      Parameters:
        `inputSource` - The input source document against which the expression is evaluated.

        If any error occurs reading or parsing this document, the error is notified to the `ErrorListener` registered with the `Configuration`, and also causes an exception to be thrown.

        (Note that there is no caching. This will be parsed, and the parsed result will be discarded.)

        If the supplied value is null then (contrary to the JAXP specifications), the XPath expression is evaluated with the context item undefined.

      Returns:
        the result of the evaluation, converted to a String
      Throws:
        `javax.xml.xpath.XPathExpressionException` - in the event of an XPath dynamic error
        `java.lang.NullPointerException` - If `inputSource` is `null`.

    - #### getInternalExpression

          public Expression getInternalExpression()

      Low-level method to get the internal Saxon expression object. This exposes a wide range of internal methods that may be needed by specialized applications, and allows greater control over the dynamic context for evaluating the expression.
      Returns:
        the underlying Saxon expression object.