1
2
3
4
5
6
7
8
9
10 package org.dom4j;
11
12 import java.util.List;
13 import java.util.Map;
14
15 import org.jaxen.FunctionContext;
16 import org.jaxen.NamespaceContext;
17 import org.jaxen.VariableContext;
18
19 /*** <p><code>XPath</code> represents an XPath expression after
20 * it has been parsed from a String.</p>
21 *
22 * @author <a href="mailto:james.strachan@metastuff.com">James Strachan</a>
23 * @version $Revision: 1.18 $
24 */
25 public interface XPath extends NodeFilter {
26
27 /*** <p><code>getText</code> will return the textual version of
28 * the XPath expression.</p>
29 *
30 * @return the textual format of the XPath expression.
31 */
32 public String getText();
33
34
35 /*** <p><code>matches</code> returns true if the given node matches
36 * the XPath expression. To be more precise when evaluating this XPath
37 * expression on the given node the result set must include the node.</p>
38 *
39 * @return true if the given node matches this XPath expression
40 */
41 public boolean matches(Node node);
42
43 /*** <p><code>evaluate</code> evaluates an XPath expression and returns
44 * the result as an {@link Object}. The object returned can
45 * either be a {@link List} of {@link Node} instances, a {@link Node}
46 * instance, a {@link String} or a {@link Number} instance depending on
47 * the XPath expression.
48 *
49 * @param context is either a node or a list of nodes on which to
50 * evalute the XPath
51 * @return the value of the XPath expression as a
52 * {@link List} of {@link Node} instances, a {@link Node}
53 * instance, a {@link String} or a {@link Number} instance depending on
54 * the XPath expression.
55 */
56 public Object evaluate(Object context);
57
58 /*** <p><code>selectObject</code> evaluates an XPath expression and returns
59 * the result as an {@link Object}. The object returned can
60 * either be a {@link List} of {@link Node} instances, a {@link Node}
61 * instance, a {@link String} or a {@link Number} instance depending on
62 * the XPath expression.
63 *
64 * @param context is either a node or a list of nodes on which to
65 * evalute the XPath
66 * @return the value of the XPath expression as a
67 * {@link List} of {@link Node} instances, a {@link Node}
68 * instance, a {@link String} or a {@link Number} instance depending on
69 * the XPath expression.
70 *
71 * @deprecated please use evaluate(Object) instead.
72 * WILL BE REMOVED IN dom4j-1.6 !!
73 */
74 public Object selectObject(Object context);
75
76 /*** <p><code>selectNodes</code> performs this XPath expression
77 * on the given {@link Node} or {@link List} of {@link Node}s
78 * instances appending all the results together into a single list.</p>
79 *
80 * @param context is either a node or a list of nodes on which to
81 * evalute the XPath
82 * @return the results of all the XPath evaluations as a single list
83 */
84 public List selectNodes(Object context);
85
86
87 /*** <p><code>selectNodes</code> evaluates the XPath expression
88 * on the given {@link Node} or {@link List} of {@link Node}s
89 * and returns the result as a <code>List</code> of
90 * <code>Node</code>s sorted by the sort XPath expression.</p>
91 *
92 * @param context is either a node or a list of nodes on which to
93 * evalute the XPath
94 * @param sortXPath is the XPath expression to sort by
95 * @return a list of <code>Node</code> instances
96 */
97 public List selectNodes(Object context, XPath sortXPath);
98
99 /*** <p><code>selectNodes</code> evaluates the XPath expression
100 * on the given {@link Node} or {@link List} of {@link Node}s
101 * and returns the result as a <code>List</code> of
102 * <code>Node</code>s sorted by the sort XPath expression.</p>
103 *
104 * @param context is either a node or a list of nodes on which to
105 * evalute the XPath
106 * @param sortXPath is the XPath expression to sort by
107 * @param distinct specifies whether or not duplicate values of the
108 * sort expression are allowed. If this parameter is true then only
109 * distinct sort expressions values are included in the result
110 * @return a list of <code>Node</code> instances
111 */
112 public List selectNodes(Object context, XPath sortXPath, boolean distinct);
113
114
115 /*** <p><code>selectSingleNode</code> evaluates this XPath expression
116 * on the given {@link Node} or {@link List} of {@link Node}s
117 * and returns the result as a single <code>Node</code> instance.</p>
118 *
119 * @param context is either a node or a list of nodes on which to
120 * evalute the XPath
121 * @return a single matching <code>Node</code> instance
122 */
123 public Node selectSingleNode(Object context);
124
125
126 /*** <p><code>valueOf</code> evaluates this XPath expression
127 * and returns the textual representation of the results using the
128 * XPath string() function.</p>
129 *
130 * @param context is either a node or a list of nodes on which to
131 * evalute the XPath
132 * @return the string representation of the results of the XPath expression
133 */
134 public String valueOf(Object context);
135
136 /*** <p><code>numberValueOf</code> evaluates an XPath expression
137 * and returns the numeric value of the XPath expression if the XPath
138 * expression results is a number, or null if the result is not a number.
139 *
140 * @param context is either a node or a list of nodes on which to
141 * evalute the XPath
142 * @return the numeric result of the XPath expression or null
143 * if the result is not a number.
144 */
145 public Number numberValueOf(Object context);
146
147 /***
148 * Retrieve a boolean-value interpretation of this XPath
149 * expression when evaluated against a given context.
150 *
151 * <p>
152 * The boolean-value of the expression is determined per
153 * the <code>boolean(..)</code> core function as defined
154 * in the XPath specification. This means that an expression
155 * that selects zero nodes will return <code>false</code>,
156 * while an expression that selects one-or-more nodes will
157 * return <code>true</code>.
158 * </p>
159 *
160 * @param context The node, nodeset or Context object for evaluation. This value can be null
161 * @return The boolean-value interpretation of this expression.
162 * @since 1.5
163 */
164 public boolean booleanValueOf(Object context);
165
166 /*** <p><code>sort</code> sorts the given List of Nodes
167 * using this XPath expression as a {@link java.util.Comparator}.</p>
168 *
169 * @param list is the list of Nodes to sort
170 */
171 public void sort( List list );
172
173 /*** <p><code>sort</code> sorts the given List of Nodes
174 * using this XPath expression as a {@link java.util.Comparator}
175 * and optionally removing duplicates.</p>
176 *
177 * @param list is the list of Nodes to sort
178 * @param distinct if true then duplicate values (using the sortXPath for
179 * comparisions) will be removed from the List
180 */
181 public void sort( List list, boolean distinct );
182
183
184 /*** @return the current function context
185 */
186 public FunctionContext getFunctionContext();
187
188 /*** Sets the function context to be used when evaluating XPath
189 * expressions
190 */
191 public void setFunctionContext(FunctionContext functionContext);
192
193 /*** @return the current namespace context
194 */
195 public NamespaceContext getNamespaceContext();
196
197 /*** Sets the namespace context to be used when evaluating XPath
198 * expressions
199 */
200 public void setNamespaceContext(NamespaceContext namespaceContext);
201
202 /*** Sets the current NamespaceContext from a Map where the keys
203 * are the String namespace prefixes and the values are the namespace
204 * URIs For example.<br>
205 *
206 * <pre>
207 * Map uris = new HashMap();<br/>
208 * uris.put( "SOAP-ENV", "http://schemas.xmlsoap.org/soap/envelope/" );<br/>
209 * uris.put( "m", "urn:xmethodsBabelFish" );<br/>
210 * XPath xpath = document.createXPath( "/SOAP-ENV:Envelope/SOAP-ENV:Body/m:BabelFish" );<br/>
211 * xpath.setNamespaceURIs( uris );<br/>
212 * Node babelfish = xpath.selectSingleNode( document );<br/>
213 * </pre>
214 *
215 */
216 public void setNamespaceURIs(Map map);
217
218 /*** @return the current variable context
219 */
220 public VariableContext getVariableContext();
221
222 /*** Sets the variable context to be used when evaluating XPath
223 * expressions
224 */
225 public void setVariableContext(VariableContext variableContext);
226
227 }
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275