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 */
017package 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: 1234255 $ $Date: 2012-01-21 04:11:46 +0100 (Sa, 21 Jan 2012) $
047 */
048public 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    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}