View Javadoc

1   package org.jaxen;
2   
3   /*
4    $Id: XPath.java,v 1.8 2005/04/01 02:20:59 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 List of node objects) or 
57   *  a Jaxen Context 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 a given context.
76       *
77       *  <p>
78       *  The context of evaluation my be a <i>document</i>,
79       *  an <i>element</i>, or a set of <i>elements</i>.
80       *  </p>
81       *
82       *  <p>
83       *  If the expression evaluates to a single primitive
84       *  (String, Number or Boolean) type, it is returned
85       *  directly.  Otherwise, the returned value is a
86       *  List (a <code>node-set</code>, in the terms of the
87       *  specification) of values.
88       *  </p>
89       *
90       *  <p>
91       *  When using this method, one must be careful to
92       *  test the class of the returned objects, and of 
93       *  each of the composite members if a <code>List</code>
94       *  is returned.  If the returned members are XML entities,
95       *  they will be the actual <code>Document</code>,
96       *  <code>Element</code> or <code>Attribute</code> objects
97       *  as defined by the concrete XML object-model implementation,
98       *  directly from the context document.  This <b>does not
99       *  return <i>copies</i> of anything</b>, but merely returns
100      *  references to entities within the source document.
101      *  </p>
102      *  
103      *  @param context the node, node-set or Context object for evaluation. 
104      *         This value can be null.
105      *
106      *  @return the result of evaluating the XPath expression
107      *          against the supplied context
108      *
109      *  @throws JaxenException if an error occurs while attempting
110      *          to perform evaluation
111      */
112     Object evaluate(Object context) throws JaxenException;
113     
114     // ----------------------------------------------------------------------
115     //     Advanced Evaluation
116     // ----------------------------------------------------------------------
117     
118     /*** Retrieve a string-value interpretation of this XPath
119      *  expression when evaluated against a given context.
120      *
121      *  <p>
122      *  The string-value of the expression is determined per
123      *  the <code>string(..)</code> core function as defined
124      *  in the XPath specification.  This means that an expression
125      *  that selects more than one nodes will return the string value
126      *  of the first node in the node set..
127      *  </p>
128      *
129      *  @deprecated use {@link #stringValueOf(Object) instead}
130      *
131      *  @param context the node, node-set or Context object for evaluation. 
132      *         This value can be null.
133      *
134      *  @return the string-value of this expression
135      *
136      *  @throws JaxenException if an error occurs while attempting
137      *          to perform evaluation
138      */
139     String valueOf(Object context)
140         throws JaxenException;
141 
142     /*** Retrieve a string-value interpretation of this XPath
143      *  expression when evaluated against a given context.
144      *
145      *  <p>
146      *  The string-value of the expression is determined per
147      *  the <code>string(..)</code> core function as defined
148      *  in the XPath specification.  This means that an expression
149      *  that selects more than one nodes will return the string value
150      *  of the first node in the node set..
151      *  </p>
152      *
153      *  @param context the node, node-set or Context object for evaluation. 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 perform evaluation
159      */
160      String stringValueOf(Object context)
161         throws JaxenException;
162     
163     /*** Retrieve a boolean-value interpretation of this XPath
164      *  expression when evaluated against a given context.
165      *
166      *  <p>
167      *  The boolean-value of the expression is determined per
168      *  the <code>boolean()</code> core function as defined
169      *  in the XPath specification.  This means that an expression
170      *  that selects zero nodes will return <code>false</code>,
171      *  while an expression that selects one-or-more nodes will
172      *  return <code>true</code>.
173      *  </p>
174      *
175      *  @param context the node, node-set or Context object for evaluation. This value can be null.
176      *
177      *  @return the boolean-value of this expression
178      *
179      *  @throws JaxenException if an error occurs while attempting
180      *          to perform evaluation.
181      */
182     boolean booleanValueOf(Object context)
183         throws JaxenException;
184     
185 
186     /*** Retrieve a number-value interpretation of this XPath
187      *  expression when evaluated against a given context.
188      *
189      *  <p>
190      *  The number-value of the expression is determined per
191      *  the <code>number(..)</code> core function as defined
192      *  in the XPath specification. This means that if this
193      *  expression selects multiple nodes, the number-value
194      *  of the first node is returned.
195      *  </p>
196      *
197      *  @param context the node, node-set or Context object for evaluation. This value can be null
198      *
199      *  @return the number-value interpretation of this expression.
200      *
201      *  @throws JaxenException if an error occurs while attempting
202      *          to perform evaluation.
203      */
204     Number numberValueOf(Object context)
205         throws JaxenException;
206 
207     // ----------------------------------------------------------------------
208     //     Selection
209     // ----------------------------------------------------------------------
210 
211     /*** Select all nodes that are selectable by this XPath
212      *  expression. If multiple nodes match, multiple nodes
213      *  will be returned.
214      *
215      *  <p>
216      *  <b>NOTE:</b> In most cases, nodes will be returned
217      *  in document-order, as defined by the XML Canonicalization
218      *  specification.  The exception occurs when using XPath
219      *  expressions involving the <code>union</code> operator
220      *  (denoted with the pipe '|' character).
221      *  </p>
222      *
223      *  @see #selectSingleNode
224      *
225      *  @param context the node, node-set or Context object for evaluation. This value can be null
226      *
227      *  @return the <code>node-set</code> of all items selected
228      *          by this XPath expression.
229      *
230      *  @throws JaxenException if an error occurs while attempting
231      *          to perform evaluation.
232      */
233     List selectNodes(Object context)
234         throws JaxenException;
235 
236     /*** Select only the first node that is selectable by this XPath
237      *  expression.  If multiple nodes match, only one node will be
238      *  returned.
239      *
240      *  <b>NOTE:</b> In most cases, the selected node will be the first
241      *  selectable node in document-order, as defined by the XML Canonicalization
242      *  specification.  The exception occurs when using XPath
243      *  expressions involving the <code>union</code> operator
244      *  (denoted with the pipe '|' character).
245      *  This is a bug and needs to be fixed.
246      *  </p>
247      *
248      *  @see #selectNodes
249      *
250      *  @param context the node, node-set or Context object for evaluation. This value can be null.
251      *
252      *  @return the <code>node-set</code> of all items selected
253      *          by this XPath expression
254      *
255      *  @throws JaxenException if an error occurs while attempting
256      *          to perform evaluation
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 use with 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 use with 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 use with 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      *  for us in evaluating this XPath expression.
407      *
408      *  @return the implementation-specific <code>Navigator</code>
409      */
410     Navigator getNavigator();
411 }