    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
    018package org.apache.commons.jxpath.ri;
    019
    020/**
    021 * The Compiler APIs are completely agnostic to the actual types of objects produced and consumed by the APIs. Arguments and return values are declared as
    022 * java.lang.Object.
    023 * <p>
    024 * Since objects returned by Compiler methods are passed as arguments to other Compiler methods, the descriptions of these methods use virtual types. There are
    025 * four virtual object types: EXPRESSION, QNAME, STEP and NODE_TEST.
    026 * <p>
    027 * The following example illustrates this notion. This sequence compiles the XPath "foo[round(1 div 2)]/text()": <blockquote>
    028 *
    029 * <pre>
    030 *      Object qname1 = compiler.qname(null, "foo")
    031 *      Object expr1 = compiler.number("1");
    032 *      Object expr2 = compiler.number("2");
    033 *      Object expr3 = compiler.div(expr1, expr2);
    034 *      Object expr4 = compiler.
    035 *              coreFunction(Compiler.FUNCTION_ROUND, new Object[]{expr3});
    036 *      Object test1 = compiler.nodeNameTest(qname1);
    037 *      Object step1 = compiler.
    038 *              step(Compiler.AXIS_CHILD, test1, new Object[]{expr4});
    039 *      Object test2 = compiler.nodeTypeTest(Compiler.NODE_TYPE_TEXT);
    040 *      Object step2 = compiler.nodeTypeTest(Compiler.AXIS_CHILD, test2, null);
    041 *      Object expr5 = compiler.locationPath(false, new Object[]{step1, step2});
    042 * </pre>
    043 *
    044 * </blockquote>
    045 */
    046public interface Compiler {
    047
    048    /** Constant {@value} */
    049    int NODE_TYPE_NODE = 1;
    050
    051    /** Constant {@value} */
    052    int NODE_TYPE_TEXT = 2;
    053
    054    /** Constant {@value} */
    055    int NODE_TYPE_COMMENT = 3;
    056
    057    /** Constant {@value} */
    058    int NODE_TYPE_PI = 4;
    059
    060    /** Constant {@value} */
    061    int AXIS_SELF = 1;
    062
    063    /** Constant {@value} */
    064    int AXIS_CHILD = 2;
    065
    066    /** Constant {@value} */
    067    int AXIS_PARENT = 3;
    068
    069    /** Constant {@value} */
    070    int AXIS_ANCESTOR = 4;
    071
    072    /** Constant {@value} */
    073    int AXIS_ATTRIBUTE = 5;
    074
    075    /** Constant {@value} */
    076    int AXIS_NAMESPACE = 6;
    077
    078    /** Constant {@value} */
    079    int AXIS_PRECEDING = 7;
    080
    081    /** Constant {@value} */
    082    int AXIS_FOLLOWING = 8;
    083
    084    /** Constant {@value} */
    085    int AXIS_DESCENDANT = 9;
    086
    087    /** Constant {@value} */
    088    int AXIS_ANCESTOR_OR_SELF = 10;
    089
    090    /** Constant {@value} */
    091    int AXIS_FOLLOWING_SIBLING = 11;
    092
    093    /** Constant {@value} */
    094    int AXIS_PRECEDING_SIBLING = 12;
    095
    096    /** Constant {@value} */
    097    int AXIS_DESCENDANT_OR_SELF = 13;
    098
    099    /** Constant {@value} */
    100    int FUNCTION_LAST = 1;
    101
    102    /** Constant {@value} */
    103    int FUNCTION_POSITION = 2;
    104
    105    /** Constant {@value} */
    106    int FUNCTION_COUNT = 3;
    107
    108    /** Constant {@value} */
    109    int FUNCTION_ID = 4;
    110
    111    /** Constant {@value} */
    112    int FUNCTION_LOCAL_NAME = 5;
    113
    114    /** Constant {@value} */
    115    int FUNCTION_NAMESPACE_URI = 6;
    116
    117    /** Constant {@value} */
    118    int FUNCTION_NAME = 7;
    119
    120    /** Constant {@value} */
    121    int FUNCTION_STRING = 8;
    122
    123    /** Constant {@value} */
    124    int FUNCTION_CONCAT = 9;
    125
    126    /** Constant {@value} */
    127    int FUNCTION_STARTS_WITH = 10;
    128
    129    /** Constant {@value} */
    130    int FUNCTION_CONTAINS = 11;
    131
    132    /** Constant {@value} */
    133    int FUNCTION_SUBSTRING_BEFORE = 12;
    134
    135    /** Constant {@value} */
    136    int FUNCTION_SUBSTRING_AFTER = 13;
    137
    138    /** Constant {@value} */
    139    int FUNCTION_SUBSTRING = 14;
    140
    141    /** Constant {@value} */
    142    int FUNCTION_STRING_LENGTH = 15;
    143
    144    /** Constant {@value} */
    145    int FUNCTION_NORMALIZE_SPACE = 16;
    146
    147    /** Constant {@value} */
    148    int FUNCTION_TRANSLATE = 17;
    149
    150    /** Constant {@value} */
    151    int FUNCTION_BOOLEAN = 18;
    152
    153    /** Constant {@value} */
    154    int FUNCTION_NOT = 19;
    155
    156    /** Constant {@value} */
    157    int FUNCTION_TRUE = 20;
    158
    159    /** Constant {@value} */
    160    int FUNCTION_FALSE = 21;
    161
    162    /** Constant {@value} */
    163    int FUNCTION_LANG = 22;
    164
    165    /** Constant {@value} */
    166    int FUNCTION_NUMBER = 23;
    167
    168    /** Constant {@value} */
    169    int FUNCTION_SUM = 24;
    170
    171    /** Constant {@value} */
    172    int FUNCTION_FLOOR = 25;
    173
    174    /** Constant {@value} */
    175    int FUNCTION_CEILING = 26;
    176
    177    /** Constant {@value} */
    178    int FUNCTION_ROUND = 27;
    179
    180    /** Constant {@value} */
    181    int FUNCTION_NULL = 28;
    182
    183    /** Constant {@value} */
    184    int FUNCTION_KEY = 29;
    185
    186    /** Constant {@value} */
    187    int FUNCTION_FORMAT_NUMBER = 30;
    188
    189    /** Constant {@value} */
    190    int FUNCTION_ENDS_WITH = 31;
    191
    192    /**
    193     * Produces an EXPRESSION object representing logical conjunction of all arguments
    194     *
    195     * @param arguments are EXPRESSION objects
    196     * @return Object
    197     */
    198    Object and(Object[] arguments);
    199
    200    /**
    201     * Produces an EXPRESSION object representing <em>left</em> divided by <em>right</em>
    202     *
    203     * @param left  is an EXPRESSION object
    204     * @param right is an EXPRESSION object
    205     * @return Object
    206     */
    207    Object divide(Object left, Object right);
    208
    209    /**
    210     * Produces an EXPRESSION object representing the comparison: <em>left</em> equals to <em>right</em>
    211     *
    212     * @param left  is an EXPRESSION object
    213     * @param right is an EXPRESSION object
    214     * @return Object
    215     */
    216    Object equal(Object left, Object right);
    217
    218    /**
    219     * Produces an EXPRESSION object representing a filter expression
    220     *
    221     * @param expression is an EXPRESSION object
    222     * @param predicates are EXPRESSION objects
    223     * @param steps      are STEP objects
    224     * @return Object
    225     */
    226    Object expressionPath(Object expression, Object[] predicates, Object[] steps);
    227
    228    /**
    229     * Produces an EXPRESSION object representing the computation of a core function with the supplied arguments.
    230     *
    231     * @param code is one of FUNCTION_... constants
    232     * @param args are EXPRESSION objects
    233     * @return Object
    234     */
    235    Object function(int code, Object[] args);
    236
    237    /**
    238     * Produces an EXPRESSION object representing the computation of a library function with the supplied arguments.
    239     *
    240     * @param name is a QNAME object (function name)
    241     * @param args are EXPRESSION objects
    242     * @return Object
    243     */
    244    Object function(Object name, Object[] args);
    245
    246    /**
    247     * Produces an EXPRESSION object representing the comparison: <em>left</em> greater than <em>right</em>
    248     *
    249     * @param left  is an EXPRESSION object
    250     * @param right is an EXPRESSION object
    251     * @return Object
    252     */
    253    Object greaterThan(Object left, Object right);
    254
    255    /**
    256     * Produces an EXPRESSION object representing the comparison: <em>left</em> greater than or equal to <em>right</em>
    257     *
    258     * @param left  is an EXPRESSION object
    259     * @param right is an EXPRESSION object
    260     * @return Object
    261     */
    262    Object greaterThanOrEqual(Object left, Object right);
    263
    264    /**
    265     * Produces an EXPRESSION object representing the comparison: <em>left</em> less than <em>right</em>
    266     *
    267     * @param left  is an EXPRESSION object
    268     * @param right is an EXPRESSION object
    269     * @return Object
    270     */
    271    Object lessThan(Object left, Object right);
    272
    273    /**
    274     * Produces an EXPRESSION object representing the comparison: <em>left</em> less than or equal to <em>right</em>
    275     *
    276     * @param left  is an EXPRESSION object
    277     * @param right is an EXPRESSION object
    278     * @return Object
    279     */
    280    Object lessThanOrEqual(Object left, Object right);
    281
    282    /**
    283     * Produces an EXPRESSION object that represents a string constant.
    284     *
    285     * @param value String literal
    286     * @return Object
    287     */
    288    Object literal(String value);
    289
    290    /**
    291     * Produces an EXPRESSION object representing a location path
    292     *
    293     * @param absolute indicates whether the path is absolute
    294     * @param steps    are STEP objects
    295     * @return Object
    296     */
    297    Object locationPath(boolean absolute, Object[] steps);
    298
    299    /**
    300     * Produces an EXPRESSION object representing unary negation of the argument
    301     *
    302     * @param argument is an EXPRESSION object
    303     * @return Object
    304     */
    305    Object minus(Object argument);
    306
    307    /**
    308     * Produces an EXPRESSION object representing <em>left</em> minus <em>right</em>
    309     *
    310     * @param left  is an EXPRESSION object
    311     * @param right is an EXPRESSION object
    312     * @return Object
    313     */
    314    Object minus(Object left, Object right);
    315
    316    /**
    317     * Produces an EXPRESSION object representing <em>left</em> modulo <em>right</em>
    318     *
    319     * @param left  is an EXPRESSION object
    320     * @param right is an EXPRESSION object
    321     * @return Object
    322     */
    323    Object mod(Object left, Object right);
    324
    325    /**
    326     * Produces an EXPRESSION object representing <em>left</em> multiplied by <em>right</em>
    327     *
    328     * @param left  is an EXPRESSION object
    329     * @param right is an EXPRESSION object
    330     * @return Object
    331     */
    332    Object multiply(Object left, Object right);
    333
    334    /**
    335     * Produces a NODE_TEST object that represents a node name test.
    336     *
    337     * @param qname is a QNAME object
    338     * @return Object
    339     */
    340    Object nodeNameTest(Object qname);
    341
    342    /**
    343     * Produces a NODE_TEST object that represents a node type test.
    344     *
    345     * @param nodeType is a NODE_TEST object
    346     * @return Object
    347     */
    348    Object nodeTypeTest(int nodeType);
    349
    350    /**
    351     * Produces an EXPRESSION object representing the comparison: <em>left</em> is not equal to <em>right</em>
    352     *
    353     * @param left  is an EXPRESSION object
    354     * @param right is an EXPRESSION object
    355     * @return Object
    356     */
    357    Object notEqual(Object left, Object right);
    358
    359    /**
    360     * Produces an EXPRESSION object that represents a numeric constant.
    361     *
    362     * @param value numeric String
    363     * @return Object
    364     */
    365    Object number(String value);
    366
    367    /**
    368     * Produces an EXPRESSION object representing logical disjunction of all arguments
    369     *
    370     * @param arguments are EXPRESSION objects
    371     * @return Object
    372     */
    373    Object or(Object[] arguments);
    374
    375    /**
    376     * Produces a NODE_TEST object that represents a processing instruction test.
    377     *
    378     * @param instruction is a NODE_TEST object
    379     * @return Object
    380     */
    381    Object processingInstructionTest(String instruction);
    382
    383    /**
    384     * Produces an QNAME that represents a name with an optional prefix.
    385     *
    386     * @param prefix String prefix
    387     * @param name   String name
    388     * @return Object
    389     */
    390    Object qname(String prefix, String name);
    391
    392    /**
    393     * Produces a STEP object that represents a node test.
    394     *
    395     * @param axis       is one of the AXIS_... constants
    396     * @param nodeTest   is a NODE_TEST object
    397     * @param predicates are EXPRESSION objects
    398     * @return Object
    399     */
    400    Object step(int axis, Object nodeTest, Object[] predicates);
    401
    402    /**
    403     * Produces an EXPRESSION object representing the sum of all argumens
    404     *
    405     * @param arguments are EXPRESSION objects
    406     * @return Object
    407     */
    408    Object sum(Object[] arguments);
    409
    410    /**
    411     * Produces an EXPRESSION object representing union of all node sets
    412     *
    413     * @param arguments are EXPRESSION objects
    414     * @return Object
    415     */
    416    Object union(Object[] arguments);
    417
    418    /**
    419     * Produces an EXPRESSION object representing variable reference
    420     *
    421     * @param qname is a QNAME object
    422     * @return Object
    423     */
    424    Object variableReference(Object qname);
    425}