Top Description Inners Fields Constructors Methods
org.jdom2.xpath

public abstract Class XPath

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Known Direct Subclasses
org.jdom2.xpath.jaxen.JDOMXPath
Annotations
@Deprecated
Imports
java.io.*, java.lang.reflect.*, java.util.*, org.jdom2.*, org.jdom2.internal.SystemProperty

Deprecated

Use XPathFactory/XPathExpression/XPathBuilder instead.

A utility class for performing XPath calls on JDOM nodes, with a factory interface for obtaining a first XPath instance. Users operate against this class while XPath vendors can plug-in implementations underneath. Users can choose an implementation using either setXPathClass or the system property "org.jdom2.xpath.class".
Author
Laurent Bihanic

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
XPath.XPathString

The XPathString is dedicated to serialize instances of XPath subclasses in a implementation-independent manner.

Field Summary

Modifier and TypeField and Description
private static Constructor<? extends XPath>
constructor

The constructor to instantiate a new XPath concrete implementation.

private static final String
DEFAULT_XPATH_CLASS

The default implementation class to use if none was configured.

public static final String
JDOM_OBJECT_MODEL_URI

The string passable to the JAXP 1.3 XPathFactory isObjectModelSupported() method to query an XPath engine regarding its support for JDOM.

private static final long
serialVersionUID

Standard JDOM2 Serialization.

private static final String
XPATH_CLASS_PROPERTY

The name of the system property from which to retrieve the name of the implementation class to use.

Constructor Summary

AccessConstructor and Description
public
XPath()

Method Summary

Modifier and TypeMethod and Description
public abstract void
addNamespace(Namespace
the namespace.
namespace)

Adds a namespace definition to the list of namespaces known of this XPath expression.

public void
addNamespace(String
the namespace prefix.
prefix, String
the namespace URI.
uri)

Adds a namespace definition (prefix and URI) to the list of namespaces known of this XPath expression.

public abstract String

Returns:

the wrapped XPath expression as a string.
getXPath()

Returns the wrapped XPath expression as a string.

public static XPath

Returns:

an XPath instance representing the input path
newInstance(String
the XPath expression to wrap.
path)

Deprecated as a consequence of XPath being deprecated.
Creates a new XPath wrapper object, compiling the specified XPath expression.
public abstract Number

Returns:

the number value of the first node selected by applying the wrapped XPath expression to the given context, null if no node was selected or the special value java.lang.Double#NaN (Not-a-Number) if the selected value can not be converted into a number value.
numberValueOf(Object
the element to use as context for evaluating the XPath expression.
context)

Returns the number value of the first node selected by applying the wrapped XPath expression to the given context.

public abstract List<?>

Returns:

the list of selected items, which may be of types: Element, Attribute, Text, CDATA, Comment, ProcessingInstruction, Boolean, Double, or String.
selectNodes(Object
the node to use as context for evaluating the XPath expression.
context)

Evaluates the wrapped XPath expression and returns the list of selected items.

public static List<?>

Returns:

the list of selected items, which may be of types: Element, Attribute, Text, CDATA, Comment, ProcessingInstruction, Boolean, Double, or String.
selectNodes(Object
the node to use as context for evaluating the XPath expression.
context, String
the XPath expression to evaluate.
path)

Evaluates an XPath expression and returns the list of selected items.

public abstract Object

Returns:

the first selected item, which may be of types: Element, Attribute, Text, CDATA, Comment, ProcessingInstruction, Boolean, Double, String, or null if no item was selected.
selectSingleNode(Object
the node to use as context for evaluating the XPath expression.
context)

Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).

public static Object

Returns:

the first selected item, which may be of types: Element, Attribute, Text, CDATA, Comment, ProcessingInstruction, Boolean, Double, String, or null if no item was selected.
selectSingleNode(Object
the element to use as context for evaluating the XPath expression.
context, String
the XPath expression to evaluate.
path)

Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).

public abstract void
setVariable(String
the variable name.
name, Object
the variable value.
value)

Defines an XPath variable and sets its value.

public static void
setXPathClass(Class<? extends XPath>
the concrete subclass of XPath.
aClass)

Sets the concrete XPath subclass to use when allocating XPath instances.

public abstract String

Returns:

the string value of the first node selected by applying the wrapped XPath expression to the given context.
valueOf(Object
the element to use as context for evaluating the XPath expression.
context)

