1 /* 2 * Copyright 2007 the original author or authors. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package org.springframework.xml.xpath; 18 19 import java.util.List; 20 import javax.xml.transform.Source; 21 22 import org.w3c.dom.Node; 23 24 /** 25 * Interface that specifies a basic set of XPath operations, implemented by various XPathTemplates. Contains numerous 26 * evaluation methods, 27 * <p/> 28 * The templates that implement this interface do not use precompiled XPath expressions. Consider using the {@link 29 * XPathExpressionFactory} or the {@link XPathExpressionFactoryBean} for optimal performance, but less flexibility. 30 * 31 * @author Arjen Poutsma 32 * @see Jaxp13XPathTemplate 33 * @see JaxenXPathTemplate 34 * @since 1.0.0 35 */ 36 public interface XPathOperations { 37 38 /** 39 * Evaluates the given expression as a <code>boolean</code>. Returns the boolean evaluation of the expression, or 40 * <code>false</code> if it is invalid. 41 * 42 * @param expression the XPath expression 43 * @param context the context starting point 44 * @return the result of the evaluation 45 * @throws XPathException in case of XPath errors 46 * @see <a href="http://www.w3.org/TR/xpath#booleans">XPath specification</a> 47 */ 48 boolean evaluateAsBoolean(String expression, Source context) throws XPathException; 49 50 /** 51 * Evaluates the given expression as a {@link Node}. Returns the evaluation of the expression, or <code>null</code> 52 * if it is invalid. 53 * 54 * @param expression the XPath expression 55 * @param context the context starting point 56 * @return the result of the evaluation 57 * @throws XPathException in case of XPath errors 58 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 59 */ 60 Node evaluateAsNode(String expression, Source context) throws XPathException; 61 62 /** 63 * Evaluates the given expression as a list of {@link Node} objects. Returns the evaluation of the expression, or an 64 * empty list if no results are found. 65 * 66 * @param expression the XPath expression 67 * @param context the context starting point 68 * @return the result of the evaluation 69 * @throws XPathException in case of XPath errors 70 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 71 */ 72 List evaluateAsNodeList(String expression, Source context) throws XPathException; 73 74 /** 75 * Evaluates the given expression as a <code>double</code>. Returns the evaluation of the expression, or {@link 76 * Double#NaN} if it is invalid. 77 * 78 * @param expression the XPath expression 79 * @param context the context starting point 80 * @return the result of the evaluation 81 * @throws XPathException in case of XPath errors 82 * @see <a href="http://www.w3.org/TR/xpath#numbers">XPath specification</a> 83 */ 84 double evaluateAsDouble(String expression, Source context) throws XPathException; 85 86 /** 87 * Evaluates the given expression as a {@link String}. Returns the evaluation of the expression, or 88 * <code>null</code> if it is invalid. 89 * 90 * @param expression the XPath expression 91 * @param context the context starting point 92 * @return the result of the evaluation 93 * @throws XPathException in case of XPath errors 94 * @see <a href="http://www.w3.org/TR/xpath#strings">XPath specification</a> 95 */ 96 String evaluateAsString(String expression, Source context) throws XPathException; 97 98 /** 99 * Evaluates the given expression, mapping a single {@link Node} result to a Java object via a {@link NodeMapper}. 100 * 101 * @param expression the XPath expression 102 * @param context the context starting point 103 * @param nodeMapper object that will map one object per node 104 * @return the single mapped object 105 * @throws XPathException in case of XPath errors 106 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 107 */ 108 Object evaluateAsObject(String expression, Source context, NodeMapper nodeMapper) throws XPathException; 109 110 /** 111 * Evaluates the given expression, mapping each result {@link Node} objects to a Java object via a {@link 112 * NodeMapper}. 113 * 114 * @param expression the XPath expression 115 * @param context the context starting point 116 * @param nodeMapper object that will map one object per node 117 * @return the result list, containing mapped objects 118 * @throws XPathException in case of XPath errors 119 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 120 */ 121 List evaluate(String expression, Source context, NodeMapper nodeMapper) throws XPathException; 122 123 /** 124 * Evaluates the given expression, handling the result {@link Node} objects on a per-node basis with a {@link 125 * NodeCallbackHandler}. 126 * 127 * @param expression the XPath expression 128 * @param context the context starting point 129 * @param callbackHandler object that will extract results, one row at a time 130 * @throws XPathException in case of XPath errors 131 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 132 */ 133 void evaluate(String expression, Source context, NodeCallbackHandler callbackHandler) throws XPathException; 134 }