1 /*
2 * $Header$
3 * $Revision$
4 * $Date$
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$
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 if expression evaluation fails
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 if expression evaluation fails
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 never
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 never
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 if expression evaluation fails
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 if expression evaluation fails
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 if expression evaluation fails
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>
191 * @throws JaxenException if expression evaluation fails
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 if expression evaluation fails
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 if expression evaluation fails
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 if expression evaluation fails
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 if expression evaluation fails
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 if expression evaluation fails
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 if expression evaluation fails
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 if expression evaluation fails
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 never
320 */
321 PredicateSet createPredicateSet() throws JaxenException;
322
323 }