View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.jexl3;
19  
20  import java.util.List;
21  import java.util.Map;
22  import java.util.Set;
23  import java.util.concurrent.Callable;
24  
25  /**
26   * A JEXL Script.
27   *
28   * <p>A script is some valid JEXL syntax to be executed with a given set of {@link JexlContext} variables.</p>
29   *
30   * <p>A script is a group of statements, separated by semicolons.</p>
31   *
32   * <p>The statements can be <code>blocks</code> (curly braces containing code),
33   * Control statements such as <code>if</code> and <code>while</code>
34   * as well as expressions and assignment statements.</p>
35   *
36   * <p>Do <em>not</em> create classes that implement this interface; delegate or compose instead.</p>
37   *
38   * @since 1.1
39   */
40  public interface JexlScript {
41  
42       /**
43       * Returns the source text of this expression.
44        *
45       * @return the source text
46       */
47      String getSourceText();
48  
49      /**
50       * Recreates the source text of this expression from the internal syntactic tree.
51       *
52       * @return the source text
53       */
54      String getParsedText();
55  
56      /**
57       * Recreates the source text of this expression from the internal syntactic tree.
58       *
59       * @param indent the number of spaces for indentation, 0 meaning no indentation
60       * @return the source text
61       */
62      String getParsedText(int indent);
63  
64      /**
65       * Executes the script with the variables contained in the
66       * supplied {@link JexlContext}.
67       *
68       * @param context A JexlContext containing variables.
69       * @return The result of this script, usually the result of
70       *         the last statement.
71       */
72      Object execute(JexlContext context);
73  
74      /**
75       * Executes the script with the variables contained in the
76       * supplied {@link JexlContext} and a set of arguments corresponding to the
77       * parameters used during parsing.
78       *
79       * @param context A JexlContext containing variables.
80       * @param args the arguments
81       * @return The result of this script, usually the result of
82       *         the last statement.
83       * @since 2.1
84       */
85      Object execute(JexlContext context, Object... args);
86  
87      /**
88       * Gets this script parameters.
89       *
90       * @return the parameters or null
91       * @since 2.1
92       */
93      String[] getParameters();
94  
95      /**
96       * Gets this script unbound parameters.
97       * <p>Parameters that haven't been bound by a previous call to curry().</p>
98       * @return the parameters or null
99       * @since 3.2
100      */
101     String[] getUnboundParameters();
102 
103     /**
104      * Gets this script local variables.
105      *
106      * @return the local variables or null
107      * @since 2.1
108      */
109     String[] getLocalVariables();
110 
111     /**
112      * Gets this script variables.
113      * <p>Note that since variables can be in an ant-ish form (ie foo.bar.quux), each variable is returned as
114      * a list of strings where each entry is a fragment of the variable ({"foo", "bar", "quux"} in the example.</p>
115      *
116      * @return the variables or null
117      * @since 2.1
118      */
119     Set<List<String>> getVariables();
120 
121     /**
122      * Gets this script pragmas.
123      *
124      * @return the (non null, may be empty) pragmas map
125      */
126     Map<String, Object> getPragmas();
127 
128     /**
129      * Creates a Callable from this script.
130      *
131      * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
132      * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
133      *
134      * @param context the context
135      * @return the callable
136      * @since 2.1
137      */
138     Callable<Object> callable(JexlContext context);
139 
140     /**
141      * Creates a Callable from this script.
142      *
143      * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
144      * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
145      *
146      * @param context the context
147      * @param args the script arguments
148      * @return the callable
149      * @since 2.1
150      */
151     Callable<Object> callable(JexlContext context, Object... args);
152 
153     /**
154      * Curries this script, returning a script with bound arguments.
155      *
156      * <p>If this script does not declare parameters or if all of them are already bound,
157      * no error is generated and this script is returned.</p>
158      *
159      * @param args the arguments to bind
160      * @return the curried script or this script if no binding can occur
161      */
162     JexlScript curry(Object... args);
163 }