org.jdom.xpath

Class XPath

public abstract class XPath extends Object implements Serializable

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 {@link #setXPathClass} or the system property "org.jdom.xpath.class".

Version: $Revision: 1.15 $, $Date: 2004/02/06 09:28:32 $

Author: Laurent Bihanic

Method Summary
abstract voidaddNamespace(Namespace namespace)
Adds a namespace definition to the list of namespaces known of this XPath expression.
voidaddNamespace(String prefix, String uri)
Adds a namespace definition (prefix and URI) to the list of namespaces known of this XPath expression.
abstract StringgetXPath()
Returns the wrapped XPath expression as a string.
static XPathnewInstance(String path)
Creates a new XPath wrapper object, compiling the specified XPath expression.
abstract NumbernumberValueOf(Object context)
Returns the number value of the first node selected by applying the wrapped XPath expression to the given context.
abstract ListselectNodes(Object context)
Evaluates the wrapped XPath expression and returns the list of selected items.
static ListselectNodes(Object context, String path)
Evaluates an XPath expression and returns the list of selected items.
abstract ObjectselectSingleNode(Object context)
Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).
static ObjectselectSingleNode(Object context, String path)
Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).
abstract voidsetVariable(String name, Object value)
Defines an XPath variable and sets its value.
static voidsetXPathClass(Class aClass)
Sets the concrete XPath subclass to use when allocating XPath instances.
abstract StringvalueOf(Object context)
Returns the string value of the first node selected by applying the wrapped XPath expression to the given context.
protected ObjectwriteReplace()
[Serialization support] Returns the alternative object to write to the stream when serializing this object.

Method Detail

addNamespace

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 the namespace.

addNamespace

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 the namespace prefix. uri the namespace URI.

Throws: IllegalNameException if the prefix or uri are null or empty strings or if they contain illegal characters.

getXPath

public abstract String getXPath()
Returns the wrapped XPath expression as a string.

Returns: the wrapped XPath expression as a string.

newInstance

public static XPath newInstance(String path)
Creates a new XPath wrapper object, compiling the specified XPath expression.

Parameters: path the XPath expression to wrap.

Throws: JDOMException if the XPath expression is invalid.

numberValueOf

public abstract Number numberValueOf(Object context)
Returns the number value of the first node selected by applying the wrapped XPath expression to the given context.

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

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 {@link java.lang.Double#NaN} (Not-a-Number) if the selected value can not be converted into a number value.

Throws: JDOMException if the XPath expression is invalid or its evaluation on the specified context failed.

selectNodes

public abstract List selectNodes(Object context)
Evaluates the wrapped XPath expression and returns the list of selected items.

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

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

Throws: JDOMException if the evaluation of the XPath expression on the specified context failed.

selectNodes

public static List selectNodes(Object context, String path)
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, {@link #newInstance allocating} an XPath wrapper instance and {@link #selectNodes(java.lang.Object) evaluating} it several times is way more efficient.

Parameters: context the node to use as context for evaluating the XPath expression. path the XPath expression to evaluate.

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

Throws: JDOMException if the XPath expression is invalid or its evaluation on the specified context failed.

selectSingleNode

public abstract Object selectSingleNode(Object context)
Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes (or atomics).

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

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

Throws: JDOMException if the evaluation of the XPath expression on the specified context failed.

selectSingleNode

public static Object selectSingleNode(Object context, String path)
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, {@link #newInstance allocating} an XPath wrapper instance and {@link #selectSingleNode(java.lang.Object) evaluating} it several times is way more efficient.

Parameters: context the element to use as context for evaluating the XPath expression. path the XPath expression to evaluate.

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

Throws: JDOMException if the XPath expression is invalid or its evaluation on the specified context failed.

setVariable

public abstract void setVariable(String name, Object value)
Defines an XPath variable and sets its value.

Parameters: name the variable name. value the variable value.

Throws: IllegalArgumentException if name is not a valid XPath variable name or if the value type is not supported by the underlying implementation

setXPathClass

public static void setXPathClass(Class aClass)
Sets the concrete XPath subclass to use when allocating XPath instances.

Parameters: aClass the concrete subclass of XPath.

Throws: IllegalArgumentException if aClass is null. JDOMException if aClass is not a concrete subclass of XPath.

valueOf

public abstract String valueOf(Object context)
Returns the string value of the first node selected by applying the wrapped XPath expression to the given context.

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

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

Throws: JDOMException if the XPath expression is invalid or its evaluation on the specified context failed.

writeReplace

protected final Object writeReplace()
[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: an XPathString instance configured with the wrapped XPath expression.

Throws: ObjectStreamException never.

Copyright © 2004 Jason Hunter, Brett McLaughlin. All Rights Reserved.