## 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
`protected` `XPathExpressionImpl(Expression exp, Configuration config)` The constructor is protected, to ensure that instances can only be created using the createExpression() method of XPathEvaluator

Method Summary
`java.util.List` `evaluate()` Execute a prepared XPath expression, returning the results as a List.
`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
`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.Object` `evaluateSingle()` Execute a prepared XPath expression, returning the first item in the result.
`Expression` `getInternalExpression()` Low-level method to get the internal Saxon expression object.
`SequenceIterator` `rawIterator()` Get a raw iterator over the results of the expression.
`void` `setContextNode(NodeInfo node)` Set the context node for evaluating the expression.
`void` `setSortKey(XPathExpressionImpl sortKey)` Define the sort order for the results of the expression.
`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`

Constructor Detail

### XPathExpressionImpl

    protected XPathExpressionImpl(Expression exp,
                                  Configuration config)

  The constructor is protected, to ensure that instances can only be created using the createExpression() method of XPathEvaluator

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.

### setSortKey

    public void setSortKey(XPathExpressionImpl sortKey)

  Define the sort order for the results of the expression. If this method is called, then the list returned by a subsequent call on the evaluate() method will first be sorted.

  Parameters:
    `sortKey` - an XPathExpression, which will be applied to each item in the sequence; the result of this expression determines the ordering of the list returned by the evaluate() method. The sortKey can be null, to clear a previous sort key.

### setContextNode

    public void setContextNode(NodeInfo node)

  Set the context node for evaluating the expression. If this method is not called, the context node will be the root of the document to which the prepared expression is bound.

### evaluate

    public java.util.List evaluate()
                            throws XPathException

  Execute a prepared XPath expression, returning the results as a List. The context node must have been set previously using `setContextNode(net.sf.saxon.om.NodeInfo)`.

  Returns:
    The results of the expression, as a List. The List represents the sequence of items returned by the expression. Each item in the list will either be an instance of net.sf.saxon.om.NodeInfo, representing a node, or a Java object representing an atomic value. For the types of Java object that may be returned, see `evaluate(Object, javax.xml.namespace.QName)` with the second argument set to NODESET.
  Throws:
    `XPathException`

### evaluateSingle

    public java.lang.Object evaluateSingle()
                                    throws XPathException

  Execute a prepared XPath expression, returning the first item in the result. This is useful where it is known that the expression will only return a singleton value (for example, a single node, or a boolean). The context node must be set previously using `setContextNode(net.sf.saxon.om.NodeInfo)`.

  Returns:
    The first item in the sequence returned by the expression. If the expression returns an empty sequence, this method returns null. Otherwise, it returns the first item in the result sequence, represented as a Java object using the same mapping as for the evaluate() method
  Throws:
    `XPathException`

### rawIterator

    public SequenceIterator rawIterator()
                                 throws XPathException

  Get a raw iterator over the results of the expression. This returns results without any conversion of the returned items to "native" Java classes. This method is intended for use by applications that need to process the results of the expression using internal Saxon interfaces.

  Throws:
    `XPathException`

### 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, JDOM, or XOM, provided the support module for that object model is loaded.
    `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:

    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. 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). Note that the result is never returned as a DOM NodeList.

  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 an instance of NodeInfo
  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. (Note that there is no caching. This will be parsed, and the parsed result will be discarded.)
    `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. (Note that there is no caching. This will be parsed, and the parsed result will be discarded.)
  Returns:
    the result of the evaluation, converted to a String
  Throws:
    `javax.xml.xpath.XPathExpressionException`

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