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: XPath.java 569998 2007-08-27 04:40:02Z mrglavas $ 18320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 19320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpackage javax.xml.xpath; 20320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 21320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonimport javax.xml.namespace.NamespaceContext; 227365de1056414750d0a7d1fdd26025fd247f0d04Jesse Wilsonimport javax.xml.namespace.QName; 237365de1056414750d0a7d1fdd26025fd247f0d04Jesse Wilsonimport org.xml.sax.InputSource; 24320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 25320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/** 26320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p><code>XPath</code> provides access to the XPath evaluation environment and expressions.</p> 27320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 28320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <table id="XPath-evaluation" border="1" cellpadding="2"> 29320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <thead> 30320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 31320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <th colspan="2">Evaluation of XPath Expressions.</th> 32320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 33320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </thead> 34320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tbody> 35320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 36320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>context</td> 37320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 38320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If a request is made to evaluate the expression in the absence 39320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * of a context item, an empty document node will be used for the context. 40320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * For the purposes of evaluating XPath expressions, a DocumentFragment 41320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * is treated like a Document node. 42320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 43320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 44320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 45320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>variables</td> 46320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 47320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the expression contains a variable reference, its value will be found through the {@link XPathVariableResolver} 48320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * set with {@link #setXPathVariableResolver(XPathVariableResolver resolver)}. 49320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * An {@link XPathExpressionException} is raised if the variable resolver is undefined or 50320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the resolver returns <code>null</code> for the variable. 51320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The value of a variable must be immutable through the course of any single evaluation.</p> 52320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 53320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 54320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 55320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>functions</td> 56320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 57320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the expression contains a function reference, the function will be found through the {@link XPathFunctionResolver} 58320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * set with {@link #setXPathFunctionResolver(XPathFunctionResolver resolver)}. 59320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * An {@link XPathExpressionException} is raised if the function resolver is undefined or 60320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the function resolver returns <code>null</code> for the function.</p> 61320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 62320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 63320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 64320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>QNames</td> 65320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 66320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * QNames in the expression are resolved against the XPath namespace context 67320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * set with {@link #setNamespaceContext(NamespaceContext nsContext)}. 68320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 69320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 70320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <tr> 71320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td>result</td> 72320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <td> 73320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * This result of evaluating an expression is converted to an instance of the desired return type. 74320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Valid return types are defined in {@link XPathConstants}. 75320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Conversion to the return type follows XPath conversion rules.</p> 76320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </td> 77320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </tr> 78320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </table> 79f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 80320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @author <a href="Norman.Walsh@Sun.com">Norman Walsh</a> 81320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a> 82320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @version $Revision: 569998 $, $Date: 2007-08-26 21:40:02 -0700 (Sun, 26 Aug 2007) $ 83320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @see <a href="http://www.w3.org/TR/xpath">XML Path Language (XPath) Version 1.0</a> 84320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @since 1.5 85320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 86320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpublic interface XPath { 87f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 88d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes /** 89d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <p>Reset this <code>XPath</code> to its original configuration.</p> 90f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 91d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <p><code>XPath</code> is reset to the same state as when it was created with 92d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * {@link XPathFactory#newXPath()}. 93d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <code>reset()</code> is designed to allow the reuse of existing <code>XPath</code>s 94d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * thus saving resources associated with the creation of new <code>XPath</code>s.</p> 95f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 96d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <p>The reset <code>XPath</code> is not guaranteed to have the same {@link XPathFunctionResolver}, {@link XPathVariableResolver} 97d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * or {@link NamespaceContext} <code>Object</code>s, e.g. {@link Object#equals(Object obj)}. 98d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * It is guaranteed to have a functionally equal <code>XPathFunctionResolver</code>, <code>XPathVariableResolver</code> 99d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * and <code>NamespaceContext</code>.</p> 100d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes */ 101d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes public void reset(); 102320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 103320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 104320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Establish a variable resolver.</p> 105f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 106320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>A <code>NullPointerException</code> is thrown if <code>resolver</code> is <code>null</code>.</p> 107f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 108320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param resolver Variable resolver. 109f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 110320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>resolver</code> is <code>null</code>. 111320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 112320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void setXPathVariableResolver(XPathVariableResolver resolver); 113320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 114320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 115320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Return the current variable resolver.</p> 116f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 117320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p><code>null</code> is returned in no variable resolver is in effect.</p> 118f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 119320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return Current variable resolver. 120320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 121320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public XPathVariableResolver getXPathVariableResolver(); 122320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 123320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 124320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Establish a function resolver.</p> 125f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 126320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>A <code>NullPointerException</code> is thrown if <code>resolver</code> is <code>null</code>.</p> 127f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 128320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param resolver XPath function resolver. 129f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 130320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>resolver</code> is <code>null</code>. 131320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 132320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void setXPathFunctionResolver(XPathFunctionResolver resolver); 133320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 134320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 135320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Return the current function resolver.</p> 136f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 137320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p><code>null</code> is returned in no function resolver is in effect.</p> 138f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 139320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return Current function resolver. 140320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 141320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public XPathFunctionResolver getXPathFunctionResolver(); 142320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 143320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 144320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Establish a namespace context.</p> 145f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 146320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>A <code>NullPointerException</code> is thrown if <code>nsContext</code> is <code>null</code>.</p> 147f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 148320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param nsContext Namespace context to use. 149f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 150320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>nsContext</code> is <code>null</code>. 151320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 152320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public void setNamespaceContext(NamespaceContext nsContext); 153320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 154320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 155320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Return the current namespace context.</p> 156f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 157320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p><code>null</code> is returned in no namespace context is in effect.</p> 158f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 159320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return Current Namespace context. 160320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 161320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public NamespaceContext getNamespaceContext(); 162320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 163f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes /** 164320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Compile an XPath expression for later evaluation.</p> 165f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 166320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If <code>expression</code> contains any {@link XPathFunction}s, 167320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * they must be available via the {@link XPathFunctionResolver}. 168320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * An {@link XPathExpressionException} will be thrown if the <code>XPathFunction</code> 169320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * cannot be resolved with the <code>XPathFunctionResolver</code>.</p> 170f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 171f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>If <code>expression</code> is <code>null</code>, a <code>NullPointerException</code> is thrown.</p> 172320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 173320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param expression The XPath expression. 174f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 175320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return Compiled XPath expression. 176f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 177320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If <code>expression</code> cannot be compiled. 178320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>expression</code> is <code>null</code>. 179320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 180320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public XPathExpression compile(String expression) 181320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 182320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 183320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 184320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Evaluate an <code>XPath</code> expression in the specified context and return the result as the specified type.</p> 185320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 186320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See <a href="#XPath-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 187320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * variable, function and <code>QName</code> resolution and return type conversion.</p> 188f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 189320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants} ( 190320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link XPathConstants#NUMBER NUMBER}, 191320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link XPathConstants#STRING STRING}, 192320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link XPathConstants#BOOLEAN BOOLEAN}, 193320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link XPathConstants#NODE NODE} or 194320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link XPathConstants#NODESET NODESET}) 195320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * then an <code>IllegalArgumentException</code> is thrown.</p> 196f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 197f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>If a <code>null</code> value is provided for 198320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>item</code>, an empty document will be used for the 199320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * context. 200320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If <code>expression</code> or <code>returnType</code> is <code>null</code>, then a 201320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>NullPointerException</code> is thrown.</p> 202320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 203320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param expression The XPath expression. 204320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param item The starting context (node or node list, for example). 205320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param returnType The desired return type. 206f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 207320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return Result of evaluating an XPath expression as an <code>Object</code> of <code>returnType</code>. 208f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 209320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If <code>expression</code> cannot be evaluated. 210320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}. 211320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>expression</code> or <code>returnType</code> is <code>null</code>. 212320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 213320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Object evaluate(String expression, Object item, QName returnType) 214320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 215320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 216320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 217320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Evaluate an XPath expression in the specified context and return the result as a <code>String</code>.</p> 218320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 219320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This method calls {@link #evaluate(String expression, Object item, QName returnType)} with a <code>returnType</code> of 220320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link XPathConstants#STRING}.</p> 221f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 222320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See <a href="#XPath-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 223320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * variable, function and QName resolution and return type conversion.</p> 224320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 225f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>If a <code>null</code> value is provided for 226320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>item</code>, an empty document will be used for the 227320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * context. 228320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If <code>expression</code> is <code>null</code>, then a <code>NullPointerException</code> is thrown.</p> 229f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 230320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param expression The XPath expression. 231320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param item The starting context (node or node list, for example). 232f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 233320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return The <code>String</code> that is the result of evaluating the expression and 234320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * converting the result to a <code>String</code>. 235f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 236320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If <code>expression</code> cannot be evaluated. 237320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>expression</code> is <code>null</code>. 238320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 239320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public String evaluate(String expression, Object item) 240320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 241320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 242320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 243320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Evaluate an XPath expression in the context of the specified <code>InputSource</code> 244320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and return the result as the specified type.</p> 245320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 246320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This method builds a data model for the {@link InputSource} and calls 247320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link #evaluate(String expression, Object item, QName returnType)} on the resulting document object.</p> 248320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 249320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See <a href="#XPath-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 250320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * variable, function and QName resolution and return type conversion.</p> 251f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 252320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If <code>returnType</code> is not one of the types defined in {@link XPathConstants}, 253320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * then an <code>IllegalArgumentException</code> is thrown.</p> 254f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 255320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If <code>expression</code>, <code>source</code> or <code>returnType</code> is <code>null</code>, 256320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * then a <code>NullPointerException</code> is thrown.</p> 257f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 258320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param expression The XPath expression. 259320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param source The input source of the document to evaluate over. 260320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param returnType The desired return type. 261f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 262320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return The <code>Object</code> that encapsulates the result of evaluating the expression. 263f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 264320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If expression cannot be evaluated. 265320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws IllegalArgumentException If <code>returnType</code> is not one of the types defined in {@link XPathConstants}. 266320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>expression</code>, <code>source</code> or <code>returnType</code> 267320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * is <code>null</code>. 268320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 269320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public Object evaluate( 270320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson String expression, 271320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson InputSource source, 272320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson QName returnType) 273320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 274320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 275320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 276320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Evaluate an XPath expression in the context of the specified <code>InputSource</code> 277320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and return the result as a <code>String</code>.</p> 278320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 279320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This method calls {@link #evaluate(String expression, InputSource source, QName returnType)} with a 280320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>returnType</code> of {@link XPathConstants#STRING}.</p> 281320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 282320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See <a href="#XPath-evaluation">Evaluation of XPath Expressions</a> for context item evaluation, 283320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * variable, function and QName resolution and return type conversion.</p> 284f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 285320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If <code>expression</code> or <code>source</code> is <code>null</code>, 286320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * then a <code>NullPointerException</code> is thrown.</p> 287f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 288320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param expression The XPath expression. 289320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param source The <code>InputSource</code> of the document to evaluate over. 290f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 291320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return The <code>String</code> that is the result of evaluating the expression and 292320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * converting the result to a <code>String</code>. 293f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 294320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathExpressionException If expression cannot be evaluated. 295320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>expression</code> or <code>source</code> is <code>null</code>. 296320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 297320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public String evaluate(String expression, InputSource source) 298320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathExpressionException; 299320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson} 300