XPath


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 }
412
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags