APIdia Launch Partner
Top Description Fields Constructors Methods
com.sun.org.apache.xpath.internal

public Class CachedXPathAPI

extends Object
Class Inheritance
Imports
javax.xml.transform.TransformerException, com.sun.org.apache.xml.internal.utils.PrefixResolver, .PrefixResolverDefault, com.sun.org.apache.xpath.internal.objects.XObject, jdk.xml.internal.JdkConstants, org.w3c.dom.Document, .Node, .NodeList, org.w3c.dom.traversal.NodeIterator
The methods in this class are convenience methods into the low-level XPath API. These functions tend to be a little slow, since a number of objects must be created for each evaluation. A faster way is to precompile the XPaths using the low-level API, and then just use the XPaths over and over. This is an alternative for the old XPathAPI class, which provided static methods for the purpose but had the drawback of instantiating a new XPathContext (and thus building a new DTMManager, and new DTMs) each time it was called. XPathAPIObject instead retains its context as long as the object persists, reusing the DTMs. This does have a downside: if you've changed your source document, you should obtain a new XPathAPIObject to continue searching it, since trying to use the old DTMs will probably yield bad results or malfunction outright... and the cached DTMs may consume memory until this object and its context are returned to the heap. Essentially, it's the caller's responsibility to decide when to discard the cache.
See Also
XPath Specification

Field Summary

Modifier and TypeField and Description
protected XPathContext
xpathSupport

XPathContext, and thus the document model system (DTMs), persists through multiple calls to this object.

Constructor Summary

AccessConstructor and Description
public
CachedXPathAPI()

Default constructor.

public
CachedXPathAPI(CachedXPathAPI priorXPathAPI)

This constructor shares its XPathContext with a pre-existing CachedXPathAPI.

Method Summary

Modifier and TypeMethod and Description
public XObject

Returns:

An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.
eval(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str)

Evaluate XPath string to an XObject.

public XObject

Returns:

An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.
eval(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str, Node
The node from which prefixes in the XPath will be resolved to namespaces.
namespaceNode)

Evaluate XPath string to an XObject.

public XObject

Returns:

An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.
eval(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str, PrefixResolver
Will be called if the parser encounters namespace prefixes, to resolve the prefixes to URLs.
prefixResolver)

Evaluate XPath string to an XObject.

public XPathContext
getXPathContext()

Returns the XPathSupport object used in this CachedXPathAPI %REVIEW% I'm somewhat concerned about the loss of encapsulation this causes, but the xml-security folks say they need it.

public NodeIterator

Returns:

A NodeIterator, should never be null.
selectNodeIterator(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str)

Use an XPath string to select a nodelist.

public NodeIterator

Returns:

A NodeIterator, should never be null.
selectNodeIterator(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str, Node
The node from which prefixes in the XPath will be resolved to namespaces.
namespaceNode)

Use an XPath string to select a nodelist.

public NodeList

Returns:

A NodeIterator, should never be null.
selectNodeList(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str)

Use an XPath string to select a nodelist.

public NodeList

Returns:

A NodeIterator, should never be null.
selectNodeList(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str, Node
The node from which prefixes in the XPath will be resolved to namespaces.
namespaceNode)

Use an XPath string to select a nodelist.

public Node

Returns:

The first node found that matches the XPath, or null.
selectSingleNode(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str)

Use an XPath string to select a single node.

public Node

Returns:

The first node found that matches the XPath, or null.
selectSingleNode(Node
The node to start searching from.
contextNode, String
A valid XPath string.
str, Node
The node from which prefixes in the XPath will be resolved to namespaces.
namespaceNode)

Use an XPath string to select a single node.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

xpathSupportback to summary
protected XPathContext xpathSupport

XPathContext, and thus the document model system (DTMs), persists through multiple calls to this object. This is set in the constructor.

Constructor Detail

CachedXPathAPIback to summary
public CachedXPathAPI()

Default constructor. Establishes its own XPathContext, and hence its own com.sun.org.apache.xml.internal.dtm.DTMManager. Good choice for simple uses.

Note that any particular instance of CachedXPathAPI must not be operated upon by multiple threads without synchronization; we do not currently support multithreaded access to a single com.sun.org.apache.xml.internal.dtm.DTM.

CachedXPathAPIback to summary
public CachedXPathAPI(CachedXPathAPI priorXPathAPI)

This constructor shares its XPathContext with a pre-existing CachedXPathAPI. That allows sharing document models (com.sun.org.apache.xml.internal.dtm.DTM) and previously established location state.

Note that the original CachedXPathAPI and the new one should not be operated upon concurrently; we do not support multithreaded access to a single com.sun.org.apache.xml.internal.dtm.DTM at this time. Similarly, any particular instance of CachedXPathAPI must not be operated upon by multiple threads without synchronization.

