JDOM 2.0.6.1 · org.jdom2.xpath.XPathExpression

Method Summary

Modifier and Type	Method and Description
public XPathExpression<T>	Returns: a new XPathExpression instance that shares the same core details as this. clone() Create a new instance of this XPathExpression that duplicates this instance.
public XPathDiagnostic<T>	Returns: an `XPathDiagnostic` instance. diagnose(Object The context against which to run the query. context, boolean Indicate whether the XPath expression can be terminated after the first successful result value. firstonly) Evaluate the XPath query against the supplied context, but return additional data which may be useful for diagnosing problems with XPath queries.
public List<T>	Returns: a list of the XPath results. evaluate(Object The context against which to process the query. context) Process the compiled XPathExpression against the specified context.
public T	Returns: The first XPath result (if there is any) coerced to the generic type of this XPathExpression, or null if it cannot be coerced. evaluateFirst(Object The context against which to evaluate the expression. This will typically be a Document, Element, or some other JDOM object. context) Return the first value in the XPath query result set type-cast to the return type of this XPathExpression.
public String	Returns: the string representation of the XPath expression getExpression() Get the XPath expression
public Filter<T>	Returns: the `Filter<T>` used to coerce the raw XPath results in to the correct Generic type. getFilter() Get the `Filter<T>` used to coerce the raw XPath results in to the correct Generic type.
public Namespace	Returns: the URI of the specified Namespace prefix getNamespace(String The prefix to select the Namespace URI for. prefix) Get the Namespace associated with a given prefix.
public Namespace[]	Returns: a potentially empty array of Namespaces (never null). getNamespaces() Get the Namespaces that were used to compile this XPathExpression.
public Object	Returns: the value associated to a Variable name. getVariable(String the variable localname to retrieve the value for. localname, Namespace the Namespace in which the variable name was declared. uri) Get the variable value associated to the given variable name.
public Object	Returns: the value associated to a Variable name. getVariable(String the variable qname to retrieve the value for. qname) Get the variable value associated to the given variable qname.
public Object	Returns: The value of the variable prior to this change. setVariable(String The variable localname to change. localname, Namespace the Namespace in which the variable name is declared. uri, Object The new value to set. value) Change the defined value for a variable to some new value.
public Object	Returns: The value of the variable prior to this change. setVariable(String The variable qname to change. qname, Object The new value to set. value) Change the defined value for a variable to some new value.

Method Detail

clone	back to summary
public XPathExpression<T> clone() Create a new instance of this XPathExpression that duplicates this instance. The 'cloned' instance will have the same XPath query, namespace declarations, and variables. Changing a value associated with a variable on the cloned instance will not change this instance's values, and it is safe to run the evaluate methods on the cloned copy at the same time as this copy. Returns:XPathExpression<T> a new XPathExpression instance that shares the same core details as this.

clone

back to summary

public XPathExpression<T> clone()

Create a new instance of this XPathExpression that duplicates this instance.

The 'cloned' instance will have the same XPath query, namespace declarations, and variables. Changing a value associated with a variable on the cloned instance will not change this instance's values, and it is safe to run the evaluate methods on the cloned copy at the same time as this copy.

Returns:XPathExpression<T>: a new XPathExpression instance that shares the same core details as this.

diagnose back to summary

diagnose	back to summary
public XPathDiagnostic<T> diagnose(Object context, boolean firstonly) Evaluate the XPath query against the supplied context, but return additional data which may be useful for diagnosing problems with XPath queries. Parameters context:Object The context against which to run the query. firstonly:boolean Indicate whether the XPath expression can be terminated after the first successful result value. Returns:XPathDiagnostic<T> an `XPathDiagnostic` instance. Exceptions NullPointerException: if the context is null IllegalStateException: if the expression is not runnable or if the context node is not appropriate for the expression.

public XPathDiagnostic<T> diagnose(Object context, boolean firstonly)

Evaluate the XPath query against the supplied context, but return additional data which may be useful for diagnosing problems with XPath queries.

Parameters

context:Object: The context against which to run the query.
firstonly:boolean: Indicate whether the XPath expression can be terminated after the first successful result value.

Returns:XPathDiagnostic<T>

an XPathDiagnostic instance.

Exceptions

NullPointerException:: if the context is null
IllegalStateException:: if the expression is not runnable or if the context node is not appropriate for the expression.

evaluate back to summary

