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.concurrent.Callable;
21 import java.util.concurrent.atomic.AtomicBoolean;
22
23 /**
24 * Manages variables which can be referenced in a JEXL expression.
25 *
26 * <p>JEXL variable names in their simplest form are 'java-like' identifiers.
27 * JEXL also considers 'ant' inspired variables expressions as valid.
28 * For instance, the expression 'x.y.z' is an 'antish' variable and will be resolved as a whole by the context,
29 * i.e. using the key "x.y.z". This proves to be useful to solve "fully qualified class names".</p>
30 *
31 * <p>The interpreter variable resolution algorithm will try the different sequences of identifiers till it finds
32 * one that exists in the context; if "x" is an object known in the context (JexlContext.has("x") returns true),
33 * "x.y" will <em>not</em> be looked up in the context but will most likely refer to "x.getY()".</p>
34 *
35 * <p>Note that JEXL may use '$jexl' and '$ujexl' variables for internal purpose; setting or getting those
36 * variables may lead to unexpected results unless specified otherwise.</p>
37 *
38 * @since 1.0
39 */
40 public interface JexlContext {
41
42 /**
43 * Gets the value of a variable.
44 *
45 * @param name the variable's name
46 * @return the value
47 */
48 Object get(String name);
49
50 /**
51 * Sets the value of a variable.
52 *
53 * @param name the variable's name
54 * @param value the variable's value
55 */
56 void set(String name, Object value);
57
58 /**
59 * Checks whether a variable is defined in this context.
60 *
61 * <p>A variable may be defined with a null value; this method checks whether the
62 * value is null or if the variable is undefined.</p>
63 *
64 * @param name the variable's name
65 * @return true if it exists, false otherwise
66 */
67 boolean has(String name);
68
69 /**
70 * A marker interface of the JexlContext that declares how to resolve a namespace from its name;
71 * it is used by the interpreter during evaluation.
72 *
73 * <p>In JEXL, a namespace is an object that serves the purpose of encapsulating functions; for instance,
74 * the "math" namespace would be the proper object to expose functions like "log(...)", "sinus(...)", etc.</p>
75 *
76 * In expressions like "ns:function(...)", the resolver is called with resolveNamespace("ns").
77 *
78 * <p>JEXL itself reserves 'jexl' and 'ujexl' as namespaces for internal purpose; resolving those may lead to
79 * unexpected results.</p>
80 *
81 * @since 3.0
82 */
83 interface NamespaceResolver {
84
85 /**
86 * Resolves a namespace by its name.
87 * @param name the name
88 * @return the namespace object
89 */
90 Object resolveNamespace(String name);
91 }
92
93 /**
94 * A marker interface that solves a simple class name into a fully-qualified one.
95 * @since 3.3
96 */
97 interface ClassNameResolver {
98 /**
99 * Resolves a class name.
100 * @param name the simple class name
101 * @return the fully qualified class name
102 */
103 String resolveClassName(String name);
104 }
105
106 /**
107 * A marker interface of the JexlContext, NamespaceFunctor allows creating an instance
108 * to delegate namespace methods calls to.
109 *
110 * <p>The functor is created once during the lifetime of a script evaluation.</p>
111 */
112 interface NamespaceFunctor {
113 /**
114 * Creates the functor object that will be used instead of the namespace.
115 * @param context the context
116 * @return the namespace functor instance
117 */
118 Object createFunctor(JexlContext context);
119 }
120
121 /**
122 * A marker interface of the JexlContext that indicates the interpreter to put this context
123 * in the JexlEngine thread local context instance during evaluation.
124 * This allows user functions or methods to access the context during a call.
125 * Note that the usual caveats wrt using thread local apply (caching/leaking references, etc.); in particular,
126 * keeping a reference to such a context is to be considered with great care and caution.
127 * It should also be noted that sharing such a context between threads should implicate synchronizing variable
128 * accessing the implementation class.
129 *
130 * @see JexlEngine#setThreadContext(JexlContext.ThreadLocal)
131 * @see JexlEngine#getThreadContext()
132 */
133 interface ThreadLocal extends JexlContext {
134 // no specific method
135 }
136
137 /**
138 * A marker interface of the JexlContext that processes annotations.
139 * It is used by the interpreter during evaluation to execute annotation evaluations.
140 * <p>If the JexlContext is not an instance of an AnnotationProcessor, encountering an annotation will generate
141 * an error or a warning depending on the engine strictness.
142 * @since 3.1
143 */
144 interface AnnotationProcessor {
145 /**
146 * Processes an annotation.
147 * <p>All annotations are processed through this method; the statement 'call' is to be performed within
148 * the processAnnotation method. The implementation <em>must</em> perform the call explicitly.
149 * <p>The arguments and the statement <em>must not</em> be referenced or cached for longer than the duration
150 * of the processAnnotation call.
151 *
152 * @param name the annotation name
153 * @param args the arguments of the annotation, evaluated as arguments of this call
154 * @param statement the statement that was annotated; the processor should invoke this statement 'call' method
155 * @return the result of statement.call()
156 * @throws Exception if annotation processing fails
157 */
158 Object processAnnotation(String name, Object[] args, Callable<Object> statement) throws Exception;
159 }
160
161 /**
162 * A marker interface of the JexlContext that processes module definitions.
163 * It is used by the interpreter during evaluation of the pragma module definitions.
164 * @since 3.3
165 */
166 interface ModuleProcessor {
167 /**
168 * Defines a module.
169 * The module name will be the namespace mapped to the object returned by the evaluation
170 * of its body.
171 * @param engine the engine evaluating this module pragma
172 * @param info the info at the pragma location
173 * @param name the module name
174 * @param body the module definition which can be its location or source
175 * @return the module object
176 */
177 Object processModule(JexlEngine engine, JexlInfo info, String name, String body);
178 }
179
180 /**
181 * A marker interface of the JexlContext that exposes runtime evaluation options.
182 * @since 3.2
183 */
184 interface OptionsHandle {
185 /**
186 * Retrieves the current set of options though the context.
187 * <p>
188 * This method will be called once at beginning of evaluation and an interpreter private copy
189 * of the context handled JexlOptions instance used for the duration of the execution;
190 * the context handled JexlOptions instance being only used as the source of that copy,
191 * it can safely alter its boolean flags during execution with no effect, avoiding any behavior ambiguity.
192 * @return the engine options
193 */
194 JexlOptions getEngineOptions();
195 }
196
197 /**
198 * A marker interface of the JexlContext that processes pragmas.
199 * It is called by the engine before interpreter creation; as a marker of
200 * JexlContext, it is expected to have access and interact with the context
201 * instance.
202 * @since 3.2
203 */
204 interface PragmaProcessor {
205 /**
206 * Process one pragma.
207 * <p>Never called in 3.3, must be implemented for 3.2 binary compatibility reasons.</p>
208 * <p>Typical implementation in 3.3:</p>
209 * <code>
210 * @Override
211 * public void processPragma(String key, Object value) {
212 * processPragma(null, key, value);
213 * }
214 * </code>
215 * @param key the key
216 * @param value the value
217 * @deprecated 3.3
218 */
219 @Deprecated
220 void processPragma(String key, Object value);
221
222 /**
223 * Process one pragma.
224 * @param opts the current evaluator options
225 * @param key the key
226 * @param value the value
227 * @since 3.3
228 */
229 default void processPragma(final JexlOptions opts, final String key, final Object value) {
230 processPragma(key, value);
231 }
232 }
233
234 /**
235 * A marker interface of the JexlContext sharing a cancelling flag.
236 * <p>A script running in a thread can thus be notified through this reference
237 * of its cancellation through the context. It uses the same interpreter logic
238 * that reacts to cancellation and is an alternative to using callable() and/or
239 * interrupting script interpreter threads.
240 * @since 3.2
241 */
242 interface CancellationHandle {
243 /**
244 * @return a cancelable boolean used by the interpreter
245 */
246 AtomicBoolean getCancellation();
247 }
248 }