1 /* 2 * Copyright 2005-2010 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 * <p/> 42 * The return value is determined per the {@code boolean()} function defined in the XPath specification. 43 * This means that an expression that selects zero nodes will return {@code false}, while an expression that 44 * selects one or more nodes will return {@code true}. 45 * An expression that returns a string returns {@code false} for empty strings and {@code true} for all other 46 * strings. 47 * An expression that returns a number returns {@code false} for zero and {@code true} for non-zero numbers. 48 * 49 * @param expression the XPath expression 50 * @param context the context starting point 51 * @return the result of the evaluation 52 * @throws XPathException in case of XPath errors 53 * @see <a href="http://www.w3.org/TR/xpath/#function-boolean">XPath specification - boolean() function</a> 54 */ 55 boolean evaluateAsBoolean(String expression, Source context) throws XPathException; 56 57 /** 58 * Evaluates the given expression as a {@link Node}. Returns the evaluation of the expression, or <code>null</code> 59 * if it is invalid. 60 * 61 * @param expression the XPath expression 62 * @param context the context starting point 63 * @return the result of the evaluation 64 * @throws XPathException in case of XPath errors 65 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 66 */ 67 Node evaluateAsNode(String expression, Source context) throws XPathException; 68 69 /** 70 * Evaluates the given expression as a list of {@link Node} objects. Returns the evaluation of the expression, or an 71 * empty list if no results are found. 72 * 73 * @param expression the XPath expression 74 * @param context the context starting point 75 * @return the result of the evaluation 76 * @throws XPathException in case of XPath errors 77 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 78 */ 79 List<Node> evaluateAsNodeList(String expression, Source context) throws XPathException; 80 81 /** 82 * Evaluates the given expression as a <code>double</code>. Returns the evaluation of the expression, or {@link 83 * Double#NaN} if it is invalid. 84 * <p/> 85 * The return value is determined per the {@code number()} function as defined in the XPath specification. 86 * This means that if the expression selects multiple nodes, it will return the number value of the first node. 87 * 88 * @param expression the XPath expression 89 * @param context the context starting point 90 * @return the result of the evaluation 91 * @throws XPathException in case of XPath errors 92 * @see <a href="http://www.w3.org/TR/xpath/#function-number">XPath specification - number() function</a> 93 */ 94 double evaluateAsDouble(String expression, Source context) throws XPathException; 95 96 /** 97 * Evaluates the given expression as a {@link String}. Returns the evaluation of the expression, or 98 * <code>null</code> if it is invalid. 99 * <p/> 100 * The return value is determined per the {@code string()} function as defined in the XPath specification. 101 * This means that if the expression selects multiple nodes, it will return the string value of the first node. 102 * 103 * @param expression the XPath expression 104 * @param context the context starting point 105 * @return the result of the evaluation 106 * @throws XPathException in case of XPath errors 107 * @see <a href="http://www.w3.org/TR/xpath/#function-string">XPath specification - string() function</a> 108 */ 109 String evaluateAsString(String expression, Source context) throws XPathException; 110 111 /** 112 * Evaluates the given expression, mapping a single {@link Node} result to a Java object via a {@link 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 single mapped object 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 <T> T evaluateAsObject(String expression, Source context, NodeMapper<T> nodeMapper) throws XPathException; 122 123 /** 124 * Evaluates the given expression, mapping each result {@link Node} objects to a Java object via a {@link 125 * NodeMapper}. 126 * 127 * @param expression the XPath expression 128 * @param context the context starting point 129 * @param nodeMapper object that will map one object per node 130 * @return the result list, containing mapped objects 131 * @throws XPathException in case of XPath errors 132 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 133 */ 134 <T> List<T> evaluate(String expression, Source context, NodeMapper<T> nodeMapper) throws XPathException; 135 136 /** 137 * Evaluates the given expression, handling the result {@link Node} objects on a per-node basis with a {@link 138 * NodeCallbackHandler}. 139 * 140 * @param expression the XPath expression 141 * @param context the context starting point 142 * @param callbackHandler object that will extract results, one row at a time 143 * @throws XPathException in case of XPath errors 144 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a> 145 */ 146 void evaluate(String expression, Source context, NodeCallbackHandler callbackHandler) throws XPathException; 147 }