View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.jxpath.ri;
19  
20  /**
21   * The Compiler APIs are completely agnostic to the actual types of objects produced and consumed by the APIs. Arguments and return values are declared as
22   * java.lang.Object.
23   * <p>
24   * Since objects returned by Compiler methods are passed as arguments to other Compiler methods, the descriptions of these methods use virtual types. There are
25   * four virtual object types: EXPRESSION, QNAME, STEP and NODE_TEST.
26   * <p>
27   * The following example illustrates this notion. This sequence compiles the XPath "foo[round(1 div 2)]/text()": <blockquote>
28   *
29   * <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>
43   *
44   * </blockquote>
45   */
46  public interface Compiler {
47  
48      /** Constant {@value} */
49      int NODE_TYPE_NODE = 1;
50  
51      /** Constant {@value} */
52      int NODE_TYPE_TEXT = 2;
53  
54      /** Constant {@value} */
55      int NODE_TYPE_COMMENT = 3;
56  
57      /** Constant {@value} */
58      int NODE_TYPE_PI = 4;
59  
60      /** Constant {@value} */
61      int AXIS_SELF = 1;
62  
63      /** Constant {@value} */
64      int AXIS_CHILD = 2;
65  
66      /** Constant {@value} */
67      int AXIS_PARENT = 3;
68  
69      /** Constant {@value} */
70      int AXIS_ANCESTOR = 4;
71  
72      /** Constant {@value} */
73      int AXIS_ATTRIBUTE = 5;
74  
75      /** Constant {@value} */
76      int AXIS_NAMESPACE = 6;
77  
78      /** Constant {@value} */
79      int AXIS_PRECEDING = 7;
80  
81      /** Constant {@value} */
82      int AXIS_FOLLOWING = 8;
83  
84      /** Constant {@value} */
85      int AXIS_DESCENDANT = 9;
86  
87      /** Constant {@value} */
88      int AXIS_ANCESTOR_OR_SELF = 10;
89  
90      /** Constant {@value} */
91      int AXIS_FOLLOWING_SIBLING = 11;
92  
93      /** Constant {@value} */
94      int AXIS_PRECEDING_SIBLING = 12;
95  
96      /** Constant {@value} */
97      int AXIS_DESCENDANT_OR_SELF = 13;
98  
99      /** Constant {@value} */
100     int FUNCTION_LAST = 1;
101 
102     /** Constant {@value} */
103     int FUNCTION_POSITION = 2;
104 
105     /** Constant {@value} */
106     int FUNCTION_COUNT = 3;
107 
108     /** Constant {@value} */
109     int FUNCTION_ID = 4;
110 
111     /** Constant {@value} */
112     int FUNCTION_LOCAL_NAME = 5;
113 
114     /** Constant {@value} */
115     int FUNCTION_NAMESPACE_URI = 6;
116 
117     /** Constant {@value} */
118     int FUNCTION_NAME = 7;
119 
120     /** Constant {@value} */
121     int FUNCTION_STRING = 8;
122 
123     /** Constant {@value} */
124     int FUNCTION_CONCAT = 9;
125 
126     /** Constant {@value} */
127     int FUNCTION_STARTS_WITH = 10;
128 
129     /** Constant {@value} */
130     int FUNCTION_CONTAINS = 11;
131 
132     /** Constant {@value} */
133     int FUNCTION_SUBSTRING_BEFORE = 12;
134 
135     /** Constant {@value} */
136     int FUNCTION_SUBSTRING_AFTER = 13;
137 
138     /** Constant {@value} */
139     int FUNCTION_SUBSTRING = 14;
140 
141     /** Constant {@value} */
142     int FUNCTION_STRING_LENGTH = 15;
143 
144     /** Constant {@value} */
145     int FUNCTION_NORMALIZE_SPACE = 16;
146 
147     /** Constant {@value} */
148     int FUNCTION_TRANSLATE = 17;
149 
150     /** Constant {@value} */
151     int FUNCTION_BOOLEAN = 18;
152 
153     /** Constant {@value} */
154     int FUNCTION_NOT = 19;
155 
156     /** Constant {@value} */
157     int FUNCTION_TRUE = 20;
158 
159     /** Constant {@value} */
160     int FUNCTION_FALSE = 21;
161 
162     /** Constant {@value} */
163     int FUNCTION_LANG = 22;
164 
165     /** Constant {@value} */
166     int FUNCTION_NUMBER = 23;
167 
168     /** Constant {@value} */
169     int FUNCTION_SUM = 24;
170 
171     /** Constant {@value} */
172     int FUNCTION_FLOOR = 25;
173 
174     /** Constant {@value} */
175     int FUNCTION_CEILING = 26;
176 
177     /** Constant {@value} */
178     int FUNCTION_ROUND = 27;
179 
180     /** Constant {@value} */
181     int FUNCTION_NULL = 28;
182 
183     /** Constant {@value} */
184     int FUNCTION_KEY = 29;
185 
186     /** Constant {@value} */
187     int FUNCTION_FORMAT_NUMBER = 30;
188 
189     /** Constant {@value} */
190     int FUNCTION_ENDS_WITH = 31;
191 
192     /**
193      * Produces an EXPRESSION object representing logical conjunction of all arguments
194      *
195      * @param arguments are EXPRESSION objects
196      * @return Object
197      */
198     Object and(Object[] arguments);
199 
200     /**
201      * Produces an EXPRESSION object representing <em>left</em> divided by <em>right</em>
202      *
203      * @param left  is an EXPRESSION object
204      * @param right is an EXPRESSION object
205      * @return Object
206      */
207     Object divide(Object left, Object right);
208 
209     /**
210      * Produces an EXPRESSION object representing the comparison: <em>left</em> equals to <em>right</em>
211      *
212      * @param left  is an EXPRESSION object
213      * @param right is an EXPRESSION object
214      * @return Object
215      */
216     Object equal(Object left, Object right);
217 
218     /**
219      * Produces an EXPRESSION object representing a filter expression
220      *
221      * @param expression is an EXPRESSION object
222      * @param predicates are EXPRESSION objects
223      * @param steps      are STEP objects
224      * @return Object
225      */
226     Object expressionPath(Object expression, Object[] predicates, Object[] steps);
227 
228     /**
229      * Produces an EXPRESSION object representing the computation of a core function with the supplied arguments.
230      *
231      * @param code is one of FUNCTION_... constants
232      * @param args are EXPRESSION objects
233      * @return Object
234      */
235     Object function(int code, Object[] args);
236 
237     /**
238      * Produces an EXPRESSION object representing the computation of a library function with the supplied arguments.
239      *
240      * @param name is a QNAME object (function name)
241      * @param args are EXPRESSION objects
242      * @return Object
243      */
244     Object function(Object name, Object[] args);
245 
246     /**
247      * Produces an EXPRESSION object representing the comparison: <em>left</em> greater than <em>right</em>
248      *
249      * @param left  is an EXPRESSION object
250      * @param right is an EXPRESSION object
251      * @return Object
252      */
253     Object greaterThan(Object left, Object right);
254 
255     /**
256      * Produces an EXPRESSION object representing the comparison: <em>left</em> greater than or equal to <em>right</em>
257      *
258      * @param left  is an EXPRESSION object
259      * @param right is an EXPRESSION object
260      * @return Object
261      */
262     Object greaterThanOrEqual(Object left, Object right);
263 
264     /**
265      * Produces an EXPRESSION object representing the comparison: <em>left</em> less than <em>right</em>
266      *
267      * @param left  is an EXPRESSION object
268      * @param right is an EXPRESSION object
269      * @return Object
270      */
271     Object lessThan(Object left, Object right);
272 
273     /**
274      * Produces an EXPRESSION object representing the comparison: <em>left</em> less than or equal to <em>right</em>
275      *
276      * @param left  is an EXPRESSION object
277      * @param right is an EXPRESSION object
278      * @return Object
279      */
280     Object lessThanOrEqual(Object left, Object right);
281 
282     /**
283      * Produces an EXPRESSION object that represents a string constant.
284      *
285      * @param value String literal
286      * @return Object
287      */
288     Object literal(String value);
289 
290     /**
291      * Produces an EXPRESSION object representing a location path
292      *
293      * @param absolute indicates whether the path is absolute
294      * @param steps    are STEP objects
295      * @return Object
296      */
297     Object locationPath(boolean absolute, Object[] steps);
298 
299     /**
300      * Produces an EXPRESSION object representing unary negation of the argument
301      *
302      * @param argument is an EXPRESSION object
303      * @return Object
304      */
305     Object minus(Object argument);
306 
307     /**
308      * Produces an EXPRESSION object representing <em>left</em> minus <em>right</em>
309      *
310      * @param left  is an EXPRESSION object
311      * @param right is an EXPRESSION object
312      * @return Object
313      */
314     Object minus(Object left, Object right);
315 
316     /**
317      * Produces an EXPRESSION object representing <em>left</em> modulo <em>right</em>
318      *
319      * @param left  is an EXPRESSION object
320      * @param right is an EXPRESSION object
321      * @return Object
322      */
323     Object mod(Object left, Object right);
324 
325     /**
326      * Produces an EXPRESSION object representing <em>left</em> multiplied by <em>right</em>
327      *
328      * @param left  is an EXPRESSION object
329      * @param right is an EXPRESSION object
330      * @return Object
331      */
332     Object multiply(Object left, Object right);
333 
334     /**
335      * Produces a NODE_TEST object that represents a node name test.
336      *
337      * @param qname is a QNAME object
338      * @return Object
339      */
340     Object nodeNameTest(Object qname);
341 
342     /**
343      * Produces a NODE_TEST object that represents a node type test.
344      *
345      * @param nodeType is a NODE_TEST object
346      * @return Object
347      */
348     Object nodeTypeTest(int nodeType);
349 
350     /**
351      * Produces an EXPRESSION object representing the comparison: <em>left</em> is not equal to <em>right</em>
352      *
353      * @param left  is an EXPRESSION object
354      * @param right is an EXPRESSION object
355      * @return Object
356      */
357     Object notEqual(Object left, Object right);
358 
359     /**
360      * Produces an EXPRESSION object that represents a numeric constant.
361      *
362      * @param value numeric String
363      * @return Object
364      */
365     Object number(String value);
366 
367     /**
368      * Produces an EXPRESSION object representing logical disjunction of all arguments
369      *
370      * @param arguments are EXPRESSION objects
371      * @return Object
372      */
373     Object or(Object[] arguments);
374 
375     /**
376      * Produces a NODE_TEST object that represents a processing instruction test.
377      *
378      * @param instruction is a NODE_TEST object
379      * @return Object
380      */
381     Object processingInstructionTest(String instruction);
382 
383     /**
384      * Produces an QNAME that represents a name with an optional prefix.
385      *
386      * @param prefix String prefix
387      * @param name   String name
388      * @return Object
389      */
390     Object qname(String prefix, String name);
391 
392     /**
393      * Produces a STEP object that represents a node test.
394      *
395      * @param axis       is one of the AXIS_... constants
396      * @param nodeTest   is a NODE_TEST object
397      * @param predicates are EXPRESSION objects
398      * @return Object
399      */
400     Object step(int axis, Object nodeTest, Object[] predicates);
401 
402     /**
403      * Produces an EXPRESSION object representing the sum of all argumens
404      *
405      * @param arguments are EXPRESSION objects
406      * @return Object
407      */
408     Object sum(Object[] arguments);
409 
410     /**
411      * Produces an EXPRESSION object representing union of all node sets
412      *
413      * @param arguments are EXPRESSION objects
414      * @return Object
415      */
416     Object union(Object[] arguments);
417 
418     /**
419      * Produces an EXPRESSION object representing variable reference
420      *
421      * @param qname is a QNAME object
422      * @return Object
423      */
424     Object variableReference(Object qname);
425 }