    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    }