Class AbstractXPathCompiled<T>
- Type Parameters:
T
- The generic type of the returned values.
- All Implemented Interfaces:
Cloneable
,XPathExpression<T>
super.clone();
- Author:
- Rolf Lear
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionclone()
Subclasses of this AbstractXPathCompile class must call super.clone() in their clone methods!Evaluate the XPath query against the supplied context, but return additional data which may be useful for diagnosing problems with XPath queries.Process the compiled XPathExpression against the specified context.evaluateFirst
(Object context) Return the first value in the XPath query result set type-cast to the return type of this XPathExpression.protected abstract List<?>
evaluateRawAll
(Object context) This is the raw expression evaluator to be implemented by the back-end XPath library.protected abstract Object
evaluateRawFirst
(Object context) This is the raw expression evaluator to be implemented by the back-end XPath library.final String
Get the XPath expressionGet theFilter<T>
used to coerce the raw XPath results in to the correct Generic type.final Namespace
getNamespace
(String prefix) Get the Namespace associated with a given prefix.Get the Namespaces that were used to compile this XPathExpression.getVariable
(String qname) Get the variable value associated to the given variable qname.final Object
getVariable
(String name, Namespace uri) Get the variable value associated to the given variable name.utility method that allows descendant classes to access the variables that were set on this expression, in a format that can be used in a constructor (qname/value).setVariable
(String qname, Object value) Change the defined value for a variable to some new value.setVariable
(String name, Namespace uri, Object value) Change the defined value for a variable to some new value.toString()
-
Constructor Details
-
AbstractXPathCompiled
public AbstractXPathCompiled(String query, Filter<T> filter, Map<String, Object> variables, Namespace[] namespaces) Construct an XPathExpression.- Parameters:
query
- The XPath queryfilter
- The coercion filter.variables
- A map of variables.namespaces
- The namespaces referenced from the query.- See Also:
-
-
Method Details
-
clone
Subclasses of this AbstractXPathCompile class must call super.clone() in their clone methods!This would be a sample clone method from a subclass:
Here's the documentation frompublic XPathExpression<T> clone() { @SuppressWarnings("unchecked") final MyXPathCompiled<T> ret = (MyXPathCompiled<T>)super.clone(); // change any fields that need to be cloned. .... return ret; }
XPathExpression.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.
- Specified by:
clone
in interfaceXPathExpression<T>
- Overrides:
clone
in classObject
- Returns:
- a new XPathExpression instance that shares the same core details as this.
-
getExpression
Description copied from interface:XPathExpression
Get the XPath expression- Specified by:
getExpression
in interfaceXPathExpression<T>
- Returns:
- the string representation of the XPath expression
-
getNamespace
Description copied from interface:XPathExpression
Get the Namespace associated with a given prefix.- Specified by:
getNamespace
in interfaceXPathExpression<T>
- Parameters:
prefix
- The prefix to select the Namespace URI for.- Returns:
- the URI of the specified Namespace prefix
-
getNamespaces
Description copied from interface:XPathExpression
Get the Namespaces that were used to compile this XPathExpression.- Specified by:
getNamespaces
in interfaceXPathExpression<T>
- Returns:
- a potentially empty array of Namespaces (never null).
-
getVariable
Description copied from interface:XPathExpression
Get the variable value associated to the given variable name.- Specified by:
getVariable
in interfaceXPathExpression<T>
- Parameters:
name
- the variable localname to retrieve the value for.uri
- the Namespace in which the variable name was declared.- Returns:
- the value associated to a Variable name.
-
getVariable
Description copied from interface:XPathExpression
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- Specified by:
getVariable
in interfaceXPathExpression<T>
- Parameters:
qname
- the variable qname to retrieve the value for.- Returns:
- the value associated to a Variable name.
-
setVariable
Description copied from interface:XPathExpression
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.
- Specified by:
setVariable
in interfaceXPathExpression<T>
- Parameters:
name
- The variable localname to change.uri
- the Namespace in which the variable name is declared.value
- The new value to set.- Returns:
- The value of the variable prior to this change.
-
setVariable
Description copied from interface:XPathExpression
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- Specified by:
setVariable
in interfaceXPathExpression<T>
- Parameters:
qname
- The variable qname to change.value
- The new value to set.- Returns:
- The value of the variable prior to this change.
-
getVariables
utility method that allows descendant classes to access the variables that were set on this expression, in a format that can be used in a constructor (qname/value).- Returns:
- the variables set on this instance.
-
getFilter
Description copied from interface:XPathExpression
Get theFilter<T>
used to coerce the raw XPath results in to the correct Generic type.- Specified by:
getFilter
in interfaceXPathExpression<T>
- Returns:
- the
Filter<T>
used to coerce the raw XPath results in to the correct Generic type.
-
evaluate
Description copied from interface:XPathExpression
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 theXPathExpression.diagnose(Object, boolean)
method to have access to both the raw XPath results as well as the filtered and generically typed results.- Specified by:
evaluate
in interfaceXPathExpression<T>
- Parameters:
context
- The context against which to process the query.- Returns:
- a list of the XPath results.
-
evaluateFirst
Description copied from interface:XPathExpression
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.
- Specified by:
evaluateFirst
in interfaceXPathExpression<T>
- Parameters:
context
- The context against which to evaluate the expression. This will typically be a Document, Element, or some other JDOM object.- Returns:
- The first XPath result (if there is any) coerced to the generic type of this XPathExpression, or null if it cannot be coerced.
-
diagnose
Description copied from interface:XPathExpression
Evaluate the XPath query against the supplied context, but return additional data which may be useful for diagnosing problems with XPath queries.- Specified by:
diagnose
in interfaceXPathExpression<T>
- Parameters:
context
- The context against which to run the query.firstonly
- Indicate whether the XPath expression can be terminated after the first successful result value.- Returns:
- an
XPathDiagnostic
instance.
-
toString
-
evaluateRawAll
This is the raw expression evaluator to be implemented by the back-end XPath library.- Parameters:
context
- The context against which to evaluate the query- Returns:
- A list of XPath results.
-
evaluateRawFirst
This is the raw expression evaluator to be implemented by the back-end XPath library. When this method is processed the implementing library is free to stop processing when the result that would be the first result is retrieved.Only the first value in the result will be processed (if any).
- Parameters:
context
- The context against which to evaluate the query- Returns:
- The first item in the XPath results, or null if there are no results.
-