org.jdom2.xpath
Class XPathBuilder<T>

java.lang.Object
  org.jdom2.xpath.XPathBuilder<T>

Type Parameters:

T - The generic type of the returned results.

public class XPathBuilder<T>
extends java.lang.Object

A helper class for creating XPathExpression instances without having to manage your own Namespace and Variable contexts.

Author:

Rolf Lear

Constructor Summary

XPathBuilder(java.lang.String expression, Filter<T> filter)
Create a skeleton XPathBuilder with the given expression and result filter.

Method Summary

XPathExpression<T>	compileWith(XPathFactory factory) Compile an XPathCOmpiled using the details currently stored in the XPathBuilder.
java.lang.String	getExpression() Get the XPath expression.
Filter<T>	getFilter() Get the Filter instance used for coercion.
Namespace	getNamespace(java.lang.String prefix) Get the variable value associated with the given name.
java.lang.Object	getVariable(java.lang.String qname) Get the variable value associated with the given name.
boolean	setNamespace(Namespace namespace) Define a Namespace to be available for the XPath expression.
boolean	setNamespace(java.lang.String prefix, java.lang.String uri) Define a Namespace to be available for the XPath expression.
boolean	setNamespaces(java.util.Collection<Namespace> namespaces) Add a number of namespaces to this XPathBuilder
boolean	setVariable(java.lang.String qname, java.lang.Object value) Define or redefine an XPath expression variable value.

Methods inherited from class java.lang.Object

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

Constructor Detail

XPathBuilder

public XPathBuilder(java.lang.String expression,
                    Filter<T> filter)

Create a skeleton XPathBuilder with the given expression and result filter.

Parameters:

expression - The XPath expression.

filter - The Filter to perform the coercion with.

Method Detail

setVariable

public boolean setVariable(java.lang.String qname,
                           java.lang.Object value)

Define or redefine an XPath expression variable value. In XPath, variable names can be in a namespace, and thus the variable name is in a QName form: prefix:name

Variables without a prefix are in the "" Namespace.

Variables can have a null value. The XPathExpression can change the variable value before the expression is evaluated, and, some XPath libraries support a null variable value. See XPathExpression.setVariable(String, String, Object).

In order to validate that a Variable is unique you have to know the namespace associated with the prefix. This class is designed to make it possible to make the namespace associations after the variables have been added. As a result it is not possible to validate the uniqueness of a variable name until the compileWith(XPathFactory) method is called.

As a consequence of the above, this class assumes that each unique prefix is for a unique Namespace URI (thus calling this method with different QNames is assumed to be setting different variables). This may lead to an IllegalArgumentException when the compileWith(XPathFactory) method is called.

This method does not validate the format of the variable name either, it instead postpones the validation until the expression is compiled. As a result you may encounter IllegalArgumentExceptions at compile time if the variable names are not valid XPath QNames ("name" or "prefix:name").

Parameters:

qname - The variable name to define.

value - The variable value to set.

Returns:

true if this variable was defined, false if it was previously defined and has now been redefined.

Throws:

java.lang.NullPointerException - if the name is null.

setNamespace

public boolean setNamespace(java.lang.String prefix,
                            java.lang.String uri)

Define a Namespace to be available for the XPath expression. If a Namespace with the same prefix was previously defined then the prefix will be re-defined.

Parameters:

prefix - The namespace prefix to define.

uri - The namespace URI to define.

Returns:

true if the Namespace prefix was newly defined, false if the prefix was previously defined and has now been redefined.

setNamespace

public boolean setNamespace(Namespace namespace)

Define a Namespace to be available for the XPath expression.

Parameters:

namespace - The namespace to define.

Returns:

true if this Namespace prefix was newly defined, false if the prefix was previously defined and has now been redefined.

Throws:

java.lang.NullPointerException - if the namespace is null.

setNamespaces

public boolean setNamespaces(java.util.Collection<Namespace> namespaces)

Add a number of namespaces to this XPathBuilder

Parameters:

namespaces - The namespaces to set.

Returns:

true if any of the Namespace prefixes are new to the XPathBuilder

Throws:

java.lang.NullPointerException - if the namespace collection, or any of its members are null.

getVariable

public java.lang.Object getVariable(java.lang.String qname)

Get the variable value associated with the given name. See setVariable(String, Object) for notes on how the Namespaces need to be established before an authoritative reference to a variable can be made. As a result, this method uses the simple variable QName name to reference the variable.

Parameters:

qname - The variable name to get the vaiable value for.

Returns:

the variable value, or null if the variable was not defined.

Throws:

java.lang.NullPointerException - if the qname is null.

getNamespace

public Namespace getNamespace(java.lang.String prefix)

Get the variable value associated with the given name.

Parameters:

prefix - The Namespace prefix to get the Namespace for.

Returns:

the Namespace with that prefix, or null if that prefix was never defined.

getFilter

public Filter<T> getFilter()

Get the Filter instance used for coercion.

Returns:

the coercion Filter.

getExpression

public java.lang.String getExpression()

Get the XPath expression.

Returns:

the XPath expression.

compileWith

public XPathExpression<T> compileWith(XPathFactory factory)

Compile an XPathCOmpiled using the details currently stored in the XPathBuilder.

Parameters:

factory - The XPath factory to use for compiling.

Returns:

The compiled XPath expression

Throws:

java.lang.IllegalArgumentException - if the expression cannot be compiled.