evaluate	back to summary
public List<T> evaluate(Object context) Process the compiled XPathExpression against the specified context. In the JDOM2 XPath API the results of the raw XPath query are processed by the attached `Filter<T>` instance to coerce the results in to the correct generic type for this XPathExpression. The Filter process may cause some XPath results to be removed from the final results. You may instead want to call the `diagnose(Object, boolean)` method to have access to both the raw XPath results as well as the filtered and generically typed results. Parameters context:Object The context against which to process the query. Returns:List<T> a list of the XPath results. Exceptions NullPointerException: if the context is null IllegalStateException: if the expression is not runnable or if the context node is not appropriate for the expression.

public List<T> evaluate(Object context)

Process the compiled XPathExpression against the specified context.

In the JDOM2 XPath API the results of the raw XPath query are processed by the attached Filter<T> instance to coerce the results in to the correct generic type for this XPathExpression. The Filter process may cause some XPath results to be removed from the final results. You may instead want to call the diagnose(Object, boolean) method to have access to both the raw XPath results as well as the filtered and generically typed results.

Parameters

context:Object: The context against which to process the query.

Returns:List<T>

a list of the XPath results.

Exceptions

NullPointerException:: if the context is null
IllegalStateException:: if the expression is not runnable or if the context node is not appropriate for the expression.

evaluateFirst	back to summary
public T evaluateFirst(Object context) Return the first value in the XPath query result set type-cast to the return type of this XPathExpression. The concept of the 'first' result is applied before any JDOM Filter is applied. Thus, if the underlying XPath query has some results, the first result is sent through the filter. If it matches it is returned, if it does not match, then null is returned (even if some subsequent result underlying XPath result would pass the filter). This allows the XPath implementation to optimise the evaluateFirst method by potentially using 'short-circuit' conditions in the evaluation. Parameters context:Object The context against which to evaluate the expression. This will typically be a Document, Element, or some other JDOM object. Returns:T The first XPath result (if there is any) coerced to the generic type of this XPathExpression, or null if it cannot be coerced. Exceptions NullPointerException: if the context is null IllegalStateException: if the expression is not runnable or if the context node is not appropriate for the expression.

evaluateFirst

back to summary

public T evaluateFirst(Object context)

Return the first value in the XPath query result set type-cast to the return type of this XPathExpression.

The concept of the 'first' result is applied before any JDOM Filter is applied. Thus, if the underlying XPath query has some results, the first result is sent through the filter. If it matches it is returned, if it does not match, then null is returned (even if some subsequent result underlying XPath result would pass the filter).

This allows the XPath implementation to optimise the evaluateFirst method by potentially using 'short-circuit' conditions in the evaluation.

Parameters

context:Object: The context against which to evaluate the expression. This will typically be a Document, Element, or some other JDOM object.

Returns:T

The first XPath result (if there is any) coerced to the generic type of this XPathExpression, or null if it cannot be coerced.

Exceptions

NullPointerException:: if the context is null
IllegalStateException:: if the expression is not runnable or if the context node is not appropriate for the expression.

getExpression	back to summary
public String getExpression() Get the XPath expression Returns:String the string representation of the XPath expression

getExpression

back to summary

public String getExpression()

Get the XPath expression

Returns:String: the string representation of the XPath expression

getFilter back to summary

getFilter	back to summary
public Filter<T> getFilter() Get the `Filter<T>` used to coerce the raw XPath results in to the correct Generic type. Returns:Filter<T> the `Filter<T>` used to coerce the raw XPath results in to the correct Generic type.

public Filter<T> getFilter()

Get the Filter<T> used to coerce the raw XPath results in to the correct Generic type.

Returns:Filter<T>: the Filter<T> used to coerce the raw XPath results in to the correct Generic type.

getNamespace	back to summary
public Namespace getNamespace(String prefix) Get the Namespace associated with a given prefix. Parameters prefix:String The prefix to select the Namespace URI for. Returns:Namespace the URI of the specified Namespace prefix Exceptions IllegalArgumentException: if that prefix is not defined.

getNamespace

back to summary

public Namespace getNamespace(String prefix)

Get the Namespace associated with a given prefix.

Parameters

prefix:String: The prefix to select the Namespace URI for.

Returns:Namespace

the URI of the specified Namespace prefix

Exceptions

IllegalArgumentException:: if that prefix is not defined.

getNamespaces	back to summary
public Namespace[] getNamespaces() Get the Namespaces that were used to compile this XPathExpression. Returns:Namespace[] a potentially empty array of Namespaces (never null).

getNamespaces

back to summary

public Namespace[] getNamespaces()

Get the Namespaces that were used to compile this XPathExpression.

