##### Coverage Report - org.jaxen.XPath

Classes in this File | Line Coverage | Branch Coverage | Complexity
XPath |
N/A |
N/A |
| 1.0;1

1 |  |
     package org.jaxen;
2 |  |
3 |  |
     /*
4 |  |
      $Id: XPath.java,v 1.10 2005/05/07 17:42:14 elharo Exp $
5 |  |
6 |  |
      Copyright 2003 (C) The Werken Company. All Rights Reserved.
7 |  |
8 |  |
      Redistribution and use of this software and associated documentation
9 |  |
      ("Software"), with or without modification, are permitted provided
10 |  |
      that the following conditions are met:
11 |  |
12 |  |
      1. Redistributions of source code must retain copyright
13 |  |
         statements and notices.  Redistributions must also contain a
14 |  |
         copy of this document.
15 |  |
16 |  |
      2. Redistributions in binary form must reproduce the
17 |  |
         above copyright notice, this list of conditions and the
18 |  |
         following disclaimer in the documentation and/or other
19 |  |
         materials provided with the distribution.
20 |  |
21 |  |
      3. The name "jaxen" must not be used to endorse or promote
22 |  |
         products derived from this Software without prior written
23 |  |
         permission of The Werken Company.  For written permission,
24 |  |
         please contact bob@werken.com.
25 |  |
26 |  |
      4. Products derived from this Software may not be called "jaxen"
27 |  |
         nor may "jaxen" appear in their names without prior written
28 |  |
         permission of The Werken Company. "jaxen" is a registered
29 |  |
         trademark of The Werken Company.
30 |  |
31 |  |
      5. Due credit should be given to The Werken Company.
32 |  |
         (http://jaxen.werken.com/).
33 |  |
34 |  |
      THIS SOFTWARE IS PROVIDED BY THE WERKEN COMPANY AND CONTRIBUTORS
35 |  |
      ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
36 |  |
      NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
37 |  |
      FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
38 |  |
      THE WERKEN COMPANY OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
39 |  |
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
40 |  |
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
41 |  |
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
42 |  |
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
43 |  |
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
44 |  |
      ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
45 |  |
      OF THE POSSIBILITY OF SUCH DAMAGE.
46 |  |
47 |  |
      */
48 |  |
49 |  |
     import java.util.List;
50 |  |
51 |  |
     /** Defines the interface to an object which represents an XPath 1.0 expression which
52 |  |
      *  can be evaluated against a variety of different XML object models.
53 |  |
      *
54 |  |
      *  <p>
55 |  |
      *  Most of the evaluation methods take a context object. This is typically a
56 |  |
      *  node or node-set object (which is typically a <code>List</code>
57 |  |
      *  of node objects) or a Jaxen <code>Context</code> object.
58 |  |
      *  A null context is allowed, meaning that
59 |  |
      *  there are no XML nodes on which to evaluate.
60 |  |
      *  </p>
61 |  |
      *
62 |  |
      *  @see org.jaxen.dom4j.Dom4jXPath XPath for dom4j
63 |  |
      *  @see org.jaxen.jdom.JDOMXPath  XPath for JDOM
64 |  |
      *  @see org.jaxen.dom.DOMXPath   XPath for W3C DOM
65 |  |
      *
66 |  |
      *  @author <a href="mailto:bob@eng.werken.com">bob mcwhirter</a>
67 |  |
      *  @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
68 |  |
      */
69 |  |
     public interface XPath
