1 /*
   2  * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.xpath;
  27 

  28 import javax.xml.namespace.QName;
  29 import org.xml.sax.InputSource;
  30 
  31 /**
  32  * <p>{@code XPathExpression} provides access to compiled XPath expressions.</p>
  33  *
  34  * <a name="XPathExpression-evaluation"/>
  35  * <table border="1" cellpadding="2">
  36  *   <thead>
  37  *     <tr>
  38  *       <th colspan="2">Evaluation of XPath Expressions.</th>
  39  *     </tr>
  40  *   </thead>
  41  *   <tbody>
  42  *     <tr>
  43  *       <td>context</td>
  44  *       <td>
  45  *         If a request is made to evaluate the expression in the absence
  46  * of a context item, an empty document node will be used for the context.
  47  * For the purposes of evaluating XPath expressions, a DocumentFragment
  48  * is treated like a Document node.
  49  *      </td>
  50  *    </tr>
  51  *    <tr>
  52  *      <td>variables</td>
  53  *      <td>
  54  *        If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}.
  55  *        An {@link XPathExpressionException} is raised if the variable resolver is undefined or
  56  *        the resolver returns {@code null} for the variable.
  57  *        The value of a variable must be immutable through the course of any single evaluation.</p>
  58  *      </td>
  59  *    </tr>
  60  *    <tr>
  61  *      <td>functions</td>
  62  *      <td>
  63  *        If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}.
  64  *        An {@link XPathExpressionException} is raised if the function resolver is undefined or
  65  *        the function resolver returns {@code null} for the function.</p>
  66  *      </td>
  67  *    </tr>
  68  *    <tr>
  69  *      <td>QNames</td>
  70  *      <td>
  71  *        QNames in the expression are resolved against the XPath namespace context.
  72  *      </td>
  73  *    </tr>
  74  *    <tr>
  75  *      <td>result</td>
  76  *      <td>
  77  *        This result of evaluating an expression is converted to an instance of the desired return type.
  78  *        Valid return types are defined in {@link XPathConstants}.
  79  *        Conversion to the return type follows XPath conversion rules.</p>
  80  *      </td>
  81  *    </tr>
  82  * </table>
  83  *
  84  * <p>An XPath expression is not thread-safe and not reentrant.
  85  * In other words, it is the application's responsibility to make
  86  * sure that one {@link XPathExpression} object is not used from
  87  * more than one thread at any given time, and while the {@code evaluate}
  88  * method is invoked, applications may not recursively call
  89  * the {@code evaluate} method.
  90  * <p>
  91  *
  92  * @author  <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
  93  * @author  <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
  94  * @see <a href="http://www.w3.org/TR/xpath#section-Expressions">XML Path Language (XPath) Version 1.0, Expressions</a>
  95  * @since 1.5
  96  */
  97 public interface XPathExpression {
  98 
  99 
 100     /**
 101      * <p>Evaluate the compiled XPath expression in the specified context and return the result as the specified type.</p>
 102      *
 103      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
 104      * variable, function and QName resolution and return type conversion.</p>
 105      *
 106      * <p>
 107      * The parameter {@code item} represents the context the XPath expression
 108      * will be operated on. The type of the context is implementation-dependent.
 109      * If the value is {@code null}, the operation must have no dependency on
 110      * the context, otherwise an XPathExpressionException will be thrown.
 111      *
 112      * @implNote
 113      * The type of the context is usually {@link org.w3c.dom.Node}.


 114      *
 115      * @param item The context the XPath expression will be evaluated in.
 116      * @param returnType The result type expected to be returned by the XPath expression.
 117      *
 118      * @return The {@code Object} that is the result of evaluating the expression and converting the result to
 119      *   {@code returnType}.
 120      *
 121      * @throws XPathExpressionException If the expression cannot be evaluated.
 122      * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}.
 123      * @throws NullPointerException If {@code returnType} is {@code null}.
 124      */
 125     public Object evaluate(Object item, QName returnType)
 126         throws XPathExpressionException;
 127 
 128     /**
 129      * <p>Evaluate the compiled XPath expression in the specified context and return the result as a {@code String}.</p>
 130      *
 131      * <p>This method calls {@link #evaluate(Object item, QName returnType)} with a {@code returnType} of
 132      * {@link XPathConstants#STRING}.</p>
 133      *
 134      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
 135      * variable, function and QName resolution and return type conversion.</p>
 136      *
 137      * <p>
 138      * The parameter {@code item} represents the context the XPath expression
 139      * will be operated on. The type of the context is implementation-dependent.
 140      * If the value is {@code null}, the operation must have no dependency on
 141      * the context, otherwise an XPathExpressionException will be thrown.
 142      *
 143      * @implNote
 144      * The type of the context is usually {@link org.w3c.dom.Node}.
 145      *
 146      * @param item The context the XPath expression will be evaluated in.

 147      *
 148      * @return The result of evaluating an XPath expression as a {@code String}.
 149      *
 150      * @throws XPathExpressionException If the expression cannot be evaluated.
 151      */
 152     public String evaluate(Object item)
 153         throws XPathExpressionException;
 154 
 155     /**
 156      * <p>Evaluate the compiled XPath expression in the context of the specified {@code InputSource} and return the result as the
 157      * specified type.</p>
 158      *
 159      * <p>This method builds a data model for the {@link InputSource} and calls
 160      * {@link #evaluate(Object item, QName returnType)} on the resulting document object.</p>
 161      *
 162      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
 163      * variable, function and QName resolution and return type conversion.</p>
 164      *
 165      * <p>If {@code returnType} is not one of the types defined in {@link XPathConstants},
 166      * then an {@code IllegalArgumentException} is thrown.</p>
 167      *
 168      * <p>If {@code source} or {@code returnType} is {@code null},
 169      * then a {@code NullPointerException} is thrown.</p>
 170      *
 171      * @param source The {@code InputSource} of the document to evaluate over.
 172      * @param returnType The desired return type.
 173      *
 174      * @return The {@code Object} that is the result of evaluating the expression and converting the result to
 175      *   {@code returnType}.
 176      *
 177      * @throws XPathExpressionException If the expression cannot be evaluated.
 178      * @throws IllegalArgumentException If {@code returnType} is not one of the types defined in {@link XPathConstants}.
 179      * @throws NullPointerException If {@code source or returnType} is {@code null}.
 180      */
 181     public Object evaluate(InputSource source, QName returnType)
 182         throws XPathExpressionException;
 183 
 184     /**
 185      * <p>Evaluate the compiled XPath expression in the context of the specified {@code InputSource} and return the result as a
 186      * {@code String}.</p>
 187      *
 188      * <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a {@code returnType} of
 189      * {@link XPathConstants#STRING}.</p>
 190      *
 191      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
 192      * variable, function and QName resolution and return type conversion.</p>
 193      *
 194      * <p>If {@code source} is {@code null}, then a {@code NullPointerException} is thrown.</p>
 195      *
 196      * @param source The {@code InputSource} of the document to evaluate over.
 197      *
 198      * @return The {@code String} that is the result of evaluating the expression and converting the result to a
 199      *   {@code String}.
 200      *
 201      * @throws XPathExpressionException If the expression cannot be evaluated.
 202      * @throws NullPointerException If {@code source} is {@code null}.
 203      */
 204     public String evaluate(InputSource source)
 205         throws XPathExpressionException;
 206 
 207     /**
 208      * Evaluate the compiled XPath expression in the specified context, and return
 209      * the result with the type specified through the {@code class type}.
 210      *
 211      * <p>
 212      * The parameter {@code item} represents the context the XPath expression
 213      * will be operated on. The type of the context is implementation-dependent.
 214      * If the value is {@code null}, the operation must have no dependency on
 215      * the context, otherwise an XPathExpressionException will be thrown.
 216      *
 217      * @implNote
 218      * The type of the context is usually {@link org.w3c.dom.Node}.
 219      *
 220      * @implSpec
 221      * The default implementation in the XPath API is equivalent to:
 222      * <pre> {@code
 223      *     (T)evaluate(item, XPathEvaluationResult.XPathResultType.getQNameType(type));
 224      * }</pre>
 225      *
 226      * Since the {@code evaluate} method does not support the
 227      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying
 228      * XPathEvaluationResult as the type will result in IllegalArgumentException.
 229      * Any implementation supporting the
 230      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override
 231      * this method.
 232      *
 233      * @param <T> The class type that will be returned by the XPath expression.
 234      * @param item The context the XPath expression will be evaluated in.
 235      * @param type The class type expected to be returned by the XPath expression.
 236      *
 237      * @return The result of evaluating the expression.
 238      *
 239      * @throws XPathExpressionException If the expression cannot be evaluated.
 240      * @throws IllegalArgumentException If {@code type} is not of the types
 241      * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType
 242      * XPathResultType}, or XPathEvaluationResult is specified as the type but an
 243      * implementation supporting the
 244      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type is not available.
 245      * @throws NullPointerException If {@code type} is {@code null}.
 246      *
 247      * @since 1.9
 248      */
 249     default <T>T evaluateExpression(Object item, Class<T> type)
 250         throws XPathExpressionException
 251     {
 252         return type.cast(evaluate(item, XPathEvaluationResult.XPathResultType.getQNameType(type)));
 253     }
 254 
 255     /**
 256      * Evaluate the compiled XPath expression in the specified context. This is
 257      * equivalent to calling {@link #evaluateExpression(Object item, Class type)}
 258      * with type {@link XPathEvaluationResult}:
 259      * <pre> {@code
 260      *     evaluateExpression(item, XPathEvaluationResult.class);
 261      * }</pre>
 262      * <p>
 263      * The parameter {@code item} represents the context the XPath expression
 264      * will be operated on. The type of the context is implementation-dependent.
 265      * If the value is {@code null}, the operation must have no dependency on
 266      * the context, otherwise an XPathExpressionException will be thrown.
 267      *
 268      * @implNote
 269      * The type of the context is usually {@link org.w3c.dom.Node}.
 270      *
 271      * @implSpec
 272      * The default implementation in the XPath API is equivalent to:
 273      * <pre> {@code
 274      *     evaluateExpression(item, XPathEvaluationResult.class);
 275      * }</pre>
 276      *
 277      * Since the {@code evaluate} method does not support the
 278      * {@link XPathEvaluationResult.XPathResultType#ANY ANY}
 279      * type, the default implementation of this method will always throw an
 280      * IllegalArgumentException. Any implementation supporting the
 281      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore
 282      * override this method.
 283      *
 284      * @param item The context the XPath expression will be evaluated in.
 285      *
 286      * @return The result of evaluating the expression.
 287      *
 288      * @throws XPathExpressionException If the expression cannot be evaluated.
 289      * @throws IllegalArgumentException If the implementation of this method
 290      * does not support the
 291      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type.
 292      *
 293      * @since 1.9
 294      */
 295     default XPathEvaluationResult<?> evaluateExpression(Object item)
 296         throws XPathExpressionException
 297     {
 298         return evaluateExpression(item, XPathEvaluationResult.class);
 299     }
 300 
 301     /**
 302      * Evaluate the compiled XPath expression in the specified context,
 303      * and return the result with the type specified through the {@code class type}
 304      * <p>
 305      * This method builds a data model for the {@link InputSource} and calls
 306      * {@link #evaluateExpression(Object item, Class type)} on the resulting
 307      * document object.
 308      * <P>
 309      * By default, the JDK's data model is {@link org.w3c.dom.Document}.
 310      *
 311      * @implSpec
 312      * The default implementation in the XPath API is equivalent to:
 313      * <pre> {@code
 314            (T)evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type));
 315      * }</pre>
 316      *
 317      * Since the {@code evaluate} method does not support the
 318      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type, specifying
 319      * XPathEvaluationResult as the type will result in IllegalArgumentException.
 320      * Any implementation supporting the
 321      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must override
 322      * this method.
 323      *
 324      * @param <T> The class type that will be returned by the XPath expression.
 325      * @param source The {@code InputSource} of the document to evaluate over.
 326      * @param type The class type expected to be returned by the XPath expression.
 327      *
 328      * @return The result of evaluating the expression.
 329      *
 330      * @throws XPathExpressionException If the expression cannot be evaluated.
 331      * @throws IllegalArgumentException If {@code type} is not of the types
 332      * corresponding to the types defined in the {@link XPathEvaluationResult.XPathResultType
 333      * XPathResultType}, or XPathEvaluationResult is specified as the type but an
 334      * implementation supporting the
 335      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type
 336      * is not available.
 337      * @throws NullPointerException If {@code source or type} is {@code null}.
 338      *
 339      * @since 1.9
 340      */
 341     default <T>T evaluateExpression(InputSource source, Class<T> type)
 342         throws XPathExpressionException
 343     {
 344         return type.cast(evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type)));
 345     }
 346 
 347     /**
 348      * Evaluate the compiled XPath expression in the specified context. This is
 349      * equivalent to calling {@link #evaluateExpression(InputSource source, Class type)}
 350      * with type {@link XPathEvaluationResult}:
 351      * <pre> {@code
 352      *     evaluateExpression(source, XPathEvaluationResult.class);
 353      * }</pre>
 354      * <p>
 355      *
 356      * @implSpec
 357      * The default implementation in the XPath API is equivalent to:
 358      * <pre> {@code
 359      *     (XPathEvaluationResult)evaluateExpression(source, XPathEvaluationResult.class);
 360      * }</pre>
 361      *
 362      * Since the {@code evaluate} method does not support the
 363      * {@link XPathEvaluationResult.XPathResultType#ANY ANY}
 364      * type, the default implementation of this method will always throw an
 365      * IllegalArgumentException. Any implementation supporting the
 366      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type must therefore
 367      * override this method.
 368      *
 369      * @param source The {@code InputSource} of the document to evaluate over.
 370      *
 371      * @return The result of evaluating the expression.
 372      *
 373      * @throws XPathExpressionException If the expression cannot be evaluated.
 374      * @throws IllegalArgumentException If the implementation of this method
 375      * does not support the
 376      * {@link XPathEvaluationResult.XPathResultType#ANY ANY} type.
 377      * @throws NullPointerException If {@code source} is {@code null}.
 378      *
 379      * @since 1.9
 380      */
 381     default XPathEvaluationResult<?> evaluateExpression(InputSource source)
 382         throws XPathExpressionException
 383     {
 384         return evaluateExpression(source, XPathEvaluationResult.class);
 385     }
 386 }
--- EOF ---