Returns:Namespace[]: a potentially empty array of Namespaces (never null).

getVariable	back to summary
public Object getVariable(String localname, Namespace uri) Get the variable value associated to the given variable name. Parameters localname:String the variable localname to retrieve the value for. uri:Namespace the Namespace in which the variable name was declared. Returns:Object the value associated to a Variable name. Exceptions NullPointerException: if name or uri is null IllegalArgumentException: if that variable name is not defined.

getVariable

back to summary

public Object getVariable(String localname, Namespace uri)

Get the variable value associated to the given variable name.

Parameters

localname:String: the variable localname to retrieve the value for.
uri:Namespace: the Namespace in which the variable name was declared.

Returns:Object

the value associated to a Variable name.

Exceptions

NullPointerException:: if name or uri is null
IllegalArgumentException:: if that variable name is not defined.

getVariable back to summary

getVariable	back to summary
public Object getVariable(String qname) Get the variable value associated to the given variable qname. qname must consist of an optional namespace prefix and colon, followed by a mandatory variable localname. If the prefix is not specified, then the Namespace is assumed to be the `Namespace#NO_NAMESPACE`. If the prefix is specified, it must match with one of the declared Namespaces for this XPathExpression Parameters qname:String the variable qname to retrieve the value for. Returns:Object the value associated to a Variable name. Exceptions NullPointerException: if qname is null IllegalArgumentException: if that variable name is not defined.

public Object getVariable(String qname)

Get the variable value associated to the given variable qname.

qname must consist of an optional namespace prefix and colon, followed by a mandatory variable localname. If the prefix is not specified, then the Namespace is assumed to be the Namespace#NO_NAMESPACE. If the prefix is specified, it must match with one of the declared Namespaces for this XPathExpression

Parameters

qname:String: the variable qname to retrieve the value for.

Returns:Object

the value associated to a Variable name.

Exceptions

NullPointerException:: if qname is null
IllegalArgumentException:: if that variable name is not defined.

setVariable	back to summary
public Object setVariable(String localname, Namespace uri, Object value) Change the defined value for a variable to some new value. You may not use this method to add new variables to the compiled XPath, you can only change existing variable values. The value of the variable may be null. Some XPath libraries support a null value, and if the library that this expression is for does not support a null value it should be translated to something meaningful for that library, typically the empty string. Parameters localname:String The variable localname to change. uri:Namespace the Namespace in which the variable name is declared. value:Object The new value to set. Returns:Object The value of the variable prior to this change. Exceptions NullPointerException: if name or uri is null IllegalArgumentException: if name is not already a variable.

setVariable

back to summary

public Object setVariable(String localname, Namespace uri, Object value)

Change the defined value for a variable to some new value. You may not use this method to add new variables to the compiled XPath, you can only change existing variable values.

The value of the variable may be null. Some XPath libraries support a null value, and if the library that this expression is for does not support a null value it should be translated to something meaningful for that library, typically the empty string.

Parameters

localname:String: The variable localname to change.
uri:Namespace: the Namespace in which the variable name is declared.
value:Object: The new value to set.

Returns:Object

The value of the variable prior to this change.

Exceptions

NullPointerException:: if name or uri is null
IllegalArgumentException:: if name is not already a variable.

setVariable back to summary

setVariable	back to summary
public Object setVariable(String qname, Object value) Change the defined value for a variable to some new value. You may not use this method to add new variables to the compiled XPath, you can only change existing variable values. The value of the variable may be null. Some XPath libraries support a null value, and if the library that this expression is for does not support a null value it should be translated to something meaningful for that library, typically the empty string. qname must consist of an optional namespace prefix and colon, followed by a mandatory variable localname. If the prefix is not specified, then the Namespace is assumed to be the `Namespace#NO_NAMESPACE`. If the prefix is specified, it must match with one of the declared Namespaces for this XPathExpression Parameters qname:String The variable qname to change. value:Object The new value to set. Returns:Object The value of the variable prior to this change. Exceptions NullPointerException: if qname is null IllegalArgumentException: if name is not already a variable.

public Object setVariable(String qname, Object value)

Change the defined value for a variable to some new value. You may not use this method to add new variables to the compiled XPath, you can only change existing variable values.

Parameters

qname:String: The variable qname to change.
value:Object: The new value to set.

Returns:Object

The value of the variable prior to this change.

Exceptions

NullPointerException:: if qname is null
IllegalArgumentException:: if name is not already a variable.

public Interface XPathExpression<T>

Method Summary

Method Detail