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