net.sf.saxon.xpath
Class XPathEvaluator

java.lang.Object
  extended bynet.sf.saxon.xpath.XPathEvaluator

public class XPathEvaluator
extends Object

XPathEvaluator provides a simple API for standalone XPath processing (that is, executing XPath expressions in the absence of an XSLT stylesheet). It is loosely modelled on the proposed org.w3c.dom.xpath.XPathEvaluator interface, though it does not actually implement this interface at present.

Author:
Michael H. Kay (michael.h.kay@ntlworld.com)

Constructor Summary
XPathEvaluator()
          Default constructor.
XPathEvaluator(Source source)
          Construct an XPathEvaluator to process a particular source document.
 
Method Summary
static Object convert(Item item)
          Internal method to convert an XPath value to a Java object.
 XPathExpression createExpression(String expression)
          Prepare an XPath expression for subsequent evaluation.
 List evaluate(String expression)
          Prepare and execute an XPath expression, supplied as a string, and returning the results as a List.
 Object evaluateSingle(String expression)
          Prepare and execute an XPath expression, supplied as a string, and returning the first item in the result.
 StaticContext getStaticContext()
          Get the current static context
static void main(String[] args)
          A simple command-line interface for the XPathEvaluator (not documented).
 void setContextNode(NodeInfo node)
          Set the context node.
 NodeInfo setSource(Source source)
          Supply the document against which XPath expressions are to be executed.
 void setStaticContext(StaticContext context)
          Set the static context for compiling XPath expressions.
 void setStripSpace(boolean strip)
          Indicate whether all whitespace text nodes in the source document are to be removed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XPathEvaluator

public XPathEvaluator()
Default constructor. If this constructor is used, a source document must be subsequently supplied using the setSource() method.


XPathEvaluator

public XPathEvaluator(Source source)
               throws XPathException
Construct an XPathEvaluator to process a particular source document. This is equivalent to using the default constructor and immediately calling setSource().

Parameters:
source - The source document (or a specific node within it).
Method Detail

setStripSpace

public void setStripSpace(boolean strip)
Indicate whether all whitespace text nodes in the source document are to be removed. This option has no effect unless it is called before the call on setSource(), and unless the Source supplied to setSource() is a SAXSource or StreamSource.

Parameters:
strip - True if all whitespace text nodes are to be stripped from the source document, false otherwise. The default if the method is not called is false.

setSource

public NodeInfo setSource(Source source)
                   throws XPathException
Supply the document against which XPath expressions are to be executed. This method must be called before preparing or executing an XPath expression. It is possible to supply a different document subsequently; however, prepared XPath expressions are always executed against the document that was current at the time they were prepared. Setting a new source document clears all the namespaces that have been declared.

Parameters:
source - Any javax.xml.transform.Source object representing the document against which XPath expressions will be executed. Note that a Saxon DocumentInfo (indeed any NodeInfo) can be used as a Source. To use a third-party DOM Document as a source, create an instance of javax.xml.transform.dom.DOMSource to wrap it. Note that this method copies the supplied DOM to a TinyTree; if you want instead to wrap the DOM in a NodeInfo layer, use setSource(new DocumentWrapper(dom)). The Source object supplied also determines the initial setting of the context item. In most cases the context node will be the root of the supplied document; however, if a NodeInfo or DOMSource is supplied it can be any node in the document.
Returns:
the NodeInfo of the start node in the resulting document object.
Throws:
XPathException

setStaticContext

public void setStaticContext(StaticContext context)
Set the static context for compiling XPath expressions. This provides control over the environment in which the expression is compiled, for example it allows namespace prefixes to be declared, variables to be bound and functions to be defined. For most purposes, the static context can be defined by providing and tailoring an instance of the StandaloneContext class. Until this method is called, a default static context is used, in which no namespaces are defined other than the standard ones (xml, xslt, and saxon), and no variables or functions (other than the core XPath functions) are available.


getStaticContext

public StaticContext getStaticContext()
Get the current static context


createExpression

public XPathExpression createExpression(String expression)
                                 throws XPathException
Prepare an XPath expression for subsequent evaluation. The prepared expression can only be used with the document that has been established using setSource() at the time this method is called.

Parameters:
expression - The XPath expression to be evaluated, supplied as a string.
Returns:
an XPathExpression object representing the prepared expression
Throws:
XPathException - if the syntax of the expression is wrong, or if it references namespaces, variables, or functions that have not been declared.

setContextNode

public void setContextNode(NodeInfo node)
Set the context node. This provides the context node for any expressions executed after this method is called, including expressions that were prepared before it was called.

Parameters:
node - The node to be used as the context node. This must be a node within the context document (the document supplied using the setSource() method).
Throws:
NullPointerException - if the argument is null
IllegalArgumentException - if the supplied node is not a node in the context document

evaluate

public List evaluate(String expression)
              throws XPathException
Prepare and execute an XPath expression, supplied as a string, and returning the results as a List.

Parameters:
expression - The XPath expression to be evaluated, supplied as a string.
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 object representing a node, or a Java object representing an atomic value. The types of Java object that may be included in the list, and the XML Schema data types that they correspond to, are as follows:

  • Boolean (xsd:boolean)
  • String (xsd:string)
  • BigDecimal (xsd:decimal)
  • Long (xsd:integer and its derived types)
  • Double (xsd:double)
  • Float (xsd:float)
  • Date (xsd:dateTime)
Throws:
XPathException

convert

public static Object convert(Item item)
                      throws XPathException
Internal method to convert an XPath value to a Java object. An atomic value is returned as an instance of the best available Java class. If the item is a node, the node is "unwrapped", to return the underlying node in the original model (which might be, for example, a DOM or JDOM node).

Throws:
XPathException

evaluateSingle

public Object evaluateSingle(String expression)
                      throws XPathException
Prepare and execute an XPath expression, supplied as a string, and 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).

Parameters:
expression - The XPath expression to be evaluated, supplied as a string.
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

main

public static void main(String[] args)
                 throws Exception
A simple command-line interface for the XPathEvaluator (not documented). First parameter is the filename containing the source document, second parameter is the XPath expression.

Throws:
Exception