1 /*
2 * Copyright 2006 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 *
39 * @param node the starting point
40 * @return the result of the evaluation
41 * @throws XPathException in case of XPath errors
42 * @see <a href="http://www.w3.org/TR/xpath#booleans">XPath specification</a>
43 */
44 boolean evaluateAsBoolean(Node node) throws XPathException;
45
46 /**
47 * Evaluates the given expression as a {@link Node}. Returns the evaluation of the expression, or <code>null</code>
48 * if it is invalid.
49 *
50 * @param node the 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#node-sets">XPath specification</a>
54 */
55 Node evaluateAsNode(Node node) throws XPathException;
56
57 /**
58 * Evaluates the given expression, and returns all {@link Node} objects that conform to it. Returns an empty list if
59 * no result could be found.
60 *
61 * @param node the starting point
62 * @return a list of <code>Node</code>s that are selected by the expression
63 * @throws XPathException in case of XPath errors
64 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
65 */
66 List evaluateAsNodeList(Node node) throws XPathException;
67
68 /**
69 * Evaluates the given expression as a number (<code>double</code>). Returns the numeric evaluation of the
70 * expression, or {@link Double#NaN} if it is invalid.
71 *
72 * @param node the starting point
73 * @return the result of the evaluation
74 * @throws XPathException in case of XPath errors
75 * @see <a href="http://www.w3.org/TR/xpath#numbers">XPath specification</a>
76 */
77 double evaluateAsNumber(Node node) throws XPathException;
78
79 /**
80 * Evaluates the given expression as a String. Returns <code>null</code> if no result could be found.
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#strings">XPath specification</a>
86 */
87 String evaluateAsString(Node node) throws XPathException;
88
89 /**
90 * Evaluates the given expression, mapping a single {@link Node} result to a Java object via a {@link NodeMapper}.
91 *
92 * @param node the starting point
93 * @param nodeMapper object that will map one object per node
94 * @return the single mapped object
95 * @throws XPathException in case of XPath errors
96 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
97 */
98 Object evaluateAsObject(Node node, NodeMapper nodeMapper) throws XPathException;
99
100 /**
101 * Evaluates the given expression, mapping each result {@link Node} objects to a Java object via a {@link
102 * NodeMapper}.
103 *
104 * @param node the starting point
105 * @param nodeMapper object that will map one object per node
106 * @return the result list, containing mapped objects
107 * @throws XPathException in case of XPath errors
108 * @see <a href="http://www.w3.org/TR/xpath#node-sets">XPath specification</a>
109 */
110 List evaluate(Node node, NodeMapper nodeMapper) throws XPathException;
111 }