1 /*
   2  * Copyright (c) 2003, 2005, 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 org.xml.sax.InputSource;
  29 import javax.xml.namespace.QName;

  30 
  31 /**
  32  * <p><code>XPathExpression</code> 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</code> 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</code> 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</code>
  88  * method is invoked, applications may not recursively call
  89  * the <code>evaluate</code> 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      * <p>Evaluate the compiled XPath expression in the specified context and return the result as the specified type.</p>
 101      *
 102      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
 103      * variable, function and QName resolution and return type conversion.</p>
 104      *
 105      * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants},
 106      * then an <code>IllegalArgumentException</code> is thrown.</p>



 107      *
 108      * <p>If a <code>null</code> value is provided for
 109      * <code>item</code>, an empty document will be used for the
 110      * context.
 111      * If <code>returnType</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p>
 112      *
 113      * @param item The starting context (a node, for example).
 114      * @param returnType The desired return type.
 115      *
 116      * @return The <code>Object</code> that is the result of evaluating the expression and converting the result to
 117      *   <code>returnType</code>.
 118      *
 119      * @throws XPathExpressionException If the expression cannot be evaluated.
 120      * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}.
 121      * @throws NullPointerException If  <code>returnType</code> is <code>null</code>.
 122      */
 123     public Object evaluate(Object item, QName returnType)
 124         throws XPathExpressionException;
 125 
 126     /**
 127      * <p>Evaluate the compiled XPath expression in the specified context and return the result as a <code>String</code>.</p>
 128      *
 129      * <p>This method calls {@link #evaluate(Object item, QName returnType)} with a <code>returnType</code> of
 130      * {@link XPathConstants#STRING}.</p>
 131      *
 132      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
 133      * variable, function and QName resolution and return type conversion.</p>
 134      *
 135      * <p>If a <code>null</code> value is provided for
 136      * <code>item</code>, an empty document will be used for the
 137      * context.


 138      *
 139      * @param item The starting context (a node, for example).

 140      *
 141      * @return The <code>String</code> that is the result of evaluating the expression and converting the result to a
 142      *   <code>String</code>.
 143      *


 144      * @throws XPathExpressionException If the expression cannot be evaluated.
 145      */
 146     public String evaluate(Object item)
 147         throws XPathExpressionException;
 148 
 149     /**
 150      * <p>Evaluate the compiled XPath expression in the context of the specified <code>InputSource</code> and return the result as the
 151      * specified type.</p>
 152      *
 153      * <p>This method builds a data model for the {@link InputSource} and calls
 154      * {@link #evaluate(Object item, QName returnType)} on the resulting document object.</p>
 155      *
 156      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
 157      * variable, function and QName resolution and return type conversion.</p>
 158      *
 159      * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants},
 160      * then an <code>IllegalArgumentException</code> is thrown.</p>
 161      *
 162      * <p>If <code>source</code> or <code>returnType</code> is <code>null</code>,
 163      * then a <code>NullPointerException</code> is thrown.</p>
 164      *
 165      * @param source The <code>InputSource</code> of the document to evaluate over.
 166      * @param returnType The desired return type.
 167      *
 168      * @return The <code>Object</code> that is the result of evaluating the expression and converting the result to
 169      *   <code>returnType</code>.
 170      *
 171      * @throws XPathExpressionException If the expression cannot be evaluated.
 172      * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}.
 173      * @throws NullPointerException If  <code>source</code> or <code>returnType</code> is <code>null</code>.
 174      */
 175     public Object evaluate(InputSource source, QName returnType)
 176         throws XPathExpressionException;
 177 
 178     /**
 179      * <p>Evaluate the compiled XPath expression in the context of the specified <code>InputSource</code> and return the result as a
 180      * <code>String</code>.</p>
 181      *
 182      * <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a <code>returnType</code> of
 183      * {@link XPathConstants#STRING}.</p>
 184      *
 185      * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation,
 186      * variable, function and QName resolution and return type conversion.</p>
 187      *
 188      * <p>If <code>source</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p>
 189      *
 190      * @param source The <code>InputSource</code> of the document to evaluate over.
 191      *
 192      * @return The <code>String</code> that is the result of evaluating the expression and converting the result to a
 193      *   <code>String</code>.
 194      *
 195      * @throws XPathExpressionException If the expression cannot be evaluated.
 196      * @throws NullPointerException If  <code>source</code> is <code>null</code>.
 197      */
 198     public String evaluate(InputSource source)
 199         throws XPathExpressionException;




















































































































































































 200 }
--- EOF ---