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
21 import org.w3c.dom.Node;
22
23 /**
24 * Defines the contract for a precompiled XPath expression. Concrete instances can be obtained through the {@link
25 * XPathExpressionFactory}.
26 * <p/>
27 * Implementations of this interface are precompiled, and thus faster, but less flexible, than the XPath expressions
28 * used by {@link XPathOperations} implementations.
29 *
30 * @author Arjen Poutsma
31 * @since 1.0.0
32 */
33 public interface XPathExpression {
34
35 /**
36 * Evaluates the given expression as a <code>boolean</code>. Returns the boolean evaluation of the expression, or
37 * <code>false</code> if it is invalid.
38 * <p/>
39 * The return value is determined per the {@code boolean()} function defined in the XPath specification.
40 * This means that an expression that selects zero nodes will return {@code false}, while an expression that
41 * selects one or more nodes will return {@code true}.
42 * An expression that returns a string returns {@code false} for empty strings and {@code true} for all other
43 * strings.
44 * An expression that returns a number returns {@code false} for zero and {@code true} for non-zero numbers.
45 *
46 * @param node the starting point
47 * @return the result of the evaluation
48 * @throws XPathException in case of XPath errors
49 * @see <a href="http://www.w3.org/TR/xpath/#function-boolean">XPath specification - boolean() function</a>
50 */
51 boolean evaluateAsBoolean(Node node) throws XPathException;
52
53 /**
54 * Evaluates the given expression as a {@link Node}. Returns the evaluation of the expression, or <code>null</code>
55 * if it is invalid.
56 *
57 * @param node the starting point
58 * @return the result of the evaluation
59 * @throws XPathException in case of XPath errors
60 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
61 */
62 Node evaluateAsNode(Node node) throws XPathException;
63
64 /**
65 * Evaluates the given expression, and returns all {@link Node} objects that conform to it. Returns an empty list if
66 * no result could be found.
67 *
68 * @param node the starting point
69 * @return a list of <code>Node</code>s that are selected by the expression
70 * @throws XPathException in case of XPath errors
71 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
72 */
73 List<Node> evaluateAsNodeList(Node node) throws XPathException;
74
75 /**
76 * Evaluates the given expression as a number (<code>double</code>). Returns the numeric evaluation of the
77 * expression, or {@link Double#NaN} if it is invalid.
78 * <p/>
79 * The return value is determined per the {@code number()} function as defined in the XPath specification.
80 * This means that if the expression selects multiple nodes, it will return the number value of the first node.
81 *
82 * @param node the starting point
83 * @return the result of the evaluation
84 * @throws XPathException in case of XPath errors
85 * @see <a href="http://www.w3.org/TR/xpath/#function-number">XPath specification - number() function</a>
86 */
87 double evaluateAsNumber(Node node) throws XPathException;
88
89 /**
90 * Evaluates the given expression as a String. Returns <code>null</code> if no result could be found.
91 * <p/>
92 * The return value is determined per the {@code string()} function as defined in the XPath specification.
93 * This means that if the expression selects multiple nodes, it will return the string value of the first node.
94 *
95 * @param node the starting point
96 * @return the result of the evaluation
97 * @throws XPathException in case of XPath errors
98 * @see <a href="http://www.w3.org/TR/xpath/#function-string">XPath specification - string() function</a>
99 */
100 String evaluateAsString(Node node) throws XPathException;
101
102 /**
103 * Evaluates the given expression, mapping a single {@link Node} result to a Java object via a {@link NodeMapper}.
104 *
105 * @param node the starting point
106 * @param nodeMapper object that will map one object per node
107 * @return the single mapped object
108 * @throws XPathException in case of XPath errors
109 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
110 */
111 <T> T evaluateAsObject(Node node, NodeMapper<T> nodeMapper) throws XPathException;
112
113 /**
114 * Evaluates the given expression, mapping each result {@link Node} objects to a Java object via a {@link
115 * NodeMapper}.
116 *
117 * @param node the starting point
118 * @param nodeMapper object that will map one object per node
119 * @return the result list, containing mapped objects
120 * @throws XPathException in case of XPath errors
121 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
122 */
123 <T> List<T> evaluate(Node node, NodeMapper<T> nodeMapper) throws XPathException;
124 }