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 * Creates a Callable from this script.
44 *
45 * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
46 * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
47 *
48 * @param context the context
49 * @return the callable
50 * @since 2.1
51 */
52 Callable<Object> callable(JexlContext context);
53
54 /**
55 * Creates a Callable from this script.
56 *
57 * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
58 * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
59 *
60 * @param context the context
61 * @param args the script arguments
62 * @return the callable
63 * @since 2.1
64 */
65 Callable<Object> callable(JexlContext context, Object... args);
66
67 /**
68 * Curries this script, returning a script with bound arguments.
69 *
70 * <p>If this script does not declare parameters or if all of them are already bound,
71 * no error is generated and this script is returned.</p>
72 *
73 * @param args the arguments to bind
74 * @return the curried script or this script if no binding can occur
75 */
76 JexlScript curry(Object... args);
77
78 /**
79 * Executes the script with the variables contained in the
80 * supplied {@link JexlContext}.
81 *
82 * @param context A JexlContext containing variables.
83 * @return The result of this script, usually the result of
84 * the last statement.
85 */
86 Object execute(JexlContext context);
87
88 /**
89 * Executes the script with the variables contained in the
90 * supplied {@link JexlContext} and a set of arguments corresponding to the
91 * parameters used during parsing.
92 *
93 * @param context A JexlContext containing variables.
94 * @param args the arguments
95 * @return The result of this script, usually the result of
96 * the last statement.
97 * @since 2.1
98 */
99 Object execute(JexlContext context, Object... args);
100
101 /**
102 * Gets this script local variables.
103 *
104 * @return the local variables or null
105 * @since 2.1
106 */
107 String[] getLocalVariables();
108
109 /**
110 * Gets this script parameters.
111 *
112 * @return the parameters or null
113 * @since 2.1
114 */
115 String[] getParameters();
116
117 /**
118 * Recreates the source text of this expression from the internal syntactic tree.
119 *
120 * @return the source text
121 */
122 String getParsedText();
123
124 /**
125 * Recreates the source text of this expression from the internal syntactic tree.
126 *
127 * @param indent the number of spaces for indentation, 0 meaning no indentation
128 * @return the source text
129 */
130 String getParsedText(int indent);
131
132 /**
133 * Gets this script pragmas.
134 *
135 * @return the (non null, may be empty) pragmas map
136 */
137 Map<String, Object> getPragmas();
138
139 /**
140 * Returns the source text of this expression.
141 *
142 * @return the source text
143 */
144 String getSourceText();
145
146 /**
147 * Gets this script unbound parameters.
148 * <p>Parameters that haven't been bound by a previous call to curry().</p>
149 * @return the parameters or null
150 * @since 3.2
151 */
152 String[] getUnboundParameters();
153
154 /**
155 * Gets this script variables.
156 * <p>Note that since variables can be in an ant-ish form (ie foo.bar.quux), each variable is returned as
157 * a list of strings where each entry is a fragment of the variable ({"foo", "bar", "quux"} in the example.</p>
158 *
159 * @return the variables or null
160 * @since 2.1
161 */
162 Set<List<String>> getVariables();
163 }