public abstract class XPath extends Object implements Serializable
This class allows to express and evaluate generic XPath-like expressions on nodes of the data
model. An XPath
expression can be created in three ways:
parse(String, Object...)
and parse(Map, String, Object...)
,
which parse an XPath
string, possibly using a map of namespace declarations replacing
supplied values to optional $$ placeholders in the string;constant(Object...)
that produces the XPath
expression
returning a supplied constant value or sequence of values;compose(String, Object...)
that composes multiple XPath
or
scalar sequence operands using a supplied operator.XPath
object,
accessible via toString()
, getHead()
and getBody()
. The syntax of
the expression string is reported in the package documentation. ### TODO ###
Evaluation of an XPath
expression is performed via a number of eval
methods
that all accept an object as input but differ in their output and additional arguments:
eval(Object)
and eval(Object, Class)
return a list result consisting
either of objects of the data model or of objects obtained from their conversion to a specific
type T
;evalUnique(Object)
and evalUnique(Object, Class)
return a unique result
consisting either in a generic object or an object converted to a specific type; their outcome
is null if the evaluation produced no result, while an IllegalArgumentException
is
thrown if multiple results are produced;evalBoolean(Object)
return a boolean result.
Note that the evaluation may fail for a specific input object for a number of reasons, e.g.,
because it performs some arithmetic operation on data that is of an incompatible type. Failure
is reported by throwing an IllegalArgumentException
if the XPath
expression is
not lenient (see isLenient()
), or by returning a default value otherwise (respectively
an empty list, null or false for the three classes of eval()
methods). An XPath
expression is created not-lenient by default, but a lenient version of it can be obtained by
calling method lenient(boolean)
.
Apart from evaluation, it is possible to query an XPath
object for the set of
properties accessed by the expression, using method getProperties()
, and for the
prefix-to-namespace mappings referenced by the expression string. Methods
asPredicate()
, asFunction(Class)
and asFunctionUnique(Class)
generate respectively a Predicate
, single-valued and multi-valued Function
view
of an XPath
expression, thus supporting interoperability with the utility classes and
methods of the Guava library. Another method decompose(Map)
attempts to decompose a
boolean XPath
expression into a conjunction of property restrictions of the form
property in rangeset
plus an optional remaining XPath
expression, where
rangesets
are scalar sets of Range
s s (e.g., (-1, 5], (6, 9)). This kind of
decomposition allows to extract simple restrictions on individual properties that can be
efficiently evaluated using indexes.
XPath
objects are immutable and thread safe. Methods equals(Object)
and
hashCode()
are based exclusively on the expression string (accessible via
toString()
) and on the lenient mode of the XPath
object.
Modifier and Type | Method and Description |
---|---|
<T> Function<Object,List<T>> |
asFunction(Class<T> resultClass)
Returns a function view of this
XPath expression that produces a List<T>
result given an input object. |
<T> Function<Object,T> |
asFunctionUnique(Class<T> resultClass)
Returns a function view of this
XPath expression that produces a unique T
result given an input object. |
Predicate<Object> |
asPredicate()
Returns a predicate view of this
XPath expression that accept an object input. |
static XPath |
compose(String operator,
Object... operands)
Creates an
XPath expression by composing a number operands with the operator
specified. |
static XPath |
constant(Object... values)
Creates an
XPath expression returning a sequence with the constant value(s)
specified. |
XPath |
decompose(Map<org.openrdf.model.URI,Set<Object>> restrictions)
Attempts at decomposing the
XPath expression into the conjunction of a number of
property restrictions and (optionally) a remaining XPath expression. |
boolean |
equals(Object object)
Two
XPath expressions are equal if they have the same string and
lenient mode. |
List<Object> |
eval(Object object)
Evaluates this
XPath expression on the object supplied, producing as result a list
of objects. |
<T> List<T> |
eval(Object object,
Class<T> resultClass)
Evaluates this
XPath expression on the object supplied, producing as result a list
of objects of the type T specified. |
boolean |
evalBoolean(Object object)
Evaluates this
XPath expression on the object supplied, producing a boolean value
as result. |
Object |
evalUnique(Object object)
Evaluates this
XPath expression on the object supplied, producing as result a
unique object. |
<T> T |
evalUnique(Object object,
Class<T> resultClass)
Evaluates this
XPath expression on the object supplied, producing as result a
unique object of the type T specified. |
String |
getBody()
Returns the body of the
XPath expression, i.e., the XPath string without
the WITH clause. |
String |
getHead()
Returns the head of the
XPath expression, i.e., the content of the WITH
clause. |
Map<String,String> |
getNamespaces()
Returns the namespace declarations referenced by this
XPath expression. |
Set<org.openrdf.model.URI> |
getProperties()
Returns the properties referenced by this
XPath expression. |
int |
hashCode()
The returned hash code is based exclusively on the string and lenient mode of
this
XPath expression. |
abstract boolean |
isLenient()
Returns true if this
XPath expression is lenient, i.e., evaluation never throws
exceptions. |
XPath |
lenient(boolean lenient)
Returns a lenient / not lenient version of this
XPath expression. |
static XPath |
parse(Map<String,String> namespaces,
String expression,
Object... values)
Creates a new
XPath expression based on the namespace mappings and the expression
string specified, with optional $$ placeholders replaced by supplied values. |
static XPath |
parse(String string,
Object... values)
Creates a new
XPath expression based on the expression string specified with
optional $$ placeholders replaced by supplied values. |
String |
toString()
The method returns the
XPath string. |
static String |
toString(Object... values)
Returns the
XPath string corresponding to the sequence of values specified. |
static Object |
unwrap(Object object) |
public static XPath constant(Object... values)
XPath
expression returning a sequence with the constant value(s)
specified. Values must be scalars, arrays or iterables; the latter two are recursively
exploded and their elements added to the sequence produced by the returned XPath
expression.values
- the valuesXPath
expression@Nullable public static XPath compose(String operator, Object... operands) throws IllegalArgumentException
XPath
expression by composing a number operands with the operator
specified. Operands can be either XPath
expressions, scalars, arrays or iterables
of scalars. Supported operators are not
, and
, or
, =
,
!=
, <
, >
, <=
, >=
, +
, -
, *
,
mod
, div
, |
.operator
- the operatoroperands
- the operandsXPath
expression, or null if no operand was suppliedIllegalArgumentException
- in case multiple XPath
expressions using incompatible namespaces are
composed.public static XPath parse(String string, Object... values) throws ParseException
XPath
expression based on the expression string specified with
optional $$ placeholders replaced by supplied values. Note that i-th placeholder
is replaced with i-th value of the values
vararg array, while namespaces referenced
in the string must be defined in the WITH
clause of the string itself.string
- the expression stringvalues
- the values for optional placeholders appearing in string
XPath
expression object, on successParseException
- if the expression string supplied is not syntactically correct, or if it
references a namespace not defined in the string itself or in common
(prefix.cc) namespacespublic static XPath parse(Map<String,String> namespaces, String expression, Object... values) throws ParseException
XPath
expression based on the namespace mappings and the expression
string specified, with optional $$ placeholders replaced by supplied values. Note
that i-th placeholder is replaced with i-th value of the values
vararg array, while
namespaces occurring in the string can be defined either in the WITH
clause of the
string or in the supplied namespace Map
.namespaces
- the namespace mapexpression
- the expression stringvalues
- the values for optional placeholders appearing in string
XPath
expression object, on successParseException
- if the expression string supplied is not syntactically correct, or if it
references a namespace not defined in the string itself or in the supplied
namespace mappublic final String getHead()
XPath
expression, i.e., the content of the WITH
clause. An empty string is returned in case the with clause is not used.public final String getBody()
XPath
expression, i.e., the XPath
string without
the WITH
clause.public final Map<String,String> getNamespaces()
XPath
expression.prefix - namespace URI
mappingspublic final Set<org.openrdf.model.URI> getProperties()
XPath
expression. Note that this method
returns only the properties accessed on the root record the condition is evaluated
on, ignoring properties of nested records that can be reached via property traversal
starting from the root record.public abstract boolean isLenient()
XPath
expression is lenient, i.e., evaluation never throws
exceptions. XPath
expressions are non-lenient by default; a lenient version of an
expression can be obtained by calling method lenient(boolean)
.public final XPath lenient(boolean lenient)
XPath
expression.lenient
- the requested lenient modeXPath
expression with the same xpath string of this expression but the
requested lenient mode; note that this XPath
instance is returned in case
the requested lenient mode matches the mode of this expressionpublic final Predicate<Object> asPredicate()
XPath
expression that accept an object input. If
this XPath
is lenient, evaluation of the predicate will return false on failure,
rather than throwing an IllegalArgumentException
.public final <T> Function<Object,List<T>> asFunction(Class<T> resultClass)
XPath
expression that produces a List<T>
result given an input object. If this XPath
is lenient, evaluation of the function
will return an empty list on failure, rather than throwing an
IllegalArgumentException
.T
- the type of result list elementresultClass
- the Class
object for the list elements of the expected function resultpublic final <T> Function<Object,T> asFunctionUnique(Class<T> resultClass)
XPath
expression that produces a unique T
result given an input object. If this XPath
is lenient, evaluation of the function
will return null on failure, rather than throwing an IllegalArgumentException
.T
- the type of resultresultClass
- the Class
object for the expected function resultpublic final List<Object> eval(Object object) throws IllegalArgumentException
XPath
expression on the object supplied, producing as result a list
of objects.object
- the object to evaluate this expression onIllegalArgumentException
- if this XPath
expression is not lenient and evaluation fails for the
object suppliedpublic final <T> List<T> eval(Object object, Class<T> resultClass) throws IllegalArgumentException
XPath
expression on the object supplied, producing as result a list
of objects of the type T
specified.T
- the type of element of the result listobject
- the object to evaluate this expression onresultClass
- the Class
object for the elements of the result listIllegalArgumentException
- if this XPath
expression is not lenient and evaluation fails for the
object supplied@Nullable public final Object evalUnique(Object object) throws IllegalArgumentException
XPath
expression on the object supplied, producing as result a
unique object.object
- the object to evaluate this expression onXPath
expression
is lenientIllegalArgumentException
- if this XPath
expression is not lenient and evaluation fails for the
object supplied@Nullable public final <T> T evalUnique(Object object, Class<T> resultClass) throws IllegalArgumentException
XPath
expression on the object supplied, producing as result a
unique object of the type T
specified.T
- the type of resultobject
- the object to evaluate this expression onresultClass
- the Class
object for the result objectXPath
expression is lenientIllegalArgumentException
- if this XPath
expression is not lenient and evaluation fails for the
object suppliedpublic final boolean evalBoolean(Object object) throws IllegalArgumentException
XPath
expression on the object supplied, producing a boolean value
as result.object
- the object to evaluate this expression onXPath
expression is lenientIllegalArgumentException
- if this XPath
expression is not lenient and evaluation fails for the
object supplied@Nullable public final XPath decompose(Map<org.openrdf.model.URI,Set<Object>> restrictions)
XPath
expression into the conjunction of a number of
property restrictions and (optionally) a remaining XPath
expression. More in
details, the method tries to transform the condition in the following form:
p1 in restriction1 AND ... AND pN in restrictionN AND remainingXPath
, where
p1 ... pN
are property URIs, restriction1 ... restrictionN
are sets of
scalar values or scalar Range
s (e.g., (1, 5], [7, 9]
)), whose union should
be taken, and remainingXPath
contains all the clauses of the original XPath
that cannot be decomposed in property restrictions.restrictions
- a modifiable map where to store the property in restriction
restrictionsXPath
expression, if any, or null if it was possible to
completely express this expression as a conjunction of property restrictionspublic final boolean equals(Object object)
XPath
expressions are equal if they have the same string and
lenient mode.public final int hashCode()
XPath
expression.public final String toString()
XPath
string. Note this is not the string
originally supplied, but a string obtained from it during the validation step with a
WITH
clause that contains all the namespace declarations necessary to make this
expression independent from external mappings.public static String toString(Object... values)
XPath
string corresponding to the sequence of values specified. This
utility method can be used when programmatically composing an XPath
string.values
- the values to formatXPath
stringCopyright © 2015–2016 FBK-irst. All rights reserved.