org.jdom.xpath
Class XPath
- Serializable
public abstract class XPath
extends java.lang.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
setXPathClass(Class)
or
the system property "org.jdom.xpath.class".
$Revision: 1.17 $, $Date: 2007/11/10 05:29:02 $static 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.
|
void | addNamespace(String prefix, String uri) - Adds a namespace definition (prefix and URI) to the list of
namespaces known of this XPath expression.
|
abstract void | addNamespace(Namespace namespace) - Adds a namespace definition to the list of namespaces known of
this XPath expression.
|
abstract String | getXPath() - Returns the wrapped XPath expression as a string.
|
static XPath | newInstance(String path) - Creates a new XPath wrapper object, compiling the specified
XPath expression.
|
abstract Number | numberValueOf(Object context) - Returns the number value of the first node selected by applying
the wrapped XPath expression to the given context.
|
abstract List | selectNodes(Object context) - Evaluates the wrapped XPath expression and returns the list
of selected items.
|
static List | selectNodes(Object context, String path) - Evaluates an XPath expression and returns the list of selected
items.
|
abstract Object | selectSingleNode(Object context) - Evaluates the wrapped XPath expression and returns the first
entry in the list of selected nodes (or atomics).
|
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).
|
abstract void | setVariable(String name, Object value) - Defines an XPath variable and sets its value.
|
static void | setXPathClass(Class aClass) - Sets the concrete XPath subclass to use when allocating XPath
instances.
|
abstract String | valueOf(Object context) - Returns the string value of the first node selected by applying
the wrapped XPath expression to the given context.
|
protected Object | writeReplace() - [Serialization support] Returns the alternative object
to write to the stream when serializing this object.
|
JDOM_OBJECT_MODEL_URI
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".
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.
prefix
- the namespace prefix.uri
- the namespace URI.
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.
namespace
- the namespace.
getXPath
public abstract String getXPath()
Returns the wrapped XPath expression as a string.
- the wrapped XPath expression as a string.
newInstance
public static XPath newInstance(String path)
throws JDOMException
Creates a new XPath wrapper object, compiling the specified
XPath expression.
path
- the XPath expression to wrap.
numberValueOf
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.
context
- the element to use as context for evaluating
the XPath expression.
- 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.
JDOMException
- if the XPath expression is invalid or
its evaluation on the specified context
failed.
selectNodes
public abstract List selectNodes(Object context)
throws JDOMException
Evaluates the wrapped XPath expression and returns the list
of selected items.
context
- the node to use as context for evaluating
the XPath expression.
JDOMException
- if the evaluation of the XPath
expression on the specified context
failed.
selectNodes
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.
context
- the node to use as context for evaluating
the XPath expression.path
- the XPath expression to evaluate.
JDOMException
- if the XPath expression is invalid or
its evaluation on the specified context
failed.
selectSingleNode
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).
context
- the node to use as context for evaluating
the XPath expression.
- 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.
JDOMException
- if the evaluation of the XPath
expression on the specified context
failed.
selectSingleNode
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.
context
- the element to use as context for evaluating
the XPath expression.path
- the XPath expression to evaluate.
- 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.
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.
name
- the variable name.value
- the variable value.
setXPathClass
public static void setXPathClass(Class aClass)
throws JDOMException
Sets the concrete XPath subclass to use when allocating XPath
instances.
aClass
- the concrete subclass of XPath.
valueOf
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.
context
- the element to use as context for evaluating
the XPath expression.
- the string value of the first node selected by applying
the wrapped XPath expression to the given context.
JDOMException
- if the XPath expression is invalid or
its evaluation on the specified context
failed.
writeReplace
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.
- an XPathString instance configured with the wrapped
XPath expression.
Copyright B) 2007 Jason Hunter, Brett McLaughlin. All Rights Reserved.