    1   /*
    2    * Copyright 1999-2004 The Apache Software Foundation
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *     http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  package org.apache.commons.jxpath.ri;
    17
    18  /***
    19   * The Compiler APIs are completely agnostic to the actual types of objects
    20   * produced and consumed by the APIs.  Arguments and return values are
    21   * declared as java.lang.Object.
    22   * <p>
    23   * Since  objects returned by Compiler methods are passed as arguments to other
    24   * Compiler methods, the descriptions of these methods use virtual types.  There
    25   * are four virtual object types: EXPRESSION, QNAME, STEP and NODE_TEST.
    26   * <p>
    27   * The following example illustrates this notion.  This sequence compiles
    28   * the xpath "foo[round(1 div 2)]/text()":
    29   * <blockquote><pre>
    30   *      Object qname1 = compiler.qname(null, "foo")
    31   *      Object expr1 = compiler.number("1");
    32   *      Object expr2 = compiler.number("2");
    33   *      Object expr3 = compiler.div(expr1, expr2);
    34   *      Object expr4 = compiler.
    35   *              coreFunction(Compiler.FUNCTION_ROUND, new Object[]{expr3});
    36   *      Object test1 = compiler.nodeNameTest(qname1);
    37   *      Object step1 = compiler.
    38   *              step(Compiler.AXIS_CHILD, test1, new Object[]{expr4});
    39   *      Object test2 = compiler.nodeTypeTest(Compiler.NODE_TYPE_TEXT);
    40   *      Object step2 = compiler.nodeTypeTest(Compiler.AXIS_CHILD, test2, null);
    41   *      Object expr5 = compiler.locationPath(false, new Object[]{step1, step2});
    42   * </pre></blockquote>
    43   *
    44   * @author Dmitri Plotnikov
    45   * @version $Revision: 1.9 $ $Date: 2004/02/29 14:17:45 $
    46   */
    47  public interface Compiler {
    48
    49      public static final int NODE_TYPE_NODE = 1;
    50      public static final int NODE_TYPE_TEXT = 2;
    51      public static final int NODE_TYPE_COMMENT = 3;
    52      public static final int NODE_TYPE_PI = 4;
    53
    54      public static final int AXIS_SELF = 1;
    55      public static final int AXIS_CHILD = 2;
    56      public static final int AXIS_PARENT = 3;
    57      public static final int AXIS_ANCESTOR = 4;
    58      public static final int AXIS_ATTRIBUTE = 5;
    59      public static final int AXIS_NAMESPACE = 6;
    60      public static final int AXIS_PRECEDING = 7;
    61      public static final int AXIS_FOLLOWING = 8;
    62      public static final int AXIS_DESCENDANT = 9;
    63      public static final int AXIS_ANCESTOR_OR_SELF = 10;
    64      public static final int AXIS_FOLLOWING_SIBLING = 11;
    65      public static final int AXIS_PRECEDING_SIBLING = 12;
    66      public static final int AXIS_DESCENDANT_OR_SELF = 13;
    67
    68      public static final int FUNCTION_LAST = 1;
    69      public static final int FUNCTION_POSITION = 2;
    70      public static final int FUNCTION_COUNT = 3;
    71      public static final int FUNCTION_ID = 4;
    72      public static final int FUNCTION_LOCAL_NAME = 5;
    73      public static final int FUNCTION_NAMESPACE_URI = 6;
    74      public static final int FUNCTION_NAME = 7;
    75      public static final int FUNCTION_STRING = 8;
    76      public static final int FUNCTION_CONCAT = 9;
    77      public static final int FUNCTION_STARTS_WITH = 10;
    78      public static final int FUNCTION_CONTAINS = 11;
    79      public static final int FUNCTION_SUBSTRING_BEFORE = 12;
    80      public static final int FUNCTION_SUBSTRING_AFTER = 13;
    81      public static final int FUNCTION_SUBSTRING = 14;
    82      public static final int FUNCTION_STRING_LENGTH = 15;
    83      public static final int FUNCTION_NORMALIZE_SPACE = 16;
    84      public static final int FUNCTION_TRANSLATE = 17;
    85      public static final int FUNCTION_BOOLEAN = 18;
    86      public static final int FUNCTION_NOT = 19;
    87      public static final int FUNCTION_TRUE = 20;
    88      public static final int FUNCTION_FALSE = 21;
    89      public static final int FUNCTION_LANG = 22;
    90      public static final int FUNCTION_NUMBER = 23;
    91      public static final int FUNCTION_SUM = 24;
    92      public static final int FUNCTION_FLOOR = 25;
    93      public static final int FUNCTION_CEILING = 26;
    94      public static final int FUNCTION_ROUND = 27;
    95      public static final int FUNCTION_NULL = 28;
    96      public static final int FUNCTION_KEY = 29;
    97      public static final int FUNCTION_FORMAT_NUMBER = 30;
    98
    99      /***
    100      * Produces an EXPRESSION object that represents a numeric constant.
    101      */
    102     Object number(String value);
    103
    104     /***
    105      * Produces an EXPRESSION object that represents a string constant.
    106      */
    107     Object literal(String value);
    108
    109     /***
    110      * Produces an QNAME that represents a name with an optional prefix.
    111      */
    112     Object qname(String prefix, String name);
    113
    114     /***
    115      * Produces an EXPRESSION object representing the sum of all argumens
    116      *
    117      * @param arguments are EXPRESSION objects
    118      */
    119     Object sum(Object[] arguments);
    120
    121     /***
    122      * Produces an EXPRESSION object representing <i>left</i> minus <i>right</i>
    123      *
    124      * @param left is an EXPRESSION object
    125      * @param right is an EXPRESSION object
    126      */
    127     Object minus(Object left, Object right);
    128
    129     /***
    130      * Produces  an EXPRESSION object representing <i>left</i> multiplied by
    131      * <i>right</i>
    132      *
    133      * @param left is an EXPRESSION object
    134      * @param right is an EXPRESSION object
    135      */
    136     Object multiply(Object left, Object right);
    137
    138     /***
    139      * Produces  an EXPRESSION object representing <i>left</i> divided by
    140      * <i>right</i>
    141      *
    142      * @param left is an EXPRESSION object
    143      * @param right is an EXPRESSION object
    144      */
    145     Object divide(Object left, Object right);
    146
    147     /***
    148      * Produces  an EXPRESSION object representing <i>left</i> modulo
    149      * <i>right</i>
    150      *
    151      * @param left is an EXPRESSION object
    152      * @param right is an EXPRESSION object
    153      */
    154     Object mod(Object left, Object right);
    155
    156     /***
    157      * Produces an EXPRESSION object representing the comparison:
    158      * <i>left</i> less than <i>right</i>
    159      *
    160      * @param left is an EXPRESSION object
    161      * @param right is an EXPRESSION object
    162      */
    163     Object lessThan(Object left, Object right);
    164
    165     /***
    166      * Produces an EXPRESSION object representing the comparison:
    167      * <i>left</i> less than or equal to <i>right</i>
    168      *
    169      * @param left is an EXPRESSION object
    170      * @param right is an EXPRESSION object
    171      */
    172     Object lessThanOrEqual(Object left, Object right);
    173
    174     /***
    175      * Produces an EXPRESSION object representing the comparison:
    176      * <i>left</i> greater than <i>right</i>
    177      *
    178      * @param left is an EXPRESSION object
    179      * @param right is an EXPRESSION object
    180      */
    181     Object greaterThan(Object left, Object right);
    182
    183     /***
    184      * Produces an EXPRESSION object representing the comparison:
    185      * <i>left</i> greater than or equal to <i>right</i>
    186      *
    187      * @param left is an EXPRESSION object
    188      * @param right is an EXPRESSION object
    189      */
    190     Object greaterThanOrEqual(Object left, Object right);
    191
    192     /***
    193      * Produces an EXPRESSION object representing the comparison:
    194      * <i>left</i> equals to <i>right</i>
    195      *
    196      * @param left is an EXPRESSION object
    197      * @param right is an EXPRESSION object
    198      */
    199     Object equal(Object left, Object right);
    200
    201     /***
    202      * Produces an EXPRESSION object representing the comparison:
    203      * <i>left</i> is not equal to <i>right</i>
    204      *
    205      * @param left is an EXPRESSION object
    206      * @param right is an EXPRESSION object
    207      */
    208     Object notEqual(Object left, Object right);
    209
    210     /***
    211      * Produces an EXPRESSION object representing unary negation of the argument
    212      *
    213      * @param argument is an EXPRESSION object
    214      */
    215     Object minus(Object argument);
    216
    217     /***
    218      * Produces an EXPRESSION object representing variable reference
    219      *
    220      * @param qname is a QNAME object
    221      */
    222     Object variableReference(Object qName);
    223
    224     /***
    225      * Produces an EXPRESSION object representing the computation of
    226      * a core function with the supplied arguments.
    227      *
    228      * @param code is one of FUNCTION_... constants
    229      * @param args are EXPRESSION objects
    230      */
    231     Object function(int code, Object[] args);
    232
    233     /***
    234      * Produces an EXPRESSION object representing the computation of
    235      * a library function with the supplied arguments.
    236      *
    237      * @param name is a QNAME object (function name)
    238      * @param args are EXPRESSION objects
    239      */
    240     Object function(Object name, Object[] args);
    241
    242     /***
    243      * Produces an EXPRESSION object representing logical conjunction of
    244      * all arguments
    245      *
    246      * @param arguments are EXPRESSION objects
    247      */
    248     Object and(Object arguments[]);
    249
    250     /***
    251      * Produces an EXPRESSION object representing logical disjunction of
    252      * all arguments
    253      *
    254      * @param arguments are EXPRESSION objects
    255      */
    256     Object or(Object arguments[]);
    257
    258     /***
    259      * Produces an EXPRESSION object representing union of all node sets
    260      *
    261      * @param arguments are EXPRESSION objects
    262      */
    263     Object union(Object[] arguments);
    264
    265     /***
    266      * Produces a NODE_TEST object that represents a node name test.
    267      *
    268      * @param qname is a QNAME object
    269      */
    270     Object nodeNameTest(Object qname);
    271
    272     /***
    273      * Produces a NODE_TEST object that represents a node type test.
    274      *
    275      * @param qname is a QNAME object
    276      */
    277     Object nodeTypeTest(int nodeType);
    278
    279     /***
    280      * Produces  a NODE_TEST object that represents a processing instruction
    281      * test.
    282      *
    283      * @param qname is a QNAME object
    284      */
    285     Object processingInstructionTest(String instruction);
    286
    287     /***
    288      * Produces a STEP object that represents a node test.
    289      *
    290      * @param axis is one of the AXIS_... constants
    291      * @param nodeTest is a NODE_TEST object
    292      * @param predicates are EXPRESSION objects
    293      */
    294     Object step(int axis, Object nodeTest, Object[] predicates);
    295
    296     /***
    297      * Produces an EXPRESSION object representing a location path
    298      *
    299      * @param absolute indicates whether the path is absolute
    300      * @param steps are STEP objects
    301      */
    302     Object locationPath(boolean absolute, Object[] steps);
    303
    304     /***
    305      * Produces an EXPRESSION object representing a filter expression
    306      *
    307      * @param expression is an EXPRESSION object
    308      * @param predicates are EXPRESSION objects
    309      * @param steps are STEP objects
    310      */
    311     Object expressionPath(
    312         Object expression,
    313         Object[] predicates,
    314         Object[] steps);
    315 }