70 |  |
     {
71 |  |
         // ----------------------------------------------------------------------
72 |  |
         //     Basic Evaluation
73 |  |
         // ----------------------------------------------------------------------
74 |  |
75 |  |
         /** Evaluate this XPath against the given context.
76 |  |
          *
77 |  |
          *  <p>
78 |  |
          *  The context of evaluation my be a <em>document</em>,
79 |  |
          *  an <em>element</em>, or a set of <em>elements</em>.
80 |  |
          *  </p>
81 |  |
          *
82 |  |
          *  <p>
83 |  |
          *  If the expression evaluates to an XPath string, number, or boolean
84 |  |
          *  type, then the equivalent Java object type is returned.
85 |  |
          *  Otherwise, if the result is a node-set, then the returned value is a
86 |  |
          *  <code>List</code>.
87 |  |
          *  </p>
88 |  |
          *
89 |  |
          *  <p>
90 |  |
          *  When using this method, one must be careful to
91 |  |
          *  test the class of the returned objects, and of
92 |  |
          *  each of the composite members if a <code>List</code>
93 |  |
          *  is returned.  If the returned members are XML nodes,
94 |  |
          *  they will be the actual <code>Document</code>,
95 |  |
          *  <code>Element</code> or <code>Attribute</code> objects
96 |  |
          *  as defined by the concrete XML object-model implementation,
97 |  |
          *  directly from the context document.  This method <strong>does not
98 |  |
          *  return <em>copies</em> of anything</strong>. It merely returns
99 |  |
          *  references to nodes within the source document.
100 |  |
          *  </p>
101 |  |
          *
102 |  |
          *  @param context the node, node-set or Context object for evaluation.
103 |  |
          *         This value can be null.
104 |  |
          *
105 |  |
          *  @return the result of evaluating the XPath expression
106 |  |
          *          against the supplied context
107 |  |
          *
108 |  |
          *  @throws JaxenException if an error occurs while attempting
109 |  |
          *          to evaluate the expression
110 |  |
          */
111 |  |
         Object evaluate(Object context) throws JaxenException;
112 |  |
113 |  |
         // ----------------------------------------------------------------------
114 |  |
         //     Advanced Evaluation
115 |  |
         // ----------------------------------------------------------------------
116 |  |
117 |  |
         /** Retrieve a string-value interpretation of this XPath
118 |  |
          *  expression when evaluated against the given context.
119 |  |
          *
120 |  |
          *  <p>
121 |  |
          *  The string-value of the expression is determined per
122 |  |
          *  the <code>string(..)</code> core function as defined
123 |  |
          *  in the XPath specification.  This means that an expression
124 |  |
          *  that selects more than one nodes will return the string value
125 |  |
          *  of the first node in the node set..
126 |  |
          *  </p>
127 |  |
          *
128 |  |
          *  @deprecated use {@link #stringValueOf(Object)} instead
129 |  |
          *
130 |  |
          *  @param context the node, node-set or Context object for evaluation.
131 |  |
          *         This value can be null.
132 |  |
          *
133 |  |
          *  @return the string-value of this expression
134 |  |
          *
135 |  |
          *  @throws JaxenException if an error occurs while attempting
136 |  |
          *          to evaluate the expression
137 |  |
          */
138 |  |
         String valueOf(Object context)
139 |  |
             throws JaxenException;
140 |  |
141 |  |
         /** Retrieve a string-value interpretation of this XPath
142 |  |
          *  expression when evaluated against the given context.
143 |  |
          *
144 |  |
          *  <p>
145 |  |
          *  The string-value of the expression is determined per
146 |  |
          *  the <code>string(..)</code> core function as defined
147 |  |
          *  in the XPath specification.  This means that an expression
148 |  |
          *  that selects more than one nodes will return the string value
149 |  |
          *  of the first node in the node set..
150 |  |
          *  </p>
151 |  |
          *
152 |  |
          *  @param context the node, node-set or Context object for evaluation.
153 |  |
          *     This value can be null
154 |  |
          *
155 |  |
          *  @return the string-value interpretation of this expression
156 |  |
          *
157 |  |
          *  @throws JaxenException if an error occurs while attempting
158 |  |
          *          to evaluate the expression
159 |  |
          */
160 |  |
          String stringValueOf(Object context)
161 |  |
             throws JaxenException;
162 |  |
163 |  |
         /** Retrieve the boolean value of the first node in document order
164 |  |
          *  returned by this XPath expression when evaluated in
165 |  |
          *  the given context.
166 |  |
          *
167 |  |
          *  <p>
168 |  |
          *  The boolean-value of the expression is determined per
169 |  |
          *  the <code>boolean()</code> function defined
170 |  |
          *  in the XPath specification.  This means that an expression
171 |  |
          *  that selects zero nodes will return <code>false</code>,
172 |  |
          *  while an expression that selects one or more nodes will
173 |  |
          *  return <code>true</code>. An expression that returns a string
174 |  |
          *  returns false for empty strings and true for all other strings.
175 |  |
          *  An expression that returns a number
176 |  |
          *  returns false for zero and true for non-zero numbers.
177 |  |
          *  </p>
178 |  |
          *
179 |  |
          *  @param context the node, node-set or Context object for evaluation. This value can be null.
180 |  |
          *
181 |  |
          *  @return the boolean-value of this expression
182 |  |
          *
183 |  |
          *  @throws JaxenException if an error occurs while attempting
184 |  |
          *          to evaluate the expression
185 |  |
          */
186 |  |
         boolean booleanValueOf(Object context)
187 |  |
             throws JaxenException;
188 |  |
189 |  |
190 |  |
         /** Retrieve the number-value of the first node in document order
191 |  |
          *  returned by this XPath expression when evaluated in
192 |  |
          *  the given context.
193 |  |
          *
194 |  |
          *  <p>
195 |  |
          *  The number-value of the expression is determined per
196 |  |
          *  the <code>number(..)</code> core function as defined
197 |  |
          *  in the XPath specification. This means that if this
198 |  |
          *  expression selects multiple nodes, the number-value
199 |  |
          *  of the first node is returned.
200 |  |
          *  </p>
201 |  |
          *
202 |  |
          *  @param context the node, node-set or Context object for evaluation. This value can be null.
203 |  |
          *
204 |  |
          *  @return the number-value interpretation of this expression
205 |  |
          *
206 |  |
          *  @throws JaxenException if an error occurs while attempting
207 |  |
          *          to evaluate the expression
208 |  |
          */
209 |  |
         Number numberValueOf(Object context)
210 |  |
             throws JaxenException;
211 |  |
212 |  |
         // ----------------------------------------------------------------------
213 |  |
         //     Selection
214 |  |
         // ----------------------------------------------------------------------
215 |  |
216 |  |
         /** Select all nodes that are selectable by this XPath
217 |  |
          *  expression. If multiple nodes match, multiple nodes
218 |  |
          *  will be returned.
219 |  |
          *
220 |  |
          *  <p>
221 |  |
          *  <b>NOTE:</b> In most cases, nodes will be returned
222 |  |
          *  in document-order, as defined by the XML Canonicalization
223 |  |
          *  specification.  The exception occurs when using XPath
224 |  |
          *  expressions involving the <code>union</code> operator
225 |  |
          *  (denoted with the pipe '|' character).
226 |  |
          *  </p>
227 |  |
          *
228 |  |
          *  @see #selectSingleNode
229 |  |
          *
230 |  |
          *  @param context the node, node-set or Context object for evaluation.
231 |  |
          *     This value can be null.
232 |  |
          *
233 |  |
          *  @return the node-set of all items selected
234 |  |
          *          by this XPath expression.
235 |  |
          *
236 |  |
          *  @throws JaxenException if an error occurs while attempting
237 |  |
          *          to evaluate the expression
238 |  |
          */
239 |  |
         List selectNodes(Object context)
240 |  |
             throws JaxenException;
241 |  |
242 |  |
         /**
243 |  |
          *  <p>
244 |  |
          *  Return the first node in document order that is selected by this
245 |  |
          *  XPath expression.
246 |  |
          *  </p>
247 |  |
          *
248 |  |
          *  @see #selectNodes
249 |  |
          *
250 |  |
          *  @param context the node, node-set or Context object for evaluation.
251 |  |
          *     This value can be null.
252 |  |
          *
253 |  |
          *  @return the first node in document order selected by this XPath expression
254 |  |
          *
255 |  |
          *  @throws JaxenException if an error occurs while attempting
256 |  |
          *          to evaluate the expression
257 |  |
          */
258 |  |
         Object selectSingleNode(Object context)
259 |  |
             throws JaxenException;
260 |  |
261 |  |
         // ----------------------------------------------------------------------
262 |  |
         //     Helpers
263 |  |
         // ----------------------------------------------------------------------
264 |  |
265 |  |
         /** Add a namespace prefix-to-URI mapping for this XPath
266 |  |
          *  expression.
267 |  |
          *
268 |  |
          *  <p>
269 |  |
          *  Namespace prefix-to-URI mappings in an XPath are independent
270 |  |
          *  of those used within any document.  Only the mapping explicitly
271 |  |
          *  added to this XPath will be available for resolving the
272 |  |
          *  XPath expression.
273 |  |
          *  </p>
274 |  |
          *
275 |  |
          *  <p>
276 |  |
          *  This is a convenience method for adding mappings to the
277 |  |
          *  default {@link NamespaceContext} in place for this XPath.
278 |  |
          *  If you have installed a specific custom <code>NamespaceContext</code>,
279 |  |
          *  then this method will throw a <code>JaxenException</code>.
280 |  |
          *  </p>
281 |  |
          *
282 |  |
          *  @param prefix the namespace prefix
283 |  |
          *  @param uri the namespace URI
284 |  |
          *
285 |  |
          *  @throws JaxenException if a <code>NamespaceContext</code>
286 |  |
          *          used by this XPath has been explicitly installed
287 |  |
          */
288 |  |
         void addNamespace(String prefix,
289 |  |
                           String uri)
290 |  |
             throws JaxenException;
291 |  |
292 |  |
         // ----------------------------------------------------------------------
293 |  |
         //     Properties
294 |  |
         // ----------------------------------------------------------------------
295 |  |
296 |  |
         /** Set a <code>NamespaceContext</code> for  this
297 |  |
          *  XPath expression.
298 |  |
          *
299 |  |
          *  <p>
300 |  |
          *  A <code>NamespaceContext</code> is responsible for translating
301 |  |
          *  namespace prefixes within the expression into namespace URIs.
302 |  |
          *  </p>
303 |  |
          *
304 |  |
          *  @see NamespaceContext
305 |  |
          *  @see NamespaceContext#translateNamespacePrefixToUri
306 |  |
          *
307 |  |
          *  @param namespaceContext the <code>NamespaceContext</code> to
308 |  |
          *         install for this expression
309 |  |
          */
310 |  |
         void setNamespaceContext(NamespaceContext namespaceContext);
311 |  |
312 |  |
         /** Set a <code>FunctionContext</code> for  this XPath
313 |  |
          *  expression.
314 |  |
          *
315 |  |
          *  <p>
316 |  |
          *  A <code>FunctionContext</code> is responsible for resolving
317 |  |
          *  all function calls used within the expression.
318 |  |
          *  </p>
319 |  |
          *
320 |  |
          *  @see FunctionContext
321 |  |
          *  @see FunctionContext#getFunction
322 |  |
          *
323 |  |
          *  @param functionContext the <code>FunctionContext</code> to
324 |  |
          *         install for this expression
325 |  |
          */
326 |  |
         void setFunctionContext(FunctionContext functionContext);
327 |  |
328 |  |
         /** Set a <code>VariableContext</code> for this XPath
329 |  |
          *  expression.
330 |  |
          *
331 |  |
          *  <p>
332 |  |
          *  A <code>VariableContext</code> is responsible for resolving
333 |  |
          *  all variables referenced within the expression.
334 |  |
          *  </p>
335 |  |
          *
336 |  |
          *  @see VariableContext
337 |  |
          *  @see VariableContext#getVariableValue
338 |  |
          *
339 |  |
          *  @param variableContext the <code>VariableContext</code> to
340 |  |
          *         install for this expression.
341 |  |
          */
342 |  |
         void setVariableContext(VariableContext variableContext);
343 |  |
344 |  |
         /** Retrieve the <code>NamespaceContext</code> used by this XPath
345 |  |
          *  expression.
346 |  |
          *
347 |  |
          *  <p>
348 |  |
          *  A <code>FunctionContext</code> is responsible for resolving
349 |  |
          *  all function calls used within the expression.
350 |  |
          *  </p>
351 |  |
          *
352 |  |
          *  <p>
353 |  |
          *  If this XPath expression has not previously had a <code>NamespaceContext</code>
354 |  |
          *  installed, a new default <code>NamespaceContext</code> will be created,
355 |  |
          *  installed and returned.
356 |  |
          *  </p>
357 |  |
          *
358 |  |
          *  @see NamespaceContext
359 |  |
          *
360 |  |
          *  @return the <code>NamespaceContext</code> used by this expression
361 |  |
          */
362 |  |
         NamespaceContext getNamespaceContext();
363 |  |
364 |  |
         /** Retrieve the <code>FunctionContext</code> used by this XPath
365 |  |
          *  expression.
366 |  |
          *
367 |  |
          *  <p>
368 |  |
          *  A <code>FunctionContext</code> is responsible for resolving
369 |  |
          *  all function calls used within the expression.
370 |  |
          *  </p>
371 |  |
          *
372 |  |
          *  <p>
373 |  |
          *  If this XPath expression has not previously had a <code>FunctionContext</code>
374 |  |
          *  installed, a new default <code>FunctionContext</code> will be created,
375 |  |
          *  installed and returned.
376 |  |
          *  </p>
377 |  |
          *
378 |  |
          *  @see FunctionContext
379 |  |
          *
380 |  |
          *  @return the <code>FunctionContext</code> used by this expression
381 |  |
          */
382 |  |
         FunctionContext getFunctionContext();
383 |  |
384 |  |
         /** Retrieve the <code>VariableContext</code> used by this XPath
385 |  |
          *  expression.
386 |  |
          *
387 |  |
          *  <p>
388 |  |
          *  A <code>VariableContext</code> is responsible for resolving
389 |  |
          *  all variables referenced within the expression.
390 |  |
          *  </p>
391 |  |
          *
392 |  |
          *  <p>
393 |  |
          *  If this XPath expression has not previously had a <code>VariableContext</code>
394 |  |
          *  installed, a new default <code>VariableContext</code> will be created,
395 |  |
          *  installed and returned.
396 |  |
          *  </p>
397 |  |
          *
398 |  |
          *  @see VariableContext
399 |  |
          *
400 |  |
          *  @return the <code>VariableContext</code> used by this expression
401 |  |
          */
402 |  |
         VariableContext getVariableContext();
403 |  |
404 |  |
405 |  |
         /** Retrieve the XML object-model-specific {@link Navigator}
406 |  |
          *  used to evaluate this XPath expression.
407 |  |
          *
408 |  |
          *  @return the implementation-specific <code>Navigator</code>
409 |  |
          */
410 |  |
         Navigator getNavigator();
411 |  |
     }