View Javadoc

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