org.jaxen
Interface XPath

All Known Implementing Classes:
BaseXPath

public interface XPath

Defines the interface to an object which represents an XPath 1.0 expression which can be evaluated against a variety of different XML object models.

Most of the evaluation methods take a context object. This is typically a node or node set object (which is typically a List of node objects) or a Jaxen Context object. A null context is allowed, meaning that there is no XML nodes on which to evaluate.

Author:
bob mcwhirter, James Strachan
See Also:
XPath for dom4j, XPath for JDOM, XPath for W3C DOM, XPath for Electric XML

Method Summary
 void addNamespace(String prefix, String uri)
          Add a namespace prefix-to-URI mapping for this XPath expression.
 boolean booleanValueOf(Object context)
          Retrieve a boolean-value interpretation of this XPath expression when evaluated against a given context.
 Object evaluate(Object context)
          Evaluate this XPath against a given context.
 FunctionContext getFunctionContext()
          Retrieve the FunctionContext used by this XPath expression.
 NamespaceContext getNamespaceContext()
          Retrieve the NamespaceContext used by this XPath expression.
 Navigator getNavigator()
          Retrieve the XML object-model-specific Navigator for us in evaluating this XPath expression.
 VariableContext getVariableContext()
          Retrieve the VariableContext used by this XPath expression.
 Number numberValueOf(Object context)
          Retrieve a number-value interpretation of this XPath expression when evaluated against a given context.
 List selectNodes(Object context)
          Select all nodes that are selectable by this XPath expression.
 Object selectSingleNode(Object context)
          Select only the first node that is selectable by this XPath expression.
 void setFunctionContext(FunctionContext functionContext)
          Set a FunctionContext for use with this XPath expression.
 void setNamespaceContext(NamespaceContext namespaceContext)
          Set a NamespaceContext for use with this XPath expression.
 void setVariableContext(VariableContext variableContext)
          Set a VariableContext for use with this XPath expression.
 String stringValueOf(Object context)
          Retrieve a string-value interpretation of this XPath expression when evaluated against a given context.
 String valueOf(Object context)
          Deprecated. As of Jaxen 1.0 RC1 please use instead
 

Method Detail

evaluate

public Object evaluate(Object context)
                throws JaxenException
Evaluate this XPath against a given context.

The context of evaluation my be a document, an element, or a set of elements.

If the expression evaluates to a single primitive (String, Number or Boolean) type, it is returned directly. Otherwise, the returned value is a List (a node-set, in the terms of the specification) of values.

When using this method, one must be careful to test the class of the returned objects, and of each of the composite members if a List is returned. If the returned members are XML entities, they will be the actual Document, Element or Attribute objects as defined by the concrete XML object-model implementation, directly from the context document. This does not return copies of anything, but merely returns references to entities within the source document.

Parameters:
The - node, nodeset or Context object for evaluation. This value can be null
Returns:
The result of evaluating the XPath expression against the supplied context.

selectNodes

public List selectNodes(Object context)
                 throws JaxenException
Select all nodes that are selectable by this XPath expression. If multiple nodes match, multiple nodes will be returned.

NOTE: In most cases, nodes will be returned in document-order, as defined by the XML Canonicalization specification. The exception occurs when using XPath expressions involving the union operator (denoted with the pipe '|' character).

Parameters:
The - node, nodeset or Context object for evaluation. This value can be null
Returns:
The node-set of all items selected by this XPath expression.
See Also:
selectSingleNode(java.lang.Object)

selectSingleNode

public Object selectSingleNode(Object context)
                        throws JaxenException
Select only the first node that is selectable by this XPath expression. If multiple nodes match, only one node will be returned. NOTE: In most cases, the selected node will be the first selectable node in document-order, as defined by the XML Canonicalization specification. The exception occurs when using XPath expressions involving the union operator (denoted with the pipe '|' character).

Parameters:
The - node, nodeset or Context object for evaluation. This value can be null
Returns:
The node-set of all items selected by this XPath expression.
See Also:
selectNodes(java.lang.Object)

valueOf

public String valueOf(Object context)
               throws JaxenException
Deprecated. As of Jaxen 1.0 RC1 please use instead

Retrieve a string-value interpretation of this XPath expression when evaluated against a given context.

The string-value of the expression is determined per the string(..) core function as defined in the XPath specification. This means that an expression that selects more than one nodes will return the string value of the first node in the node set..

Parameters:
The - node, nodeset or Context object for evaluation. This value can be null
Returns:
The string-value interpretation of this expression.

