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    }