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: 652845 $ $Date: 2008-05-02 12:46:46 -0500 (Fri, 02 May 2008) $
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    /**
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}