Returns the string value of the first node selected by applying the wrapped XPath expression to the given context.

protected final Object

Returns:

an XPathString instance configured with the wrapped XPath expression.
writeReplace()

[Serialization support] Returns the alternative object to write to the stream when serializing this object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

constructorback to summary
private static Constructor<? extends XPath> constructor

The constructor to instantiate a new XPath concrete implementation.

See Also
newInstance
DEFAULT_XPATH_CLASSback to summary
private static final String DEFAULT_XPATH_CLASS

The default implementation class to use if none was configured.

JDOM_OBJECT_MODEL_URIback to summary
public static final String JDOM_OBJECT_MODEL_URI

The string passable to the JAXP 1.3 XPathFactory isObjectModelSupported() method to query an XPath engine regarding its support for JDOM. Defined to be the well-known URI "http://jdom.org/jaxp/xpath/jdom".

serialVersionUIDback to summary
private static final long serialVersionUID

Standard JDOM2 Serialization. Default mechanism.

XPATH_CLASS_PROPERTYback to summary
private static final String XPATH_CLASS_PROPERTY

The name of the system property from which to retrieve the name of the implementation class to use.

The property name is: "org.jdom2.xpath.class".

Constructor Detail

XPathback to summary
public XPath()

Method Detail

addNamespaceback to summary
public abstract void addNamespace(Namespace namespace)

Adds a namespace definition to the list of namespaces known of this XPath expression.

Note

In XPath, there is no such thing as a 'default namespace'. The empty prefix always resolves to the empty namespace URI.

Parameters
namespace:Namespace

the namespace.

addNamespaceback to summary
public void addNamespace(String prefix, String uri)

Adds a namespace definition (prefix and URI) to the list of namespaces known of this XPath expression.

Note

In XPath, there is no such thing as a 'default namespace'. The empty prefix always resolves to the empty namespace URI.

Parameters
prefix:String

the namespace prefix.

uri:String

the namespace URI.

Exceptions
IllegalNameException:
if the prefix or uri are null or empty strings or if they contain illegal characters.
getXPathback to summary
public abstract String getXPath()

Returns the wrapped XPath expression as a string.

Returns:String

the wrapped XPath expression as a string.

newInstanceback to summary
public static XPath newInstance(String path) throws JDOMException

Deprecated

as a consequence of XPath being deprecated. See corresponding docs for further information.

Creates a new XPath wrapper object, compiling the specified XPath expression.

Parameters
path:String

the XPath expression to wrap.

Returns:XPath

an XPath instance representing the input path

Exceptions
JDOMException:
if the XPath expression is invalid.
numberValueOfback to summary
public abstract Number numberValueOf(Object context) throws JDOMException

Returns the number value of the first node selected by applying the wrapped XPath expression to the given context.

Parameters
context:Object

the element to use as context for evaluating the XPath expression.

Returns:Number

the number value of the first node selected by applying the wrapped XPath expression to the given context, null if no node was selected or the special value java.lang.Double#NaN (Not-a-Number) if the selected value can not be converted into a number value.

Exceptions
JDOMException:
if the XPath expression is invalid or its evaluation on the specified context failed.
selectNodesback to summary
public abstract List<?> selectNodes(Object context) throws JDOMException

Evaluates the wrapped XPath expression and returns the list of selected items.

Parameters
context:Object

the node to use as context for evaluating the XPath expression.

Returns:List<?>

the list of selected items, which may be of types: Element, Attribute, Text, CDATA, Comment, ProcessingInstruction, Boolean, Double, or String.

Exceptions
JDOMException:
if the evaluation of the XPath expression on the specified context failed.
selectNodesback to summary
public static List<?> selectNodes(Object context, String path) throws JDOMException

Evaluates an XPath expression and returns the list of selected items.

Note

This method should not be used when the same XPath expression needs to be applied several times (on the same or different contexts) as it requires the expression to be compiled before being evaluated. In such cases, allocating an XPath wrapper instance and evaluating it several times is way more efficient.

Parameters
context:Object

the node to use as context for evaluating the XPath expression.

path:String

the XPath expression to evaluate.

Returns:List<?>

the list of selected items, which may be of types: Element, Attribute, Text, CDATA, Comment, ProcessingInstruction, Boolean, Double, or String.

