View Javadoc

1   /*
2    * $Header: /home/projects/jaxen/scm/jaxen/src/java/main/org/jaxen/expr/XPathFactory.java,v 1.13 2007/05/02 14:32:38 elharo Exp $
3    * $Revision: 1.13 $
4    * $Date: 2007/05/02 14:32:38 $
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,v 1.13 2007/05/02 14:32:38 elharo Exp $
47   */
48  package org.jaxen.expr;
49  
50  import org.jaxen.JaxenException;
51  import org.jaxen.saxpath.Operator;
52  
53  /***
54   * An abstract factory used to create individual path component objects.
55   *
56   */
57  public interface XPathFactory
58  {
59      
60      /***
61       * Create a new <code>XPathExpr</code> from an <code>Expr</code>.
62       * 
63       * @param rootExpr the expression wrapped by the resuolting XPathExpr
64       * @return an XPathExpr wrapping the root expression
65       * @throws JaxenException
66       */
67      XPathExpr createXPath( Expr rootExpr ) throws JaxenException;
68  
69      /***
70       * Create a new path expression.
71       * 
72       * @param filterExpr the filter expression that starts the path expression
73       * @param locationPath the location path that follows the filter expression
74       * @return a path expression formed by concatenating the two arguments
75       * @throws JaxenException
76       */
77      PathExpr createPathExpr( FilterExpr filterExpr,
78                               LocationPath locationPath ) throws JaxenException;
79  
80      /***
81       * Create a new empty relative location path.
82       * 
83       * @return an empty relative location path
84       * @throws JaxenException
85       */
86      LocationPath createRelativeLocationPath() throws JaxenException;
87  
88      /***
89       * Create a new empty absolute location path.
90       * 
91       * @return an empty absolute location path
92       * @throws JaxenException
93       */
94      LocationPath createAbsoluteLocationPath() throws JaxenException;
95  
96      /***
97       * Returns a new XPath Or expression.  
98       * 
99       * @param lhs the left hand side of the expression
100      * @param rhs the right hand side of the expression
101      * @return <code><i>lhs</i> or <i>rhs</i></code>
102      * @throws JaxenException
103      */
104     BinaryExpr createOrExpr( Expr lhs,
105                              Expr rhs ) throws JaxenException;
106 
107     /***
108      * Returns a new XPath And expression.  
109      * 
110      * @param lhs the left hand side of the expression
111      * @param rhs the right hand side of the expression
112      * @return <code><i>lhs</i> and <i>rhs</i></code>
113      * @throws JaxenException
114      */
115     BinaryExpr createAndExpr( Expr lhs,
116                               Expr rhs ) throws JaxenException;
117 
118     /***
119      * Returns a new XPath equality expression.  
120      * 
121      * @param lhs the left hand side of the expression
122      * @param rhs the right hand side of the expression
123      * @param equalityOperator <code>Operator.EQUALS</code> or <code>Operator.NOT_EQUALS</code>
124      * @return <code><i>lhs</i> = <i>rhs</i></code> or <code><i>lhs</i> != <i>rhs</i></code>
125      * @throws JaxenException if the third argument is not 
126      *                        <code>Operator.EQUALS</code> or <code>Operator.NOT_EQUALS</code>
127      */
128     BinaryExpr createEqualityExpr( Expr lhs,
129                                    Expr rhs,
130                                    int equalityOperator ) throws JaxenException;
131 
132     /***
133      * Returns a new XPath relational expression.  
134      * 
135      * @param lhs the left hand side of the expression
136      * @param rhs the right hand side of the expression
137      * @param relationalOperator <code>Operator.LESS_THAN</code>, <code>Operator.GREATER_THAN</code>, 
138      *                           <code>Operator.LESS_THAN_EQUALS</code>, or <code>Operator.GREATER_THAN_EQUALS</code>
139      * @return <code><i>lhs</i> <i>relationalOperator</i> <i>rhs</i></code> or <code><i>lhs</i> != <i>rhs</i></code>
140      * @throws JaxenException if the third argument is not a relational operator constant
141      */
142     BinaryExpr createRelationalExpr( Expr lhs,
143                                      Expr rhs,
144                                      int relationalOperator ) throws JaxenException;
145 
146     /***
147      * Returns a new XPath additive expression.  
148      * 
149      * @param lhs the left hand side of the expression
150      * @param rhs the right hand side of the expression
151      * @param additiveOperator <code>Operator.ADD</code> or <code>Operator.SUBTRACT</code>
152      * @return <code><i>lhs</i> + <i>rhs</i></code> or <code><i>lhs</i> - <i>rhs</i></code>
153      * @throws JaxenException if the third argument is not 
154      *                        <code>Operator.ADD</code> or <code>Operator.SUBTRACT</code>
155      */
156     BinaryExpr createAdditiveExpr( Expr lhs,
157                                    Expr rhs,
158                                    int additiveOperator ) throws JaxenException;
159 
160     /***
161      * Returns a new XPath multiplicative expression.  
162      * 
163      * @param lhs the left hand side of the expression
164      * @param rhs the right hand side of the expression
165      * @param multiplicativeOperator <code>Operator.MULTIPLY</code>, 
166      *        <code>Operator.DIV</code>, or <code>Operator.MOD</code>
167      * @return <code><i>lhs</i> * <i>rhs</i></code>, <code><i>lhs</i> div <i>rhs</i></code>,
168      *         or <code><i>lhs</i> mod <i>rhs</i></code>
169      * @throws JaxenException if the third argument is not a multiplicative operator constant
170      */
171     BinaryExpr createMultiplicativeExpr( Expr lhs,
172                                          Expr rhs,
173                                          int multiplicativeOperator ) throws JaxenException;
174 
175     /***
176      * Returns a new XPath unary expression.  
177      * 
178      * @param expr the expression to be negated
179      * @param unaryOperator <code>Operator.NEGATIVE</code>
180      * @return <code>- <i>expr</i></code> or <code><i>expr</i></code>
181      * @throws JaxenException
182      */
183     Expr createUnaryExpr( Expr expr,
184                           int unaryOperator ) throws JaxenException;
185 
186     /***
187      * Returns a new XPath union expression.  
188      * 
189      * @param lhs the left hand side of the expression
190      * @param rhs the right hand side of the expression
191      * @return <code><i>lhs</i> | <i>rhs</i></code></code>
192      * @throws JaxenException
193      */
194     UnionExpr createUnionExpr( Expr lhs,
195                                Expr rhs ) throws JaxenException;
196 
197     /***
198      * Returns a new XPath filter expression.  
199      * 
200      * @param expr the basic expression to which the predicate will be added
201      * @return the expression with an empty predicate set
202      * @throws JaxenException
203      */
204     FilterExpr createFilterExpr( Expr expr ) throws JaxenException;
205 
206     
207     /***
208      * Create a new function call expression.
209      * 
210      * @param prefix the namespace prefix of the function
211      * @param functionName the local name of the function 
212      * @return a function with an empty argument list
213      * @throws JaxenException
214      */
215     FunctionCallExpr createFunctionCallExpr( String prefix,
216                                              String functionName ) throws JaxenException;
217 
218     /***
219      * Create a number expression.
220      * 
221      * @param number the value
222      * @return a number expression wrapping that value
223      * @throws JaxenException
224      */
225     NumberExpr createNumberExpr( int number ) throws JaxenException;
226 
227     /***
228      * Create a number expression.
229      * 
230      * @param number the value
231      * @return a number expression wrapping that value
232      * @throws JaxenException
233      */
234     NumberExpr createNumberExpr( double number ) throws JaxenException;
235 
236     /***
237      * Create a string literal expression.
238      * 
239      * @param literal the value
240      * @return a literal expression wrapping that value
241      * @throws JaxenException
242      */
243     LiteralExpr createLiteralExpr( String literal ) throws JaxenException;
244 
245     /***
246      * Create a new variable reference expression.
247      * 
248      * @param prefix the namespace prefix of the variable
249      * @param variableName the local name of the variable 
250      * @return a variable expression
251      * @throws JaxenException
252      */
253     VariableReferenceExpr createVariableReferenceExpr( String prefix,
254                                                        String variableName ) throws JaxenException;
255 
256     /***
257      * Create a step with a named node-test.
258      * 
259      * @param axis the axis to create the name-test on
260      * @param prefix the namespace prefix for the test
261      * @param localName the local name for the test
262      * @return a name step
263      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
264      */
265     Step createNameStep( int axis,
266                          String prefix,
267                          String localName ) throws JaxenException;
268 
269     /***
270      * Create a step with a node() node-test.
271      * 
272      * @param axis the axis to create the node-test on
273      * @return an all node step
274      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
275      */
276     Step createAllNodeStep( int axis ) throws JaxenException;
277 
278     /***
279      * Create a step with a <code>comment()</code> node-test.
280      * 
281      * @param axis the axis to create the <code>comment()</code> node-test on
282      * @return a comment node step
283      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
284      */
285     Step createCommentNodeStep( int axis ) throws JaxenException;
286 
287     /***
288      * Create a step with a <code>text()</code> node-test.
289      * 
290      * @param axis the axis to create the <code>text()</code> node-test on
291      * @return a text node step
292      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
293      */
294     Step createTextNodeStep( int axis ) throws JaxenException;
295 
296     /***
297      * Create a step with a <code>processing-instruction()</code> node-test.
298      * 
299      * @param axis the axis to create the <code>processing-instruction()</code> node-test on
300      * @param name the target to match, may be empty
301      * @return a processing instruction node step
302      * @throws JaxenException if <code>axis</code> is not one of the axis constants????
303      */
304     Step createProcessingInstructionNodeStep( int axis,
305                                               String name ) throws JaxenException;
306 
307     /***
308      * Create from the supplied expression.
309      * 
310      * @param predicateExpr the expression to evaluate in the predicate
311      * @return a predicate
312      * @throws JaxenException
313      */
314     Predicate createPredicate( Expr predicateExpr ) throws JaxenException;
315 
316     /***
317      * Create an empty predicate set. 
318      * 
319      * @return an empty predicate set
320      * @throws JaxenException
321      */
322     PredicateSet createPredicateSet() throws JaxenException;
323     
324 }