View Javadoc

1   /*
2    * $Header$
3    * $Revision: 1337 $
4    * $Date: 2008-12-02 17:58:10 -0800 (Tue, 02 Dec 2008) $
5    *
6    * ====================================================================
7    *
8    * Copyright 2000-2002 bob mcwhirter & James Strachan.
9    * All rights reserved.
10   *
11   *
12   * Redistribution and use in source and binary forms, with or without
13   * modification, are permitted provided that the following conditions are
14   * met:
15   * 
16   *   * Redistributions of source code must retain the above copyright
17   *     notice, this list of conditions and the following disclaimer.
18   * 
19   *   * Redistributions in binary form must reproduce the above copyright
20   *     notice, this list of conditions and the following disclaimer in the
21   *     documentation and/or other materials provided with the distribution.
22   * 
23   *   * Neither the name of the Jaxen Project nor the names of its
24   *     contributors may be used to endorse or promote products derived 
25   *     from this software without specific prior written permission.
26   * 
27   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
28   * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
29   * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
30   * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
31   * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
32   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
33   * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
34   * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
35   * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
36   * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
37   * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38   *
39   * ====================================================================
40   * This software consists of voluntary contributions made by many
41   * individuals on behalf of the Jaxen Project and was originally
42   * created by bob mcwhirter <bob@werken.com> and
43   * James Strachan <jstrachan@apache.org>.  For more information on the
44   * Jaxen Project, please see <http://www.jaxen.org/>.
45   *
46   * $Id: XPathFactory.java 1337 2008-12-03 01:58:10Z elharo $
47   */
48  package org.jaxen.expr;
49  
50  import org.jaxen.JaxenException;
51  
52  /**
53   * An abstract factory used to create individual path component objects.
54   *
55   */
56  public interface XPathFactory
57  {
58      
59      /**
60       * Create a new <code>XPathExpr</code> from an <code>Expr</code>.
61       * 
62       * @param rootExpr the expression wrapped by the resulting XPathExpr
63       * @return an XPathExpr wrapping the root expression
64       * @throws JaxenException
65       */
66      XPathExpr createXPath( Expr rootExpr ) throws JaxenException;
67  
68      /**
69       * Create a new path expression.
70       * 
71       * @param filterExpr the filter expression that starts the path expression
72       * @param locationPath the location path that follows the filter expression
73       * @return a path expression formed by concatenating the two arguments
74       * @throws JaxenException
75       */
76      PathExpr createPathExpr( FilterExpr filterExpr,
77                               LocationPath locationPath ) throws JaxenException;
78  
79      /**
80       * Create a new empty relative location path.
81       * 
82       * @return an empty relative location path
83       * @throws JaxenException
84       */
85      LocationPath createRelativeLocationPath() throws JaxenException;
86  
87      /**
88       * Create a new empty absolute location path.
89       * 
90       * @return an empty absolute location path
91       * @throws JaxenException
92       */
93      LocationPath createAbsoluteLocationPath() throws JaxenException;
94  
95      /**
96       * Returns a new XPath Or expression.  
97       * 
98       * @param lhs the left hand side of the expression
99       * @param rhs the right hand side of the expression
100      * @return <code><i>lhs</i> or <i>rhs</i></code>
101      * @throws JaxenException
102      */
103     BinaryExpr createOrExpr( Expr lhs,
104                              Expr rhs ) throws JaxenException;
105 
106     /**
107      * Returns a new XPath And expression.  
108      * 
109      * @param lhs the left hand side of the expression
110      * @param rhs the right hand side of the expression
111      * @return <code><i>lhs</i> and <i>rhs</i></code>
112      * @throws JaxenException
113      */
114     BinaryExpr createAndExpr( Expr lhs,
115                               Expr rhs ) throws JaxenException;
116 
117     /**
118      * Returns a new XPath equality expression.  
119      * 
120      * @param lhs the left hand side of the expression
121      * @param rhs the right hand side of the expression
122      * @param equalityOperator <code>Operator.EQUALS</code> or <code>Operator.NOT_EQUALS</code>
123      * @return <code><i>lhs</i> = <i>rhs</i></code> or <code><i>lhs</i> != <i>rhs</i></code>
124      * @throws JaxenException if the third argument is not 
125      *                        <code>Operator.EQUALS</code> or <code>Operator.NOT_EQUALS</code>
126      */
127     BinaryExpr createEqualityExpr( Expr lhs,
128                                    Expr rhs,
129                                    int equalityOperator ) throws JaxenException;
130 
131     /**
132      * Returns a new XPath relational expression.  
133      * 
134      * @param lhs the left hand side of the expression
135      * @param rhs the right hand side of the expression
136      * @param relationalOperator <code>Operator.LESS_THAN</code>, <code>Operator.GREATER_THAN</code>, 
137      *                           <code>Operator.LESS_THAN_EQUALS</code>, or <code>Operator.GREATER_THAN_EQUALS</code>
138      * @return <code><i>lhs</i> <i>relationalOperator</i> <i>rhs</i></code> or <code><i>lhs</i> != <i>rhs</i></code>
139      * @throws JaxenException if the third argument is not a relational operator constant
140      */
141     BinaryExpr createRelationalExpr( Expr lhs,
142                                      Expr rhs,
143                                      int relationalOperator ) throws JaxenException;
144 
145     /**
146      * Returns a new XPath additive expression.  
147      * 
148      * @param lhs the left hand side of the expression
149      * @param rhs the right hand side of the expression
150      * @param additiveOperator <code>Operator.ADD</code> or <code>Operator.SUBTRACT</code>
151      * @return <code><i>lhs</i> + <i>rhs</i></code> or <code><i>lhs</i> - <i>rhs</i></code>
152      * @throws JaxenException if the third argument is not 
153      *                        <code>Operator.ADD</code> or <code>Operator.SUBTRACT</code>
154      */
155     BinaryExpr createAdditiveExpr( Expr lhs,
156                                    Expr rhs,
157                                    int additiveOperator ) throws JaxenException;
158 
159     /**
160      * Returns a new XPath multiplicative expression.  
161      * 
162      * @param lhs the left hand side of the expression
163      * @param rhs the right hand side of the expression
164      * @param multiplicativeOperator <code>Operator.MULTIPLY</code>, 
165      *        <code>Operator.DIV</code>, or <code>Operator.MOD</code>
166      * @return <code><i>lhs</i> * <i>rhs</i></code>, <code><i>lhs</i> div <i>rhs</i></code>,
167      *         or <code><i>lhs</i> mod <i>rhs</i></code>
168      * @throws JaxenException if the third argument is not a multiplicative operator constant
169      */
170     BinaryExpr createMultiplicativeExpr( Expr lhs,
171                                          Expr rhs,
172                                          int multiplicativeOperator ) throws JaxenException;
173 
174     /**
175      * Returns a new XPath unary expression.  
176      * 
177      * @param expr the expression to be negated
178      * @param unaryOperator <code>Operator.NEGATIVE</code>
179      * @return <code>- <i>expr</i></code> or <code><i>expr</i></code>
180      * @throws JaxenException
181      */
182     Expr createUnaryExpr( Expr expr,
183                           int unaryOperator ) throws JaxenException;
184 
185     /**
186      * Returns a new XPath union expression.  
187      * 
188      * @param lhs the left hand side of the expression
189      * @param rhs the right hand side of the expression
190      * @return <code><i>lhs</i> | <i>rhs</i></code></code>
191      * @throws JaxenException
192      */
193     UnionExpr createUnionExpr( Expr lhs,
194                                Expr rhs ) throws JaxenException;
195 
196     /**
197      * Returns a new XPath filter expression.  
198      * 
199      * @param expr the basic expression to which the predicate will be added
200      * @return the expression with an empty predicate set
201      * @throws JaxenException
202      */
203     FilterExpr createFilterExpr( Expr expr ) throws JaxenException;
204 
205     
206     /**
207      * Create a new function call expression.
208      * 
209      * @param prefix the namespace prefix of the function
210      * @param functionName the local name of the function 
211      * @return a function with an empty argument list
212      * @throws JaxenException
213      */
214     FunctionCallExpr createFunctionCallExpr( String prefix,
215                                              String functionName ) throws JaxenException;
216 
217     /**
218      * Create a number expression.
219      * 
220      * @param number the value
221      * @return a number expression wrapping that value
222      * @throws JaxenException
223      */
224     NumberExpr createNumberExpr( int number ) throws JaxenException;
225 
226     /**
227      * Create a number expression.
228      * 
229      * @param number the value
230      * @return a number expression wrapping that value
231      * @throws JaxenException
232      */
233     NumberExpr createNumberExpr( double number ) throws JaxenException;
234 
235     /**
236      * Create a string literal expression.
237      * 
238      * @param literal the value
239      * @return a literal expression wrapping that value
240      * @throws JaxenException
241      */
242     LiteralExpr createLiteralExpr( String literal ) throws JaxenException;
243 
244     /**
245      * Create a new variable reference expression.
246      * 
247      * @param prefix the namespace prefix of the variable
248      * @param variableName the local name of the variable 
249      * @return a variable expression
250      * @throws JaxenException
251      */
252     VariableReferenceExpr createVariableReferenceExpr( String prefix,
253                                                        String variableName ) throws JaxenException;
254 
255     /**
256      * Create a step with a named node-test.
257      * 
258      * @param axis the axis to create the name-test on
259      * @param prefix the namespace prefix for the test
260      * @param localName the local name for the test
261      * @return a name step
262      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
263      */
264     Step createNameStep( int axis,
265                          String prefix,
266                          String localName ) throws JaxenException;
267 
268     /**
269      * Create a step with a node() node-test.
270      * 
271      * @param axis the axis to create the node-test on
272      * @return an all node step
273      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
274      */
275     Step createAllNodeStep( int axis ) throws JaxenException;
276 
277     /**
278      * Create a step with a <code>comment()</code> node-test.
279      * 
280      * @param axis the axis to create the <code>comment()</code> node-test on
281      * @return a comment node step
282      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
283      */
284     Step createCommentNodeStep( int axis ) throws JaxenException;
285 
286     /**
287      * Create a step with a <code>text()</code> node-test.
288      * 
289      * @param axis the axis to create the <code>text()</code> node-test on
290      * @return a text node step
291      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
292      */
293     Step createTextNodeStep( int axis ) throws JaxenException;
294 
295     /**
296      * Create a step with a <code>processing-instruction()</code> node-test.
297      * 
298      * @param axis the axis to create the <code>processing-instruction()</code> node-test on
299      * @param name the target to match, may be empty
300      * @return a processing instruction node step
301      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
302      */
303     Step createProcessingInstructionNodeStep( int axis,
304                                               String name ) throws JaxenException;
305 
306     /**
307      * Create from the supplied expression.
308      * 
309      * @param predicateExpr the expression to evaluate in the predicate
310      * @return a predicate
311      * @throws JaxenException
312      */
313     Predicate createPredicate( Expr predicateExpr ) throws JaxenException;
314 
315     /**
316      * Create an empty predicate set. 
317      * 
318      * @return an empty predicate set
319      * @throws JaxenException
320      */
321     PredicateSet createPredicateSet() throws JaxenException;
322     
323 }