Top Description Fields Constructors Methods
org.jdom2.xpath

public abstract Class XPathFactory

extends Object
Class Inheritance
Known Direct Subclasses
org.jdom2.xpath.jaxen.JaxenXPathFactory
Imports
java.util.Collection, .Map, java.util.concurrent.atomic.AtomicReference, org.jdom2.JDOMConstants, .Namespace, org.jdom2.filter.Filter, .Filters, org.jdom2.internal.ReflectionConstructor, .SystemProperty, org.jdom2.xpath.jaxen.JaxenXPathFactory
XPathFactory allows JDOM users to configure which XPath implementation to use when evaluating XPath expressions.

JDOM does not extend the core Java XPath API (javax.xml.xpath.XPath). Instead it creates a new API that is more JDOM and Java friendly leading to neater and more understandable code (in a JDOM context).

A JDOM XPathFactory instance is able to create JDOM XPathExpression instances that can be used to evaluate XPath expressions against JDOM Content.

The XPathFactory allows either default or custom XPathFactory instances to be created. If you use the newInstance(String) method then an XPathFactory of that specific type will be created. If you use the instance() method then a default XPathFactory instance will be returned.

Instances of XPathFactory are specified to be thread-safe. You can reuse an XPathFactory in multiple threads. Instances of XPathExpression are NOT thread-safe.

Author
Rolf Lear
Since
JDOM2

Field Summary

Modifier and TypeField and Description
private static final String
DEFAULTFACTORY

private static final AtomicReference<XPathFactory>
defaultreference

An atomic reference storing an instance of the default XPathFactory.

private static final Namespace[]
EMPTYNS

Constructor Summary

AccessConstructor and Description
public
XPathFactory()

Method Summary

Modifier and TypeMethod and Description
public abstract <
The generic type of the results that the XPathExpression will produce.
T> XPathExpression<T>

Returns:

an XPathExpression<> instance.
compile(String
The XPath expression.
expression, Filter<T>
The Filter that is used to coerce the XPath result data in to the generic-typed results. Note that the Filters class has a number of predefined, useful filters.
filter, Map<String, Object>
Any variable values that may be referenced from the query. A null value indicates that there are no variables.
variables, Namespace...
Any namespaces that may be referenced from the query
namespaces)

Create a Compiled XPathExpression<> instance from this factory.

public <
The generic type of the results that the XPathExpression will produce.
T> XPathExpression<T>

Returns:

an XPathExpression<T> instance.
compile(String
The XPath expression.
expression, Filter<T>
The Filter that is used to coerce the xpath result data in to the generic-typed results. Note that the Filters class has a number of predefined, useful filters.
filter, Map<String, Object>
Any variable values that may be referenced from the query. A null value indicates that there are no variables.
variables, Collection<Namespace>
List of all namespaces that may be referenced from the query
namespaces)

Create a XPathExpression<> instance from this factory.

public <
The generic type of the results that the XPathExpression will produce.
T> XPathExpression<T>

Returns:

an XPathExpression<T> instance.
compile(String
The XPath expression.
expression, Filter<T>
The Filter that is used to coerce the xpath result data in to the generic-typed results. Note that the Filters class has a number of predefined, useful filters.
filter)

Create a XPathExpression<T> instance from this factory.

public XPathExpression<Object>

Returns:

an XPathExpression<Object> instance.
compile(String
The XPath expression.
expression)

Create a XPathExpression<Object> instance from this factory.

public static final XPathFactory

Returns:

the default XPathFactory instance
instance()

Obtain an instance of an XPathFactory using the default mechanisms to determine what XPathFactory implementation to use.

public static final XPathFactory

Returns:

An XPathFactory of the specified class.
newInstance(String
The name of the XPathFactory class to create.
factoryclass)

Create a new instance of an explicit XPathFactory.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

DEFAULTFACTORYback to summary
private static final String DEFAULTFACTORY
defaultreferenceback to summary
private static final AtomicReference<XPathFactory> defaultreference

An atomic reference storing an instance of the default XPathFactory.

EMPTYNSback to summary
private static final Namespace[] EMPTYNS

Constructor Detail

XPathFactoryback to summary
public XPathFactory()

Method Detail

compileback to summary
public abstract <T> XPathExpression<T> compile(String expression, Filter<T> filter, Map<String, Object> variables, Namespace... namespaces)

Create a Compiled XPathExpression<> instance from this factory. This is the only abstract method on this class. All other compile and evaluate methods prepare the data in some way to call this compile method.

XPathFactory implementations override this method to implement support for the JDOM/XPath API.

A Filter is used to coerce resulting XPath data in to a suitable JDOM generic type. Note that the Filters class has a number of predefined, useful filters.

Namespace

XPath expressions are always namespace aware, and expect to be able to resolve prefixes to namespace URIs. In XPath expressions the prefix "" always resolves to the empty Namespace URI "". A prefix in an XPath query is expected to resolve to exactly one URI. Multiple different prefixes in the expression may resolve to the same URI.

This compile method ensures that these XPath/Namespace rules are followed and thus this method will throw IllegalArgumentException if:

  • a namespace has the empty-string prefix but has a non-empty URI.
  • more than one Namespace has any one prefix.

Variables

Variables are referenced from XPath expressions using a $varname syntax. The variable name may be a Namespace qualified variable name of the form $pfx:localname. Variables $pa:var and $pb:var are the identical variables if the namespace URI for prefix 'pa' is the same URI as for prefix 'pb'.

This compile method expects all variable names to be expressed in a prefix-qualified format, where all prefixes have to be available in one of the specified Namespace instances.

e.g. if you specify a variable name "ns:var" with value "value", you also need to have some namespace provided with the prefix "ns" such as Namespace.getNamespace("ns", "http://example.com/nsuri");

Some XPath libraries allow null variable values (Jaxen), some do not (native Java). This compile method will silently convert any null Variable value to an empty string "".

Variables are provided in the form of a Map where the key is the variable name and the mapped value is the variable value. If the entire map is null then the compile Method assumes there are no variables.

In light of the above, this compile method will throw an IllegalArgumentException if:

  • a variable name is not a valid XML QName.
  • The prefix associated with a variable name is not available as a Namespace.
A NullPointerException will be thrown if the map contains a null variable name
Parameters
<T>
The generic type of the results that the XPathExpression will produce.
expression:String

The XPath expression.

filter:Filter<T>

The Filter that is used to coerce the XPath result data in to the generic-typed results. Note that the Filters class has a number of predefined, useful filters.

variables:Map<String, Object>

Any variable values that may be referenced from the query. A null value indicates that there are no variables.

namespaces:Namespace[]

Any namespaces that may be referenced from the query

Returns:XPathExpression<T>

an XPathExpression<> instance.

Exceptions
NullPointerException:
if the query, filter, any namespace, any variable name or any variable value is null (although the entire variables value may be null).
IllegalArgumentException:
if any two Namespace values share the same prefix, or if there is any other reason that the XPath query cannot be compiled.
See Also
org.jdom2.filter.Filters
compileback to summary
public <T> XPathExpression<T> compile(String expression, Filter<T> filter, Map<String, Object> variables, Collection<Namespace> namespaces)

Create a XPathExpression<> instance from this factory.

Parameters
<T>
The generic type of the results that the XPathExpression will produce.
expression:String

The XPath expression.

filter:Filter<T>

The Filter that is used to coerce the xpath result data in to the generic-typed results. Note that the Filters class has a number of predefined, useful filters.

variables:Map<String, Object>

Any variable values that may be referenced from the query. A null value indicates that there are no variables.

namespaces:Collection<Namespace>

List of all namespaces that may be referenced from the query

Returns:XPathExpression<T>

an XPathExpression<T> instance.

Exceptions
NullPointerException:
if the query, filter, namespaces, any variable name or any variable value is null (although the entire variables value may be null).
IllegalArgumentException:
if any two Namespace values share the same prefix, or if there is any other reason that the XPath query cannot be compiled.
compileback to summary
public <T> XPathExpression<T> compile(String expression, Filter<T> filter)

Create a XPathExpression<T> instance from this factory.

Parameters
<T>
The generic type of the results that the XPathExpression will produce.
expression:String

The XPath expression.

filter:Filter<T>

The Filter that is used to coerce the xpath result data in to the generic-typed results. Note that the Filters class has a number of predefined, useful filters.

Returns:XPathExpression<T>

an XPathExpression<T> instance.

Exceptions
NullPointerException:
if the query or filter is null
IllegalArgumentException:
if there is any reason that the XPath query cannot be compiled.
compileback to summary
public XPathExpression<Object> compile(String expression)

Create a XPathExpression<Object> instance from this factory.

Parameters
expression:String

The XPath expression.

Returns:XPathExpression<Object>

an XPathExpression<Object> instance.

Exceptions
NullPointerException:
if the query or filter is null
IllegalArgumentException:
if there is any reason that the XPath query cannot be compiled.
instanceback to summary
public static final XPathFactory instance()

Obtain an instance of an XPathFactory using the default mechanisms to determine what XPathFactory implementation to use.

The exact same XPathFactory instance will be returned from each call.

The default mechanism will inspect the system property (only once) JDOMConstants#JDOM2_PROPERTY_XPATH_FACTORY to determine what class should be used for the XPathFactory. If that property is not set then JDOM will use the JaxenXPathFactory.

Returns:XPathFactory

the default XPathFactory instance

newInstanceback to summary
public static final XPathFactory newInstance(String factoryclass)

Create a new instance of an explicit XPathFactory. A new instance of the specified XPathFactory is created each time. The target XPathFactory needs to have a no-argument default constructor.

This method is a convenience mechanism only, and JDOM users are free to create a custom XPathFactory instance and use a simple:
XPathFactory fac = new MyXPathFactory(arg1, arg2, ...)

Parameters
factoryclass:String

The name of the XPathFactory class to create.

Returns:XPathFactory

An XPathFactory of the specified class.