@@ -84,9 +84,9 @@
* An XPath expression is not thread-safe and not reentrant.
* In other words, it is the application's responsibility to make
* sure that one {@link XPathExpression} object is not used from
- * more than one thread at any given time, and while the evaluate
+ * more than one thread at any given time, and while the {@code evaluate}
* method is invoked, applications may not recursively call
- * the evaluate method.
+ * the {@code evaluate} method.
*
*
* @author Norman Walsh
@@ -96,6 +96,7 @@
*/
public interface XPathExpression {
+
/**
*
Evaluate the compiled XPath expression in the specified context and return the result as the specified type.
*
@@ -102,45 +103,50 @@
* See Evaluation of XPath Expressions for context item evaluation,
* variable, function and QName resolution and return type conversion.
*
- * If returnType is not one of the types defined in {@link XPathConstants},
- * then an IllegalArgumentException is thrown.
+ *
+ * The parameter {@code item} represents the context the XPath expression
+ * will be operated on. The type of the context is implementation-dependent.
+ * If the value is {@code null}, the operation must have no dependency on
+ * the context, otherwise an XPathExpressionException will be thrown.
*
- *
If a null value is provided for
- * item, an empty document will be used for the
- * context.
- * If returnType is null, then a NullPointerException is thrown.
+ * @implNote
+ * The type of the context is usually {@link org.w3c.dom.Node}.
*
- * @param item The starting context (a node, for example).
- * @param returnType The desired return type.
+ * @param item The context the XPath expression will be evaluated in.
+ * @param returnType The result type expected to be returned by the XPath expression.
*
- * @return The Object that is the result of evaluating the expression and converting the result to
- * returnType.
+ * @return The {@code Object} that is the result of evaluating the expression and converting the result to
+ * {@code returnType}.
*
* @throws XPathExpressionException If the expression cannot be evaluated.
- * @throws IllegalArgumentException If returnType is not one of the types defined in {@link XPathConstants}.
- * @throws NullPointerException If returnType is null.
+ * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}.
+ * @throws NullPointerException If {@code returnType} is {@code null}.
*/
public Object evaluate(Object item, QName returnType)
throws XPathExpressionException;
/**
- * Evaluate the compiled XPath expression in the specified context and return the result as a String.
+ * Evaluate the compiled XPath expression in the specified context and return the result as a {@code String}.
*
- * This method calls {@link #evaluate(Object item, QName returnType)} with a returnType of
+ *
This method calls {@link #evaluate(Object item, QName returnType)} with a {@code returnType} of
* {@link XPathConstants#STRING}.
*
* See Evaluation of XPath Expressions for context item evaluation,
* variable, function and QName resolution and return type conversion.
*
- * If a null value is provided for
- * item, an empty document will be used for the
- * context.
+ *
+ * The parameter {@code item} represents the context the XPath expression
+ * will be operated on. The type of the context is implementation-dependent.
+ * If the value is {@code null}, the operation must have no dependency on
+ * the context, otherwise an XPathExpressionException will be thrown.
*
- * @param item The starting context (a node, for example).
+ * @implNote
+ * The type of the context is usually {@link org.w3c.dom.Node}.
*
- * @return The String that is the result of evaluating the expression and converting the result to a
- * String.
+ * @param item The context the XPath expression will be evaluated in.
*
+ * @return The result of evaluating an XPath expression as a {@code String}.
+ *
* @throws XPathExpressionException If the expression cannot be evaluated.
*/
public String evaluate(Object item)
@@ -147,7 +153,7 @@
throws XPathExpressionException;
/**
- *
Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as the
+ *
Evaluate the compiled XPath expression in the context of the specified {@code InputSource} and return the result as the
* specified type.
*
* This method builds a data model for the {@link InputSource} and calls
@@ -156,45 +162,225 @@
*
See Evaluation of XPath Expressions for context item evaluation,
* variable, function and QName resolution and return type conversion.
*
- * If returnType is not one of the types defined in {@link XPathConstants},
- * then an IllegalArgumentException is thrown.
+ * If {@code returnType} is not one of the types defined in {@link XPathConstants},
+ * then an {@code IllegalArgumentException} is thrown.
*
- * If source or returnType is null,
- * then a NullPointerException is thrown.
+ * If {@code source} or {@code returnType} is {@code null},
+ * then a {@code NullPointerException} is thrown.
*
- * @param source The InputSource of the document to evaluate over.
+ * @param source The {@code InputSource} of the document to evaluate over.
* @param returnType The desired return type.
*
- * @return The Object that is the result of evaluating the expression and converting the result to
- * returnType.
+ * @return The {@code Object} that is the result of evaluating the expression and converting the result to
+ * {@code returnType}.
*
* @throws XPathExpressionException If the expression cannot be evaluated.
- * @throws IllegalArgumentException If returnType is not one of the types defined in {@link XPathConstants}.
- * @throws NullPointerException If source or returnType is null.
+ * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}.
+ * @throws NullPointerException If {@code source or returnType} is {@code null}.
*/
public Object evaluate(InputSource source, QName returnType)
throws XPathExpressionException;
/**
- * Evaluate the compiled XPath expression in the context of the specified InputSource and return the result as a
- * String.
+ * Evaluate the compiled XPath expression in the context of the specified {@code InputSource} and return the result as a
+ * {@code String}.
*
- * This method calls {@link #evaluate(InputSource source, QName returnType)} with a returnType of
+ *
This method calls {@link #evaluate(InputSource source, QName returnType)} with a {@code returnType} of
* {@link XPathConstants#STRING}.
*
* See Evaluation of XPath Expressions for context item evaluation,
* variable, function and QName resolution and return type conversion.
*
- * If source is null, then a NullPointerException is thrown.
+ * If {@code source} is {@code null}, then a {@code NullPointerException} is thrown.
*
- * @param source The InputSource of the document to evaluate over.
+ * @param source The {@code InputSource} of the document to evaluate over.
*
- * @return The String that is the result of evaluating the expression and converting the result to a
- * String.
+ * @return The {@code String} that is the result of evaluating the expression and converting the result to a
+ * {@code String}.
*
* @throws XPathExpressionException If the expression cannot be evaluated.
- * @throws NullPointerException If source is null.
+ * @throws NullPointerException If {@code source} is {@code null}.
*/
public String evaluate(InputSource source)
throws XPathExpressionException;
+
+ /**
+ * Evaluate the compiled XPath expression in the specified context, and return
+ * the result with the type specified through the {@code class type}.
+ *
+ *
+ * The parameter {@code item} represents the context the XPath expression
+ * will be operated on. The type of the context is implementation-dependent.
+ * If the value is {@code null}, the operation must have no dependency on
+ * the context, otherwise an XPathExpressionException will be thrown.
+ *
+ * @implNote
+ * The type of the context is usually {@link org.w3c.dom.Node}.
+ *
+ * @implSpec
+ * The default implementation in the XPath API is equivalent to:
+ *
{@code
+ * (T)evaluate(item, XPathEvaluationResult.XPathResultType.getQNameType(type));
+ * }
+ *
+ * Since the {@code evaluate} method does not support the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying
+ * XPathEvaluationResult as the type will result in IllegalArgumentException.
+ * Any implementation supporting the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override
+ * this method.
+ *
+ * @param The class type that will be returned by the XPath expression.
+ * @param item The context the XPath expression will be evaluated in.
+ * @param type The class type expected to be returned by the XPath expression.
+ *
+ * @return The result of evaluating the expression.
+ *
+ * @throws XPathExpressionException If the expression cannot be evaluated.
+ * @throws IllegalArgumentException If {@code type} is not of the types
+ * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType
+ * XPathResultType}, or XPathEvaluationResult is specified as the type but an
+ * implementation supporting the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type is not available.
+ * @throws NullPointerException If {@code type} is {@code null}.
+ *
+ * @since 1.9
+ */
+ default T evaluateExpression(Object item, Class type)
+ throws XPathExpressionException
+ {
+ return type.cast(evaluate(item, XPathEvaluationResult.XPathResultType.getQNameType(type)));
+ }
+
+ /**
+ * Evaluate the compiled XPath expression in the specified context. This is
+ * equivalent to calling {@link #evaluateExpression(Object item, Class type)}
+ * with type {@link XPathEvaluationResult}:
+ * {@code
+ * evaluateExpression(item, XPathEvaluationResult.class);
+ * }
+ *
+ * The parameter {@code item} represents the context the XPath expression
+ * will be operated on. The type of the context is implementation-dependent.
+ * If the value is {@code null}, the operation must have no dependency on
+ * the context, otherwise an XPathExpressionException will be thrown.
+ *
+ * @implNote
+ * The type of the context is usually {@link org.w3c.dom.Node}.
+ *
+ * @implSpec
+ * The default implementation in the XPath API is equivalent to:
+ *
{@code
+ * evaluateExpression(item, XPathEvaluationResult.class);
+ * }
+ *
+ * Since the {@code evaluate} method does not support the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY}
+ * type, the default implementation of this method will always throw an
+ * IllegalArgumentException. Any implementation supporting the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore
+ * override this method.
+ *
+ * @param item The context the XPath expression will be evaluated in.
+ *
+ * @return The result of evaluating the expression.
+ *
+ * @throws XPathExpressionException If the expression cannot be evaluated.
+ * @throws IllegalArgumentException If the implementation of this method
+ * does not support the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type.
+ *
+ * @since 1.9
+ */
+ default XPathEvaluationResult evaluateExpression(Object item)
+ throws XPathExpressionException
+ {
+ return evaluateExpression(item, XPathEvaluationResult.class);
+ }
+
+ /**
+ * Evaluate the compiled XPath expression in the specified context,
+ * and return the result with the type specified through the {@code class type}
+ *
+ * This method builds a data model for the {@link InputSource} and calls
+ * {@link #evaluateExpression(Object item, Class type)} on the resulting
+ * document object.
+ *
+ * By default, the JDK's data model is {@link org.w3c.dom.Document}.
+ *
+ * @implSpec
+ * The default implementation in the XPath API is equivalent to:
+ *
{@code
+ (T)evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type));
+ * }
+ *
+ * Since the {@code evaluate} method does not support the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying
+ * XPathEvaluationResult as the type will result in IllegalArgumentException.
+ * Any implementation supporting the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override
+ * this method.
+ *
+ * @param The class type that will be returned by the XPath expression.
+ * @param source The {@code InputSource} of the document to evaluate over.
+ * @param type The class type expected to be returned by the XPath expression.
+ *
+ * @return The result of evaluating the expression.
+ *
+ * @throws XPathExpressionException If the expression cannot be evaluated.
+ * @throws IllegalArgumentException If {@code type} is not of the types
+ * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType
+ * XPathResultType}, or XPathEvaluationResult is specified as the type but an
+ * implementation supporting the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type
+ * is not available.
+ * @throws NullPointerException If {@code source or type} is {@code null}.
+ *
+ * @since 1.9
+ */
+ default T evaluateExpression(InputSource source, Class type)
+ throws XPathExpressionException
+ {
+ return type.cast(evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type)));
+ }
+
+ /**
+ * Evaluate the compiled XPath expression in the specified context. This is
+ * equivalent to calling {@link #evaluateExpression(InputSource source, Class type)}
+ * with type {@link XPathEvaluationResult}:
+ * {@code
+ * evaluateExpression(source, XPathEvaluationResult.class);
+ * }
+ *
+ *
+ * @implSpec
+ * The default implementation in the XPath API is equivalent to:
+ *
{@code
+ * (XPathEvaluationResult)evaluateExpression(source, XPathEvaluationResult.class);
+ * }
+ *
+ * Since the {@code evaluate} method does not support the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY}
+ * type, the default implementation of this method will always throw an
+ * IllegalArgumentException. Any implementation supporting the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore
+ * override this method.
+ *
+ * @param source The {@code InputSource} of the document to evaluate over.
+ *
+ * @return The result of evaluating the expression.
+ *
+ * @throws XPathExpressionException If the expression cannot be evaluated.
+ * @throws IllegalArgumentException If the implementation of this method
+ * does not support the
+ * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type.
+ * @throws NullPointerException If {@code source} is {@code null}.
+ *
+ * @since 1.9
+ */
+ default XPathEvaluationResult evaluateExpression(InputSource source)
+ throws XPathExpressionException
+ {
+ return evaluateExpression(source, XPathEvaluationResult.class);
+ }
}