1320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/* 2320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Licensed to the Apache Software Foundation (ASF) under one or more 3320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * contributor license agreements. See the NOTICE file distributed with 4320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this work for additional information regarding copyright ownership. 5320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The ASF licenses this file to You under the Apache License, Version 2.0 6320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * (the "License"); you may not use this file except in compliance with 7320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the License. You may obtain a copy of the License at 8320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 9320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 10320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 11320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Unless required by applicable law or agreed to in writing, software 12320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 13320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * See the License for the specific language governing permissions and 15320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * limitations under the License. 16320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 17320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson// $Id: XPathExpression.java 446598 2006-09-15 12:55:40Z jeremias $ 18320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 19320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpackage javax.xml.xpath; 20320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 21320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport javax.xml.namespace.QName; 227365de1056414750d0a7d1fdd26025fd247f0d04Jesse Wilsonimport org.xml.sax.InputSource; 23320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 24320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/** 25320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p><code>XPathExpression</code> provides access to compiled XPath expressions.</p> 26320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 27320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <table id="XPathExpression-evaluation" border="1" cellpadding="2"> 28320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <thead> 29320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 30320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <th colspan="2">Evaluation of XPath Expressions.</th> 31320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 32320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </thead> 33320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tbody> 34320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 35320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>context</td> 36320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 37320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If a request is made to evaluate the expression in the absence 38320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * of a context item, an empty document node will be used for the context. 39320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * For the purposes of evaluating XPath expressions, a DocumentFragment 40320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * is treated like a Document node. 41320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 42320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 43320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 44320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>variables</td> 45320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 46320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver}. 47320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * An {@link XPathExpressionException} is raised if the variable resolver is undefined or 48320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the resolver returns <code>null</code> for the variable. 49320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The value of a variable must be immutable through the course of any single evaluation.</p> 50320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 51320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 52320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 53320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>functions</td> 54320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 55320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver}. 56320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * An {@link XPathExpressionException} is raised if the function resolver is undefined or 57320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the function resolver returns <code>null</code> for the function.</p> 58320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 59320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 60320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 61320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>QNames</td> 62320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 63320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * QNames in the expression are resolved against the XPath namespace context. 64320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 65320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 66320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 67320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>result</td> 68320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 69320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * This result of evaluating an expression is converted to an instance of the desired return type. 70320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Valid return types are defined in {@link XPathConstants}. 71320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Conversion to the return type follows XPath conversion rules.</p> 72320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 73320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 74320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </table> 75320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 76320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> 77320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 78320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @version $Revision: 446598 $, $Date: 2006-09-15 05:55:40 -0700 (Fri, 15 Sep 2006) $ 79320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @see <a href="http://www.w3.org/TR/xpath#section-Expressions">XML Path Language (XPath) Version 1.0, Expressions</a> 80320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @since 1.5 81320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 82320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpublic interface XPathExpression { 83f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 84320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 85320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Evaluate the compiled XPath expression in the specified context and return the result as the specified type.</p> 86320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 87320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 88320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * variable, function and QName resolution and return type conversion.</p> 89f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 90320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants}, 91320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * then an <code>IllegalArgumentException</code> is thrown.</p> 92f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 93f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>If a <code>null</code> value is provided for 94320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>item</code>, an empty document will be used for the 95320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * context. 96f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * If <code>returnType</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p> 97320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 98320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param item The starting context (node or node list, for example). 99320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param returnType The desired return type. 100f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 101320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return The <code>Object</code> that is the result of evaluating the expression and converting the result to 102320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>returnType</code>. 103f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 104320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If the expression cannot be evaluated. 105320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}. 106f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @throws NullPointerException If <code>returnType</code> is <code>null</code>. 107320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 108320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Object evaluate(Object item, QName returnType) 109320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 110320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 111320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 112320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Evaluate the compiled XPath expression in the specified context and return the result as a <code>String</code>.</p> 113320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 114320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This method calls {@link #evaluate(Object item, QName returnType)} with a <code>returnType</code> of 115320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link XPathConstants#STRING}.</p> 116f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 117320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 118320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * variable, function and QName resolution and return type conversion.</p> 119f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 120f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>If a <code>null</code> value is provided for 121320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>item</code>, an empty document will be used for the 122320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * context. 123320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 124320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param item The starting context (node or node list, for example). 125f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 126f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return The <code>String</code> that is the result of evaluating the expression and converting the result to a 127320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>String</code>. 128f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 129320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If the expression cannot be evaluated. 130320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 131320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public String evaluate(Object item) 132320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 133320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 134320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 135320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Evaluate the compiled XPath expression in the context of the specified <code>InputSource</code> and return the result as the 136320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * specified type.</p> 137320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 138320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This method builds a data model for the {@link InputSource} and calls 139320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link #evaluate(Object item, QName returnType)} on the resulting document object.</p> 140f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 141320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 142320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * variable, function and QName resolution and return type conversion.</p> 143f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 144320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants}, 145320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * then an <code>IllegalArgumentException</code> is thrown.</p> 146f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 147320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If <code>source</code> or <code>returnType</code> is <code>null</code>, 148f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * then a <code>NullPointerException</code> is thrown.</p> 149320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 150320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param source The <code>InputSource</code> of the document to evaluate over. 151320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param returnType The desired return type. 152f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 153320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return The <code>Object</code> that is the result of evaluating the expression and converting the result to 154320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>returnType</code>. 155f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 156320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If the expression cannot be evaluated. 157320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}. 158f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @throws NullPointerException If <code>source</code> or <code>returnType</code> is <code>null</code>. 159320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 160320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Object evaluate(InputSource source, QName returnType) 161320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 162f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 163320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 164320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Evaluate the compiled XPath expression in the context of the specified <code>InputSource</code> and return the result as a 165320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>String</code>.</p> 166320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 167320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This method calls {@link #evaluate(InputSource source, QName returnType)} with a <code>returnType</code> of 168320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link XPathConstants#STRING}.</p> 169f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 170320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See <a href="#XPathExpression-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 171320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * variable, function and QName resolution and return type conversion.</p> 172f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 173f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>If <code>source</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p> 174320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 175320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param source The <code>InputSource</code> of the document to evaluate over. 176f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 177f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @return The <code>String</code> that is the result of evaluating the expression and converting the result to a 178320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>String</code>. 179f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 180320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If the expression cannot be evaluated. 181f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @throws NullPointerException If <code>source</code> is <code>null</code>. 182320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 183320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public String evaluate(InputSource source) 184320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 185320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson} 186