001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.jxpath.ri;
018
019 /**
020 * The Compiler APIs are completely agnostic to the actual types of objects
021 * produced and consumed by the APIs. Arguments and return values are
022 * declared as java.lang.Object.
023 * <p>
024 * Since objects returned by Compiler methods are passed as arguments to other
025 * Compiler methods, the descriptions of these methods use virtual types. There
026 * are four virtual object types: EXPRESSION, QNAME, STEP and NODE_TEST.
027 * <p>
028 * The following example illustrates this notion. This sequence compiles
029 * the xpath "foo[round(1 div 2)]/text()":
030 * <blockquote><pre>
031 * Object qname1 = compiler.qname(null, "foo")
032 * Object expr1 = compiler.number("1");
033 * Object expr2 = compiler.number("2");
034 * Object expr3 = compiler.div(expr1, expr2);
035 * Object expr4 = compiler.
036 * coreFunction(Compiler.FUNCTION_ROUND, new Object[]{expr3});
037 * Object test1 = compiler.nodeNameTest(qname1);
038 * Object step1 = compiler.
039 * step(Compiler.AXIS_CHILD, test1, new Object[]{expr4});
040 * Object test2 = compiler.nodeTypeTest(Compiler.NODE_TYPE_TEXT);
041 * Object step2 = compiler.nodeTypeTest(Compiler.AXIS_CHILD, test2, null);
042 * Object expr5 = compiler.locationPath(false, new Object[]{step1, step2});
043 * </pre></blockquote>
044 *
045 * @author Dmitri Plotnikov
046 * @version $Revision: 652845 $ $Date: 2008-05-02 12:46:46 -0500 (Fri, 02 May 2008) $
047 */
048 public interface Compiler {
049
050 public static final int NODE_TYPE_NODE = 1;
051 public static final int NODE_TYPE_TEXT = 2;
052 public static final int NODE_TYPE_COMMENT = 3;
053 public static final int NODE_TYPE_PI = 4;
054
055 public static final int AXIS_SELF = 1;
056 public static final int AXIS_CHILD = 2;
057 public static final int AXIS_PARENT = 3;
058 public static final int AXIS_ANCESTOR = 4;
059 public static final int AXIS_ATTRIBUTE = 5;
060 public static final int AXIS_NAMESPACE = 6;
061 public static final int AXIS_PRECEDING = 7;
062 public static final int AXIS_FOLLOWING = 8;
063 public static final int AXIS_DESCENDANT = 9;
064 public static final int AXIS_ANCESTOR_OR_SELF = 10;
065 public static final int AXIS_FOLLOWING_SIBLING = 11;
066 public static final int AXIS_PRECEDING_SIBLING = 12;
067 public static final int AXIS_DESCENDANT_OR_SELF = 13;
068
069 public static final int FUNCTION_LAST = 1;
070 public static final int FUNCTION_POSITION = 2;
071 public static final int FUNCTION_COUNT = 3;
072 public static final int FUNCTION_ID = 4;
073 public static final int FUNCTION_LOCAL_NAME = 5;
074 public static final int FUNCTION_NAMESPACE_URI = 6;
075 public static final int FUNCTION_NAME = 7;
076 public static final int FUNCTION_STRING = 8;
077 public static final int FUNCTION_CONCAT = 9;
078 public static final int FUNCTION_STARTS_WITH = 10;
079 public static final int FUNCTION_CONTAINS = 11;
080 public static final int FUNCTION_SUBSTRING_BEFORE = 12;
081 public static final int FUNCTION_SUBSTRING_AFTER = 13;
082 public static final int FUNCTION_SUBSTRING = 14;
083 public static final int FUNCTION_STRING_LENGTH = 15;
084 public static final int FUNCTION_NORMALIZE_SPACE = 16;
085 public static final int FUNCTION_TRANSLATE = 17;
086 public static final int FUNCTION_BOOLEAN = 18;
087 public static final int FUNCTION_NOT = 19;
088 public static final int FUNCTION_TRUE = 20;
089 public static final int FUNCTION_FALSE = 21;
090 public static final int FUNCTION_LANG = 22;
091 public static final int FUNCTION_NUMBER = 23;
092 public static final int FUNCTION_SUM = 24;
093 public static final int FUNCTION_FLOOR = 25;
094 public static final int FUNCTION_CEILING = 26;
095 public static final int FUNCTION_ROUND = 27;
096 public static final int FUNCTION_NULL = 28;
097 public static final int FUNCTION_KEY = 29;
098 public static final int FUNCTION_FORMAT_NUMBER = 30;
099
100 /**
101 * Produces an EXPRESSION object that represents a numeric constant.
102 * @param value numeric String
103 * @return Object
104 */
105 Object number(String value);
106
107 /**
108 * Produces an EXPRESSION object that represents a string constant.
109 * @param value String literal
110 * @return Object
111 */
112 Object literal(String value);
113
114 /**
115 * Produces an QNAME that represents a name with an optional prefix.
116 * @param prefix String prefix
117 * @param name String name
118 * @return Object
119 */
120 Object qname(String prefix, String name);
121
122 /**
123 * Produces an EXPRESSION object representing the sum of all argumens
124 *
125 * @param arguments are EXPRESSION objects
126 * @return Object
127 */
128 Object sum(Object[] arguments);
129
130 /**
131 * Produces an EXPRESSION object representing <i>left</i> minus <i>right</i>
132 *
133 * @param left is an EXPRESSION object
134 * @param right is an EXPRESSION object
135 * @return Object
136 */
137 Object minus(Object left, Object right);
138
139 /**
140 * Produces an EXPRESSION object representing <i>left</i> multiplied by
141 * <i>right</i>
142 *
143 * @param left is an EXPRESSION object
144 * @param right is an EXPRESSION object
145 * @return Object
146 */
147 Object multiply(Object left, Object right);
148
149 /**
150 * Produces an EXPRESSION object representing <i>left</i> divided by
151 * <i>right</i>
152 *
153 * @param left is an EXPRESSION object
154 * @param right is an EXPRESSION object
155 * @return Object
156 */
157 Object divide(Object left, Object right);
158
159 /**
160 * Produces an EXPRESSION object representing <i>left</i> modulo
161 * <i>right</i>
162 *
163 * @param left is an EXPRESSION object
164 * @param right is an EXPRESSION object
165 * @return Object
166 */
167 Object mod(Object left, Object right);
168
169 /**
170 * Produces an EXPRESSION object representing the comparison:
171 * <i>left</i> less than <i>right</i>
172 *
173 * @param left is an EXPRESSION object
174 * @param right is an EXPRESSION object
175 * @return Object
176 */
177 Object lessThan(Object left, Object right);
178
179 /**
180 * Produces an EXPRESSION object representing the comparison:
181 * <i>left</i> less than or equal to <i>right</i>
182 *
183 * @param left is an EXPRESSION object
184 * @param right is an EXPRESSION object
185 * @return Object
186 */
187 Object lessThanOrEqual(Object left, Object right);
188
189 /**
190 * Produces an EXPRESSION object representing the comparison:
191 * <i>left</i> greater than <i>right</i>
192 *
193 * @param left is an EXPRESSION object
194 * @param right is an EXPRESSION object
195 * @return Object
196 */
197 Object greaterThan(Object left, Object right);
198
199 /**
200 * Produces an EXPRESSION object representing the comparison:
201 * <i>left</i> greater than or equal to <i>right</i>
202 *
203 * @param left is an EXPRESSION object
204 * @param right is an EXPRESSION object
205 * @return Object
206 */
207 Object greaterThanOrEqual(Object left, Object right);
208
209 /**
210 * Produces an EXPRESSION object representing the comparison:
211 * <i>left</i> equals to <i>right</i>
212 *
213 * @param left is an EXPRESSION object
214 * @param right is an EXPRESSION object
215 * @return Object
216 */
217 Object equal(Object left, Object right);
218
219 /**
220 * Produces an EXPRESSION object representing the comparison:
221 * <i>left</i> is not equal to <i>right</i>
222 *
223 * @param left is an EXPRESSION object
224 * @param right is an EXPRESSION object
225 * @return Object
226 */
227 Object notEqual(Object left, Object right);
228
229 /**
230 * Produces an EXPRESSION object representing unary negation of the argument
231 *
232 * @param argument is an EXPRESSION object
233 * @return Object
234 */
235 Object minus(Object argument);
236
237 /**
238 * Produces an EXPRESSION object representing variable reference
239 *
240 * @param qname is a QNAME object
241 * @return Object
242 */
243 Object variableReference(Object qname);
244
245 /**
246 * Produces an EXPRESSION object representing the computation of
247 * a core function with the supplied arguments.
248 *
249 * @param code is one of FUNCTION_... constants
250 * @param args are EXPRESSION objects
251 * @return Object
252 */
253 Object function(int code, Object[] args);
254
255 /**
256 * Produces an EXPRESSION object representing the computation of
257 * a library function with the supplied arguments.
258 *
259 * @param name is a QNAME object (function name)
260 * @param args are EXPRESSION objects
261 * @return Object
262 */
263 Object function(Object name, Object[] args);
264
265 /**
266 * Produces an EXPRESSION object representing logical conjunction of
267 * all arguments
268 *
269 * @param arguments are EXPRESSION objects
270 * @return Object
271 */
272 Object and(Object[] arguments);
273
274 /**
275 * Produces an EXPRESSION object representing logical disjunction of
276 * all arguments
277 *
278 * @param arguments are EXPRESSION objects
279 * @return Object
280 */
281 Object or(Object[] arguments);
282
283 /**
284 * Produces an EXPRESSION object representing union of all node sets
285 *
286 * @param arguments are EXPRESSION objects
287 * @return Object
288 */
289 Object union(Object[] arguments);
290
291 /**
292 * Produces a NODE_TEST object that represents a node name test.
293 *
294 * @param qname is a QNAME object
295 * @return Object
296 */
297 Object nodeNameTest(Object qname);
298
299 /**
300 * Produces a NODE_TEST object that represents a node type test.
301 *
302 * @param nodeType is a NODE_TEST object
303 * @return Object
304 */
305 Object nodeTypeTest(int nodeType);
306
307 /**
308 * Produces a NODE_TEST object that represents a processing instruction
309 * test.
310 *
311 * @param instruction is a NODE_TEST object
312 * @return Object
313 */
314 Object processingInstructionTest(String instruction);
315
316 /**
317 * Produces a STEP object that represents a node test.
318 *
319 * @param axis is one of the AXIS_... constants
320 * @param nodeTest is a NODE_TEST object
321 * @param predicates are EXPRESSION objects
322 * @return Object
323 */
324 Object step(int axis, Object nodeTest, Object[] predicates);
325
326 /**
327 * Produces an EXPRESSION object representing a location path
328 *
329 * @param absolute indicates whether the path is absolute
330 * @param steps are STEP objects
331 * @return Object
332 */
333 Object locationPath(boolean absolute, Object[] steps);
334
335 /**
336 * Produces an EXPRESSION object representing a filter expression
337 *
338 * @param expression is an EXPRESSION object
339 * @param predicates are EXPRESSION objects
340 * @param steps are STEP objects
341 * @return Object
342 */
343 Object expressionPath(
344 Object expression,
345 Object[] predicates,
346 Object[] steps);
347 }