net.sf.practicalxml.xpath

Class XPathWrapper

java.lang.Object

net.sf.practicalxml.xpath.XPathWrapper

All Implemented Interfaces:

Cloneable

public class XPathWrapper
extends Object
implements Cloneable

This class simplifies the use of XPath expressions, hiding the factory and return types, and providing a simple builder-style interface for adding resolvers. It also maintains the expression in a compiled form, improving reuse performance.

Warning: XPathWrapper, like the underlying JDK XPath object, is not thread-safe. However, separate instances may be created and evaluated on separate threads without explicit synchronization. To make this work, we create a new XPathFactory instance for each wrapper (with the Sun JDK, this adds little overhead), synchronizing newInstance() on XPathWrapper.class.

Constructor Summary

Constructors

Constructor and Description
XPathWrapper(String expr) Creates a new instance, which may then be customized with various resolvers, and used to evaluate expressions.

Method Summary

Methods

Modifier and Type	Method and Description
XPathWrapper	bindDefaultNamespace(String nsURI) Deprecated. In practice, this method isn't particularly useful: if you're going to specify ":" on a term, you might as well specify a single-character prefix. It won't be removed, but a future implementation might parse an expression sans colons, and insert references.
XPathWrapper	bindFunction(FunctionResolver.SelfDescribingFunction func) Binds a self-describing function to this expression.
XPathWrapper	bindFunction(FunctionResolver.SelfDescribingFunction func, String prefix) Binds a self-describing function to this expression, along with the prefix used to access that function.
XPathWrapper	bindFunction(QName name, XPathFunction func) Binds a standard XPathFunction to this expression, handling any number of arguments.
XPathWrapper	bindFunction(QName name, XPathFunction func, int arity) Binds a standard XPathFunction to this expression, handling a specific number of arguments.
XPathWrapper	bindFunction(QName name, XPathFunction func, int minArity, int maxArity) Binds a standard XPathFunction to this expression, handling a specific range of arguments.
XPathWrapper	bindNamespace(String prefix, String nsURI) Adds a namespace binding to this expression.
XPathWrapper	bindVariable(QName name, Object value) Binds a value to a variable, replacing any previous value for that variable.
XPathWrapper	bindVariable(String name, Object value) Binds a value to a variable, replacing any previous value for that variable.
protected XPathWrapper	clone() Creates a shallow clone of this object, omitting the compiled XPath expression.
boolean	equals(Object obj) Two instances are considered equal if they have the same expression, namespace mappings, variable mappings, and function mappings.
List<Node>	evaluate(Node context) Applies this expression to the the specified node, converting the resulting NodeList into a java.util.List.
<T> List<T>	evaluate(Node context, Class<T> klass) Applies this expression to the the specified node, converting the resulting NodeList into a java.util.List containing only nodes of the specified type.
Boolean	evaluateAsBoolean(Node context) Applies this expression to the the specified node, requesting the BOOLEAN return type.
Element	evaluateAsElement(Node context) Applies this expression to the the specified node, and returning the first Element from the resulting nodelist.
Number	evaluateAsNumber(Node context) Applies this expression to the specified node, requesting the NUMBER return type.
String	evaluateAsString(Node context) Applies this expression to the specified node, requesting the STRING return type.
List<String>	evaluateAsStringList(Node context) Applies this expression to the specified node, requesting the NODESET return type, and then retrieving the text content for each returned node.
int	hashCode() Hash code is driven by the expression, ignoring differences between namespaces, variables, and functions.
XPathWrapper	setFunctionResolver(FunctionResolver resolver) Attaches a pre-build FunctionResolver to this wrapper, replacing the existing resolver (and removing all bound functions).
String	toString() The string value is the expression.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

XPathWrapper

public XPathWrapper(String expr)

Creates a new instance, which may then be customized with various resolvers, and used to evaluate expressions.

Method Detail

bindNamespace

public XPathWrapper bindNamespace(String prefix,
                         String nsURI)

Adds a namespace binding to this expression. All bindings must be added prior to the first call to evaluate(). If you add multiple bindings with the same namespace, only the last is retained.

Parameters:

prefix - The prefix used to reference this namespace in the XPath expression. Note that this does not need to be the same prefix used by the document.

nsURI - The namespace URI to associate with this prefix.

Returns:

The wrapper, so that calls may be chained.

bindDefaultNamespace

@Deprecated
public XPathWrapper bindDefaultNamespace(String nsURI)

Deprecated. In practice, this method isn't particularly useful: if you're going to specify ":" on a term, you might as well specify a single-character prefix. It won't be removed, but a future implementation might parse an expression sans colons, and insert references.

Sets the default namespace binding: this will be applied to all expressions that do not explicitly specify a prefix (although they must use the colon separating the non-existent prefix from the element name).

Parameters:

nsURI - The default namespace for this document.

Returns:

The wrapper, so that calls may be chained.

bindVariable

public XPathWrapper bindVariable(String name,
                        Object value)

Binds a value to a variable, replacing any previous value for that variable. Unlike other configuration methods, this may be called after calling evaluate(); the new values will be used for subsequent evaluations.

Parameters:

name - The name of the variable; this is turned into a QName without namespace.

value - The value of the variable; the XPath evaluator must be able to convert this value into a type usable in an XPath expression.

Returns:

The wrapper, so that calls may be chained.

bindVariable

public XPathWrapper bindVariable(QName name,
                        Object value)

Binds a value to a variable, replacing any previous value for that variable. Unlike other configuration methods, this may be called after calling evaluate(); the new values will be used for subsequent evaluations.

Parameters:

name - The fully-qualified name of the variable.

value - The value of the variable; the XPath evaluator must be able to convert this value into a type usable in an XPath expression.

