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. }