org.jdom.xpath
Class XPath

java.lang.Object
  |
  +--org.jdom.xpath.XPath

All Implemented Interfaces:

java.io.Serializable

public abstract class XPath

extends java.lang.Object

implements java.io.Serializable

A JDOM-oriented wrapper around XPath engines.

Author:

Laurent Bihanic

See Also:

Serialized Form

Constructor Summary

protected

XPath(java.lang.String expr) Creates a new XPath wrapper object, compiling the specified XPath expression.

Method Summary

abstract java.lang.String	getXPath() Returns the wrapped XPath expression as a string.
static XPath	newInstance(java.lang.String path) Creates a new XPath wrapper object, compiling the specified XPath expression.
abstract java.lang.Number	numberValueOf(java.lang.Object context) Returns the number value of the first node selected by applying the wrapped XPath expression to the given context.
abstract java.util.List	selectNodes(java.lang.Object context) Evaluates the wrapped XPath expression and returns the list of selected nodes.
static java.util.List	selectNodes(java.lang.Object context, java.lang.String path) Evaluates an XPath expression and returns the list of selected nodes.
abstract java.lang.Object	selectSingleNode(java.lang.Object context) Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes.
static java.lang.Object	selectSingleNode(java.lang.Object context, java.lang.String path) Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes.
abstract void	setVariable(java.lang.String name, java.lang.Object value) Defines an XPath variable and sets its value.
abstract java.lang.String	valueOf(java.lang.Object context) Returns the string value of the first node selected by applying the wrapped XPath expression to the given context.

Methods inherited from class java.lang.Object

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

Constructor Detail

XPath

protected XPath(java.lang.String expr)
         throws JDOMException

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

Parameters:

expr - the XPath expression to wrap.

Throws:

JDOMException - if the XPath expression is invalid.

Method Detail

newInstance

public static XPath newInstance(java.lang.String path)
                         throws JDOMException

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.

selectNodes

public abstract java.util.List selectNodes(java.lang.Object context)
                                    throws JDOMException

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

Parameters:

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

Returns:

the list of selected nodes, which can be instances of the following JDOM classes: Element, Attribute, Text, CDATA, Comment or ProcessingInstruction.

Throws:

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

selectSingleNode

public abstract java.lang.Object selectSingleNode(java.lang.Object context)
                                           throws JDOMException

Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes.

Parameters:

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

Returns:

the first selected nodes, which is an instance of one of the following JDOM classes: Element, Attribute, Text, CDATA, Comment or ProcessingInstruction or null if no node was selected.

Throws:

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

valueOf

public abstract java.lang.String valueOf(java.lang.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 - 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.

numberValueOf

public abstract java.lang.Number numberValueOf(java.lang.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 - 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 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.

setVariable

public abstract void setVariable(java.lang.String name,
                                 java.lang.Object value)
                          throws java.lang.IllegalArgumentException

Defines an XPath variable and sets its value.

Parameters:

name - the variable name.

value - the variable value.

Throws:

java.lang.IllegalArgumentException - if name is not a valid XPath variable name or if the value type is not supported by the underlying implementation

getXPath

public abstract java.lang.String getXPath()

Returns the wrapped XPath expression as a string.

Returns:

the wrapped XPath expression as a string.

selectNodes

public static java.util.List selectNodes(java.lang.Object context,
                                         java.lang.String path)
                                  throws JDOMException

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

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 - the node to use as context for evaluating the XPath expression.

path - the XPath expression to evaluate.

Returns:

the list of selected nodes, which can be instances of the following JDOM classes: Element, Attribute, Text, CDATA, Comment or ProcessingInstruction.

Throws:

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

selectSingleNode

public static java.lang.Object selectSingleNode(java.lang.Object context,
                                                java.lang.String path)
                                         throws JDOMException

Evaluates the wrapped XPath expression and returns the first entry in the list of selected nodes.

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 - the element to use as context for evaluating the XPath expression.

path - the XPath expression to evaluate.

Returns:

the first selected nodes, which is an instance of one of the following JDOM classes: Element, Attribute, Text, CDATA, Comment or ProcessingInstruction or null if no node was selected.

Throws:

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