stringValueOf

public String stringValueOf(Object context)
                     throws JaxenException
Retrieve a string-value interpretation of this XPath expression when evaluated against a given context.

The string-value of the expression is determined per the string(..) core function as defined in the XPath specification. This means that an expression that selects more than one nodes will return the string value of the first node in the node set..

Parameters:
The - node, nodeset or Context object for evaluation. This value can be null
Returns:
The string-value interpretation of this expression.

booleanValueOf

public boolean booleanValueOf(Object context)
                       throws JaxenException
Retrieve a boolean-value interpretation of this XPath expression when evaluated against a given context.

The boolean-value of the expression is determined per the boolean(..) core function as defined in the XPath specification. This means that an expression that selects zero nodes will return false, while an expression that selects one-or-more nodes will return true.

Parameters:
The - node, nodeset or Context object for evaluation. This value can be null
Returns:
The boolean-value interpretation of this expression.

numberValueOf

public Number numberValueOf(Object context)
                     throws JaxenException
Retrieve a number-value interpretation of this XPath expression when evaluated against a given context.

The number-value of the expression is determined per the number(..) core function as defined in the XPath specification. This means that if this expression selects multiple nodes, the number-value of the first node is returned.

Parameters:
The - node, nodeset or Context object for evaluation. This value can be null
Returns:
The number-value interpretation of this expression.

addNamespace

public void addNamespace(String prefix,
                         String uri)
                  throws JaxenException
Add a namespace prefix-to-URI mapping for this XPath expression.

Namespace prefix-to-URI mappings in an XPath are independant of those used within any document. Only the mapping explicitly added to this XPath will be available for resolving the XPath expression.

This is a convenience method for adding mappings to the default NamespaceContext in place for this XPath. If you have installed a specific custom NamespaceContext, then this method will throw a JaxenException.

Parameters:
prefix - The namespace prefix.
uri - The namespace URI.
Throws:
JaxenException - If a NamespaceContext used by this XPath has been explicitly installed.

setNamespaceContext

public void setNamespaceContext(NamespaceContext namespaceContext)
Set a NamespaceContext for use with this XPath expression.

A NamespaceContext is responsible for translating namespace prefixes within the expression into namespace URIs.

Parameters:
namespaceContext - The NamespaceContext to install for this expression.
See Also:
NamespaceContext, NamespaceContext.translateNamespacePrefixToUri(java.lang.String)

setFunctionContext

public void setFunctionContext(FunctionContext functionContext)
Set a FunctionContext for use with this XPath expression.

A FunctionContext is responsible for resolving all function calls used within the expression.

Parameters:
functionContext - The FunctionContext to install for this expression.
See Also:
FunctionContext, FunctionContext.getFunction(java.lang.String, java.lang.String, java.lang.String)

setVariableContext

public void setVariableContext(VariableContext variableContext)
Set a VariableContext for use with this XPath expression.

A VariableContext is responsible for resolving all variables referenced within the expression.

Parameters:
variableContext - The VariableContext to install for this expression.
See Also:
VariableContext, VariableContext.getVariableValue(java.lang.String, java.lang.String, java.lang.String)

getNamespaceContext

public NamespaceContext getNamespaceContext()
Retrieve the NamespaceContext used by this XPath expression.

A FunctionContext is responsible for resolving all function calls used within the expression.

If this XPath expression has not previously had a NamespaceContext installed, a new default NamespaceContext will be created, installed and returned.

Returns:
The NamespaceContext used by this expression.
See Also:
NamespaceContext

getFunctionContext

public FunctionContext getFunctionContext()
Retrieve the FunctionContext used by this XPath expression.

A FunctionContext is responsible for resolving all function calls used within the expression.

If this XPath expression has not previously had a FunctionContext installed, a new default FunctionContext will be created, installed and returned.

Returns:
The FunctionContext used by this expression.
See Also:
FunctionContext

getVariableContext

public VariableContext getVariableContext()
Retrieve the VariableContext used by this XPath expression.

A VariableContext is responsible for resolving all variables referenced within the expression.

If this XPath expression has not previously had a VariableContext installed, a new default VariableContext will be created, installed and returned.

Returns:
The VariableContext used by this expression.
See Also:
VariableContext

getNavigator

public Navigator getNavigator()
Retrieve the XML object-model-specific Navigator for us in evaluating this XPath expression.
Returns:
The implementation-specific Navigator.


Copyright © 2002 bob mcwhirter & James Strachan. All Rights Reserved. Hosted by

SourceForge Logo