View Javadoc

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 [email protected]
25   * XPathExpressionFactory}.
26   * <p/>
27   * Implementations of this interface are precompiled, and thus faster, but less flexible, than the XPath expressions
28   * used by [email protected] 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 [email protected] boolean()} function defined in the XPath specification.
40       * This means that an expression that selects zero nodes will return [email protected] false}, while an expression that
41       * selects one or more nodes will return [email protected] true}.
42       * An expression that returns a string returns [email protected] false} for empty strings and [email protected] true} for all other
43       * strings.
44       * An expression that returns a number returns [email protected] false} for zero and [email protected] 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 [email protected] 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 [email protected] 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 [email protected] Double#NaN} if it is invalid.
78       * <p/>
79       * The return value is determined per the [email protected] 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 [email protected] 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 [email protected] Node} result to a Java object via a [email protected] 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 [email protected] Node} objects to a Java object via a [email protected]
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 }