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  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 [email protected]
29   * XPathExpressionFactory} or the [email protected] 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 [email protected] boolean()} function defined in the XPath specification.
43       * This means that an expression that selects zero nodes will return [email protected] false}, while an expression that
44       * selects one or more nodes will return [email protected] true}.
45       * An expression that returns a string returns [email protected] false} for empty strings and [email protected] true} for all other
46       * strings.
47       * An expression that returns a number returns [email protected] false} for zero and [email protected] 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 [email protected] 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 [email protected] 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 [email protected]
83       * Double#NaN} if it is invalid.
84       * <p/>
85       * The return value is determined per the [email protected] 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 [email protected] 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 [email protected] 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 [email protected] Node} result to a Java object via a [email protected] 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 [email protected] Node} objects to a Java object via a [email protected]
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 [email protected] Node} objects on a per-node basis with a [email protected]
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 }