Returns:

The wrapper, so that calls may be chained.

bindFunction

public XPathWrapper bindFunction(FunctionResolver.SelfDescribingFunction func)

Binds a self-describing function to this expression. Subsequent calls with the same name/arity will silently replace the binding.

Per the JDK documentation, user-defined functions must occupy their own namespace. You must bind a namespace for this function, and use the bound prefix to reference it in your expression. Alternatively, you can call the variant of bindFunction() that binds a prefix to the function's namespace.

Parameters:

func - The function.

Returns:

The wrapper, so that calls may be chained.

bindFunction

public XPathWrapper bindFunction(FunctionResolver.SelfDescribingFunction func,
                        String prefix)

Binds a self-describing function to this expression, along with the prefix used to access that function. This also establishes a namespace binding for that prefix.

Per the JDK documentation, user-defined functions must occupy their own namespace. This method will retrieve the namespace from the function, and bind it to the passed prefix.

Parameters:

func - The function.

prefix - The prefix to bind to this function's namespace.

Returns:

The wrapper, so that calls may be chained.

bindFunction

public XPathWrapper bindFunction(QName name,
                        XPathFunction func)

Binds a standard XPathFunction to this expression, handling any number of arguments. Subsequent calls to this method with the same name will silently replace the binding.

Per the JDK documentation, user-defined functions must occupy their own namespace. If the qualified name that you pass to this method includes a prefix, the associated namespace will be bound to that prefix. If not, you must bind the namespace explicitly. In either case, you must refer to the function in your expression using a bound prefix.

Parameters:

name - The qualified name for this function. Must contain a name and namespace, may contain a prefix.

func - The function to bind to this name.

Returns:

The wrapper, so that calls may be chained.

bindFunction

public XPathWrapper bindFunction(QName name,
                        XPathFunction func,
                        int arity)

Binds a standard XPathFunction to this expression, handling a specific number of arguments. Subsequent calls to this method with the same name and arity will silently replace the binding.

Per the JDK documentation, user-defined functions must occupy their own namespace. If the qualified name that you pass to this method includes a prefix, the associated namespace will be bound to that prefix. If not, you must bind the namespace explicitly. In either case, you must refer to the function in your expression using a bound prefix.

Parameters:

name - The qualified name for this function. Must contain a name and namespace, may contain a prefix.

func - The function to bind to this name.

arity - The number of arguments accepted by this function.

Returns:

The wrapper, so that calls may be chained.

bindFunction

public XPathWrapper bindFunction(QName name,
                        XPathFunction func,
                        int minArity,
                        int maxArity)

Binds a standard XPathFunction to this expression, handling a specific range of arguments. Subsequent calls to this method with the same name and range of arguments will silently replace the binding.

Per the JDK documentation, user-defined functions must occupy their own namespace. If the qualified name that you pass to this method includes a prefix, the associated namespace will be bound to that prefix. If not, you must bind the namespace explicitly. In either case, you must refer to the function in your expression using a bound prefix.

Parameters:

name - The qualified name for this function. Must contain a name and namespace, may contain a prefix.

func - The function to bind to this name.

minArity - The minimum number of arguments accepted by this function.

maxArity - The maximum number of arguments accepted by this function.

Returns:

The wrapper, so that calls may be chained.

setFunctionResolver

public XPathWrapper setFunctionResolver(FunctionResolver resolver)

Attaches a pre-build FunctionResolver to this wrapper, replacing the existing resolver (and removing all bound functions). This method is intended for use by XPathWrapperFactory, but is exposed for applications that wish to manage their own XPaths.

Since:

1.1.12

evaluate

public List<Node> evaluate(Node context)

Applies this expression to the the specified node, converting the resulting NodeList into a java.util.List.

evaluate

public <T> List<T> evaluate(Node context,
                   Class<T> klass)

Applies this expression to the the specified node, converting the resulting NodeList into a java.util.List containing only nodes of the specified type.

evaluateAsElement

public Element evaluateAsElement(Node context)

Applies this expression to the the specified node, and returning the first Element from the resulting nodelist. Returns null if there is no element in the list.

Since:

1.1.11

evaluateAsString

public String evaluateAsString(Node context)

Applies this expression to the specified node, requesting the STRING return type.

evaluateAsStringList

public List<String> evaluateAsStringList(Node context)

Applies this expression to the specified node, requesting the NODESET return type, and then retrieving the text content for each returned node.

Note: this method calls Node.getTextContent() in keeping with normal XPath behavior. If you want to get only the immediate child text nodes, evaluate as a list of elements and use DomUtil.getText().

Since:

1.1.3

evaluateAsNumber

public Number evaluateAsNumber(Node context)

Applies this expression to the specified node, requesting the NUMBER return type.

evaluateAsBoolean

public Boolean evaluateAsBoolean(Node context)

Applies this expression to the the specified node, requesting the BOOLEAN return type.

equals

public final boolean equals(Object obj)

Two instances are considered equal if they have the same expression, namespace mappings, variable mappings, and function mappings. Note that instances with function mappings are all but guaranteed to be not-equal, unless you override the equals() method on the function implementation class.

Overrides:

equals in class Object

hashCode

public int hashCode()

Hash code is driven by the expression, ignoring differences between namespaces, variables, and functions.

Overrides:

hashCode in class Object

toString

public String toString()

The string value is the expression.

Overrides:

toString in class Object

clone

protected XPathWrapper clone()
                      throws CloneNotSupportedException

Creates a shallow clone of this object, omitting the compiled XPath expression. This method exists to support thread-local instances, which will recompile the expression.

Overrides:

clone in class Object

Throws:

CloneNotSupportedException