Top Description Fields Constructors Methods
org.jdom2.xpath

public Class XPathBuilder<T>

extends Object
Class Inheritance
Type Parameters
<T>
The generic type of the returned results.
Imports
java.util.Collection, .HashMap, .Map, org.jdom2.Namespace, org.jdom2.filter.Filter
A helper class for creating XPathExpression instances without having to manage your own Namespace and Variable contexts.
Author
Rolf Lear

Field Summary

Modifier and TypeField and Description
private final String
expression

private final Filter<T>
filter

private Map<String, Namespace>
namespaces

private Map<String, Object>
variables

Constructor Summary

AccessConstructor and Description
public
XPathBuilder(String
The XPath expression.
expression, Filter<T>
The Filter to perform the coercion with.
filter)

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

Method Summary

Modifier and TypeMethod and Description
public XPathExpression<T>

Returns:

The compiled XPath expression
compileWith(XPathFactory
The XPath factory to use for compiling.
factory)

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

public String

Returns:

the XPath expression.
getExpression()

Get the XPath expression.

public Filter<T>

Returns:

the coercion Filter.
getFilter()

Get the Filter instance used for coercion.

public Namespace

Returns:

the Namespace with that prefix, or null if that prefix was never defined.
getNamespace(String
The Namespace prefix to get the Namespace for.
prefix)

Get the Namespace associated with the given prefix.

public Object

Returns:

the variable value, or null if the variable was not defined.
getVariable(String
The variable name to get the variable value for.
qname)

Get the variable value associated with the given name.

public boolean

Returns:

true if the Namespace prefix was newly defined, false if the prefix was previously defined and has now been redefined.
setNamespace(String
The namespace prefix to define.
prefix, String
The namespace URI to define.
uri)

Define a Namespace to be available for the XPath expression.

public boolean

Returns:

true if this Namespace prefix was newly defined, false if the prefix was previously defined and has now been redefined.
setNamespace(Namespace
The namespace to define.
namespace)

Define a Namespace to be available for the XPath expression.

public boolean

Returns:

true if any of the Namespace prefixes are new to the XPathBuilder
setNamespaces(Collection<Namespace>
The namespaces to set.
namespaces)

Add a number of namespaces to this XPathBuilder

public boolean

Returns:

true if this variable was defined, false if it was previously defined and has now been redefined.
setVariable(String
The variable name to define.
qname, Object
The variable value to set.
value)

Define or redefine an XPath expression variable value.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

expressionback to summary
private final String expression
filterback to summary
private final Filter<T> filter
namespacesback to summary
private Map<String, Namespace> namespaces
variablesback to summary
private Map<String, Object> variables

Constructor Detail

XPathBuilderback to summary
public XPathBuilder(String expression, Filter<T> filter)

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

Parameters
expression:String

The XPath expression.

filter:Filter<T>

The Filter to perform the coercion with.

Method Detail

compileWithback to summary
public XPathExpression<T> compileWith(XPathFactory factory)

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

Parameters
factory:XPathFactory

The XPath factory to use for compiling.

Returns:XPathExpression<T>

The compiled XPath expression

Exceptions
IllegalArgumentException:
if the expression cannot be compiled.
getExpressionback to summary
public String getExpression()

Get the XPath expression.

Returns:String

the XPath expression.

getFilterback to summary
public Filter<T> getFilter()

Get the Filter instance used for coercion.

Returns:Filter<T>

the coercion Filter.

getNamespaceback to summary
public Namespace getNamespace(String prefix)

Get the Namespace associated with the given prefix.

Parameters
prefix:String

The Namespace prefix to get the Namespace for.

Returns:Namespace

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

getVariableback to summary
public Object getVariable(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:String

The variable name to get the variable value for.

Returns:Object

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

Exceptions
NullPointerException:
if the qname is null.
setNamespaceback to summary
public boolean setNamespace(String prefix, 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:String

The namespace prefix to define.

uri:String

The namespace URI to define.

Returns:boolean

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

setNamespaceback to summary
public boolean setNamespace(Namespace namespace)

Define a Namespace to be available for the XPath expression.

Parameters
namespace:Namespace

The namespace to define.

Returns:boolean

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

Exceptions
NullPointerException:
if the namespace is null.
setNamespacesback to summary
public boolean setNamespaces(Collection<Namespace> namespaces)

Add a number of namespaces to this XPathBuilder

Parameters
namespaces:Collection<Namespace>

The namespaces to set.

Returns:boolean

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

Exceptions
NullPointerException:
if the namespace collection, or any of its members are null.
setVariableback to summary
public boolean setVariable(String qname, 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, Namespace, 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:String

The variable name to define.

value:Object

The variable value to set.

Returns:boolean

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

Exceptions
NullPointerException:
if the name is null.