Exceptions
JDOMException:
if the XPath expression is invalid or its evaluation on the specified context failed.
selectSingleNodeback to summary
public abstract Object selectSingleNode(Object context) throws JDOMException

Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).

Parameters
context:Object

the node to use as context for evaluating the XPath expression.

Returns:Object

the first selected item, which may be of types: Element, Attribute, Text, CDATA, Comment, ProcessingInstruction, Boolean, Double, String, or null if no item was selected.

Exceptions
JDOMException:
if the evaluation of the XPath expression on the specified context failed.
selectSingleNodeback to summary
public static Object selectSingleNode(Object context, String path) throws JDOMException

Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).

Note

This method should not be used when the same XPath expression needs to be applied several times (on the same or different contexts) as it requires the expression to be compiled before being evaluated. In such cases, allocating an XPath wrapper instance and evaluating it several times is way more efficient.

Parameters
context:Object

the element to use as context for evaluating the XPath expression.

path:String

the XPath expression to evaluate.

Returns:Object

the first selected item, which may be of types: Element, Attribute, Text, CDATA, Comment, ProcessingInstruction, Boolean, Double, String, or null if no item was selected.

Exceptions
JDOMException:
if the XPath expression is invalid or its evaluation on the specified context failed.
setVariableback to summary
public abstract void setVariable(String name, Object value)

Defines an XPath variable and sets its value.

Parameters
name:String

the variable name.

value:Object

the variable value.

Exceptions
IllegalArgumentException:
if name is not a valid XPath variable name or if the value type is not supported by the underlying implementation
setXPathClassback to summary
public static void setXPathClass(Class<? extends XPath> aClass) throws JDOMException

Sets the concrete XPath subclass to use when allocating XPath instances.

Parameters
aClass:Class<? extends XPath>

the concrete subclass of XPath.

Exceptions
JDOMException:
if aClass is not a concrete subclass of XPath.
IllegalArgumentException:
if aClass is null.
valueOfback to summary
public abstract String valueOf(Object context) throws JDOMException

Returns the string value of the first node selected by applying the wrapped XPath expression to the given context.

Parameters
context:Object

the element to use as context for evaluating the XPath expression.

Returns:String

the string value of the first node selected by applying the wrapped XPath expression to the given context.

Exceptions
JDOMException:
if the XPath expression is invalid or its evaluation on the specified context failed.
writeReplaceback to summary
protected final Object writeReplace() throws ObjectStreamException

[Serialization support] Returns the alternative object to write to the stream when serializing this object. This method returns an instance of a dedicated nested class to serialize XPath expressions independently of the concrete implementation being used.

Note

Subclasses are not allowed to override this method to ensure valid serialization of all implementations.

Returns:Object

an XPathString instance configured with the wrapped XPath expression.

Exceptions
ObjectStreamException:
never.
org.jdom2.xpath back to summary

private final Class XPath.XPathString

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
The XPathString is dedicated to serialize instances of XPath subclasses in a implementation-independent manner.

XPathString ensures that only string data are serialized. Upon deserialization, XPathString relies on XPath factory method to to create instances of the concrete XPath wrapper currently configured.

Field Summary

Modifier and TypeField and Description
private static final long
serialVersionUID

Standard JDOM2 Serialization.

private String
xPath

The XPath expression as a string.

Constructor Summary

AccessConstructor and Description
public
XPathString(String
the XPath expression.
xpath)

Creates a new XPathString instance from the specified XPath expression.

Method Summary

Modifier and TypeMethod and Description
private Object

Returns:

an instance of a concrete implementation of XPath.
readResolve()

[Serialization support] Resolves the read XPathString objects into XPath implementations.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

serialVersionUIDback to summary
private static final long serialVersionUID

Standard JDOM2 Serialization. Default mechanism.

xPathback to summary
private String xPath

The XPath expression as a string.

Constructor Detail

XPathStringback to summary
public XPathString(String xpath)

Creates a new XPathString instance from the specified XPath expression.

Parameters
xpath:String

the XPath expression.

Method Detail

readResolveback to summary
private Object readResolve() throws ObjectStreamException

[Serialization support] Resolves the read XPathString objects into XPath implementations.

Returns:Object

an instance of a concrete implementation of XPath.

Exceptions
ObjectStreamException:
if no XPath could be built from the read object.