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 }