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 }