%REVIEW% Should this instead do a clone-and-reset on the XPathSupport object?

Method Detail

evalback to summary
public XObject eval(Node contextNode, String str) throws TransformerException

Evaluate XPath string to an XObject. Using this method, XPath namespace prefixes will be resolved from the namespaceNode.

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

Returns:XObject

An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.

See Also
com.sun.org.apache.xpath.internal.objects.XObject, com.sun.org.apache.xpath.internal.objects.XNull, com.sun.org.apache.xpath.internal.objects.XBoolean, com.sun.org.apache.xpath.internal.objects.XNumber, com.sun.org.apache.xpath.internal.objects.XString, com.sun.org.apache.xpath.internal.objects.XRTreeFrag
evalback to summary
public XObject eval(Node contextNode, String str, Node namespaceNode) throws TransformerException

Evaluate XPath string to an XObject. XPath namespace prefixes are resolved from the namespaceNode. The implementation of this is a little slow, since it creates a number of objects each time it is called. This could be optimized to keep the same objects around, but then thread-safety issues would arise.

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

namespaceNode:Node

The node from which prefixes in the XPath will be resolved to namespaces.

Returns:XObject

An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.

See Also
com.sun.org.apache.xpath.internal.objects.XObject, com.sun.org.apache.xpath.internal.objects.XNull, com.sun.org.apache.xpath.internal.objects.XBoolean, com.sun.org.apache.xpath.internal.objects.XNumber, com.sun.org.apache.xpath.internal.objects.XString, com.sun.org.apache.xpath.internal.objects.XRTreeFrag
evalback to summary
public XObject eval(Node contextNode, String str, PrefixResolver prefixResolver) throws TransformerException

Evaluate XPath string to an XObject. XPath namespace prefixes are resolved from the namespaceNode. The implementation of this is a little slow, since it creates a number of objects each time it is called. This could be optimized to keep the same objects around, but then thread-safety issues would arise.

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

prefixResolver:PrefixResolver

Will be called if the parser encounters namespace prefixes, to resolve the prefixes to URLs.

Returns:XObject

An XObject, which can be used to obtain a string, number, nodelist, etc, should never be null.

See Also
com.sun.org.apache.xpath.internal.objects.XObject, com.sun.org.apache.xpath.internal.objects.XNull, com.sun.org.apache.xpath.internal.objects.XBoolean, com.sun.org.apache.xpath.internal.objects.XNumber, com.sun.org.apache.xpath.internal.objects.XString, com.sun.org.apache.xpath.internal.objects.XRTreeFrag
getXPathContextback to summary
public XPathContext getXPathContext()

Returns the XPathSupport object used in this CachedXPathAPI %REVIEW% I'm somewhat concerned about the loss of encapsulation this causes, but the xml-security folks say they need it.

selectNodeIteratorback to summary
public NodeIterator selectNodeIterator(Node contextNode, String str) throws TransformerException

Use an XPath string to select a nodelist. XPath namespace prefixes are resolved from the contextNode.

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

Returns:NodeIterator

A NodeIterator, should never be null.

selectNodeIteratorback to summary
public NodeIterator selectNodeIterator(Node contextNode, String str, Node namespaceNode) throws TransformerException

Use an XPath string to select a nodelist. XPath namespace prefixes are resolved from the namespaceNode.

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

namespaceNode:Node

The node from which prefixes in the XPath will be resolved to namespaces.

Returns:NodeIterator

A NodeIterator, should never be null.

selectNodeListback to summary
public NodeList selectNodeList(Node contextNode, String str) throws TransformerException

Use an XPath string to select a nodelist. XPath namespace prefixes are resolved from the contextNode.

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

Returns:NodeList

A NodeIterator, should never be null.

selectNodeListback to summary
public NodeList selectNodeList(Node contextNode, String str, Node namespaceNode) throws TransformerException

Use an XPath string to select a nodelist. XPath namespace prefixes are resolved from the namespaceNode.

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

namespaceNode:Node

The node from which prefixes in the XPath will be resolved to namespaces.

Returns:NodeList

A NodeIterator, should never be null.

selectSingleNodeback to summary
public Node selectSingleNode(Node contextNode, String str) throws TransformerException

Use an XPath string to select a single node. XPath namespace prefixes are resolved from the context node, which may not be what you want (see the next method).

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

Returns:Node

The first node found that matches the XPath, or null.

selectSingleNodeback to summary
public Node selectSingleNode(Node contextNode, String str, Node namespaceNode) throws TransformerException

Use an XPath string to select a single node. XPath namespace prefixes are resolved from the namespaceNode.

Parameters
contextNode:Node

The node to start searching from.

str:String

A valid XPath string.

namespaceNode:Node

The node from which prefixes in the XPath will be resolved to namespaces.

Returns:Node

The first node found that matches the XPath, or null.