View Javadoc

1   /*
2    * Copyright 1999-2004 The Apache Software Foundation
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.jxpath.ri;
17  
18  /***
19   * The Compiler APIs are completely agnostic to the actual types of objects
20   * produced and consumed by the APIs.  Arguments and return values are
21   * declared as java.lang.Object.
22   * <p>
23   * Since  objects returned by Compiler methods are passed as arguments to other
24   * Compiler methods, the descriptions of these methods use virtual types.  There
25   * are four virtual object types: EXPRESSION, QNAME, STEP and NODE_TEST.
26   * <p>
27   * The following example illustrates this notion.  This sequence compiles
28   * the xpath "foo[round(1 div 2)]/text()":
29   * <blockquote><pre>
30   *      Object qname1 = compiler.qname(null, "foo")
31   *      Object expr1 = compiler.number("1");
32   *      Object expr2 = compiler.number("2");
33   *      Object expr3 = compiler.div(expr1, expr2);
34   *      Object expr4 = compiler.
35   *              coreFunction(Compiler.FUNCTION_ROUND, new Object[]{expr3});
36   *      Object test1 = compiler.nodeNameTest(qname1);
37   *      Object step1 = compiler.
38   *              step(Compiler.AXIS_CHILD, test1, new Object[]{expr4});
39   *      Object test2 = compiler.nodeTypeTest(Compiler.NODE_TYPE_TEXT);
40   *      Object step2 = compiler.nodeTypeTest(Compiler.AXIS_CHILD, test2, null);
41   *      Object expr5 = compiler.locationPath(false, new Object[]{step1, step2});
42   * </pre></blockquote>
43   *
44   * @author Dmitri Plotnikov
45   * @version $Revision: 1.9 $ $Date: 2004/02/29 14:17:45 $
46   */
47  public interface Compiler {
48  
49      public static final int NODE_TYPE_NODE = 1;
50      public static final int NODE_TYPE_TEXT = 2;
51      public static final int NODE_TYPE_COMMENT = 3;
52      public static final int NODE_TYPE_PI = 4;
53  
54      public static final int AXIS_SELF = 1;
55      public static final int AXIS_CHILD = 2;
56      public static final int AXIS_PARENT = 3;
57      public static final int AXIS_ANCESTOR = 4;
58      public static final int AXIS_ATTRIBUTE = 5;
59      public static final int AXIS_NAMESPACE = 6;
60      public static final int AXIS_PRECEDING = 7;
61      public static final int AXIS_FOLLOWING = 8;
62      public static final int AXIS_DESCENDANT = 9;
63      public static final int AXIS_ANCESTOR_OR_SELF = 10;
64      public static final int AXIS_FOLLOWING_SIBLING = 11;
65      public static final int AXIS_PRECEDING_SIBLING = 12;
66      public static final int AXIS_DESCENDANT_OR_SELF = 13;
67  
68      public static final int FUNCTION_LAST = 1;
69      public static final int FUNCTION_POSITION = 2;
70      public static final int FUNCTION_COUNT = 3;
71      public static final int FUNCTION_ID = 4;
72      public static final int FUNCTION_LOCAL_NAME = 5;
73      public static final int FUNCTION_NAMESPACE_URI = 6;
74      public static final int FUNCTION_NAME = 7;
75      public static final int FUNCTION_STRING = 8;
76      public static final int FUNCTION_CONCAT = 9;
77      public static final int FUNCTION_STARTS_WITH = 10;
78      public static final int FUNCTION_CONTAINS = 11;
79      public static final int FUNCTION_SUBSTRING_BEFORE = 12;
80      public static final int FUNCTION_SUBSTRING_AFTER = 13;
81      public static final int FUNCTION_SUBSTRING = 14;
82      public static final int FUNCTION_STRING_LENGTH = 15;
83      public static final int FUNCTION_NORMALIZE_SPACE = 16;
84      public static final int FUNCTION_TRANSLATE = 17;
85      public static final int FUNCTION_BOOLEAN = 18;
86      public static final int FUNCTION_NOT = 19;
87      public static final int FUNCTION_TRUE = 20;
88      public static final int FUNCTION_FALSE = 21;
89      public static final int FUNCTION_LANG = 22;
90      public static final int FUNCTION_NUMBER = 23;
91      public static final int FUNCTION_SUM = 24;
92      public static final int FUNCTION_FLOOR = 25;
93      public static final int FUNCTION_CEILING = 26;
94      public static final int FUNCTION_ROUND = 27;
95      public static final int FUNCTION_NULL = 28;
96      public static final int FUNCTION_KEY = 29;
97      public static final int FUNCTION_FORMAT_NUMBER = 30;
98  
99      /***
100      * Produces an EXPRESSION object that represents a numeric constant.
101      */
102     Object number(String value);
103 
104     /***
105      * Produces an EXPRESSION object that represents a string constant.
106      */
107     Object literal(String value);
108 
109     /***
110      * Produces an QNAME that represents a name with an optional prefix.
111      */
112     Object qname(String prefix, String name);
113 
114     /***
115      * Produces an EXPRESSION object representing the sum of all argumens
116      *
117      * @param arguments are EXPRESSION objects
118      */
119     Object sum(Object[] arguments);
120 
121     /***
122      * Produces an EXPRESSION object representing <i>left</i> minus <i>right</i>
123      *
124      * @param left is an EXPRESSION object
125      * @param right is an EXPRESSION object
126      */
127     Object minus(Object left, Object right);
128 
129     /***
130      * Produces  an EXPRESSION object representing <i>left</i> multiplied by
131      * <i>right</i>
132      *
133      * @param left is an EXPRESSION object
134      * @param right is an EXPRESSION object
135      */
136     Object multiply(Object left, Object right);
137 
138     /***
139      * Produces  an EXPRESSION object representing <i>left</i> divided by
140      * <i>right</i>
141      *
142      * @param left is an EXPRESSION object
143      * @param right is an EXPRESSION object
144      */
145     Object divide(Object left, Object right);
146 
147     /***
148      * Produces  an EXPRESSION object representing <i>left</i> modulo
149      * <i>right</i>
150      *
151      * @param left is an EXPRESSION object
152      * @param right is an EXPRESSION object
153      */
154     Object mod(Object left, Object right);
155 
156     /***
157      * Produces an EXPRESSION object representing the comparison:
158      * <i>left</i> less than <i>right</i>
159      *
160      * @param left is an EXPRESSION object
161      * @param right is an EXPRESSION object
162      */
163     Object lessThan(Object left, Object right);
164 
165     /***
166      * Produces an EXPRESSION object representing the comparison:
167      * <i>left</i> less than or equal to <i>right</i>
168      *
169      * @param left is an EXPRESSION object
170      * @param right is an EXPRESSION object
171      */
172     Object lessThanOrEqual(Object left, Object right);
173 
174     /***
175      * Produces an EXPRESSION object representing the comparison:
176      * <i>left</i> greater than <i>right</i>
177      *
178      * @param left is an EXPRESSION object
179      * @param right is an EXPRESSION object
180      */
181     Object greaterThan(Object left, Object right);
182 
183     /***
184      * Produces an EXPRESSION object representing the comparison:
185      * <i>left</i> greater than or equal to <i>right</i>
186      *
187      * @param left is an EXPRESSION object
188      * @param right is an EXPRESSION object
189      */
190     Object greaterThanOrEqual(Object left, Object right);
191 
192     /***
193      * Produces an EXPRESSION object representing the comparison:
194      * <i>left</i> equals to <i>right</i>
195      *
196      * @param left is an EXPRESSION object
197      * @param right is an EXPRESSION object
198      */
199     Object equal(Object left, Object right);
200 
201     /***
202      * Produces an EXPRESSION object representing the comparison:
203      * <i>left</i> is not equal to <i>right</i>
204      *
205      * @param left is an EXPRESSION object
206      * @param right is an EXPRESSION object
207      */
208     Object notEqual(Object left, Object right);
209 
210     /***
211      * Produces an EXPRESSION object representing unary negation of the argument
212      *
213      * @param argument is an EXPRESSION object
214      */
215     Object minus(Object argument);
216 
217     /***
218      * Produces an EXPRESSION object representing variable reference
219      *
220      * @param qname is a QNAME object
221      */
222     Object variableReference(Object qName);
223 
224     /***
225      * Produces an EXPRESSION object representing the computation of
226      * a core function with the supplied arguments.
227      *
228      * @param code is one of FUNCTION_... constants
229      * @param args are EXPRESSION objects
230      */
231     Object function(int code, Object[] args);
232 
233     /***
234      * Produces an EXPRESSION object representing the computation of
235      * a library function with the supplied arguments.
236      *
237      * @param name is a QNAME object (function name)
238      * @param args are EXPRESSION objects
239      */
240     Object function(Object name, Object[] args);
241 
242     /***
243      * Produces an EXPRESSION object representing logical conjunction of
244      * all arguments
245      *
246      * @param arguments are EXPRESSION objects
247      */
248     Object and(Object arguments[]);
249 
250     /***
251      * Produces an EXPRESSION object representing logical disjunction of
252      * all arguments
253      *
254      * @param arguments are EXPRESSION objects
255      */
256     Object or(Object arguments[]);
257 
258     /***
259      * Produces an EXPRESSION object representing union of all node sets
260      *
261      * @param arguments are EXPRESSION objects
262      */
263     Object union(Object[] arguments);
264 
265     /***
266      * Produces a NODE_TEST object that represents a node name test.
267      *
268      * @param qname is a QNAME object
269      */
270     Object nodeNameTest(Object qname);
271 
272     /***
273      * Produces a NODE_TEST object that represents a node type test.
274      *
275      * @param qname is a QNAME object
276      */
277     Object nodeTypeTest(int nodeType);
278 
279     /***
280      * Produces  a NODE_TEST object that represents a processing instruction
281      * test.
282      *
283      * @param qname is a QNAME object
284      */
285     Object processingInstructionTest(String instruction);
286 
287     /***
288      * Produces a STEP object that represents a node test.
289      *
290      * @param axis is one of the AXIS_... constants
291      * @param nodeTest is a NODE_TEST object
292      * @param predicates are EXPRESSION objects
293      */
294     Object step(int axis, Object nodeTest, Object[] predicates);
295 
296     /***
297      * Produces an EXPRESSION object representing a location path
298      *
299      * @param absolute indicates whether the path is absolute
300      * @param steps are STEP objects
301      */
302     Object locationPath(boolean absolute, Object[] steps);
303 
304     /***
305      * Produces an EXPRESSION object representing a filter expression
306      *
307      * @param expression is an EXPRESSION object
308      * @param predicates are EXPRESSION objects
309      * @param steps are STEP objects
310      */
311     Object expressionPath(
312         Object expression,
313         Object[] predicates,
314         Object[] steps);
315 }