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 }