001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.jexl3;
019
020import java.util.concurrent.Callable;
021import java.util.concurrent.atomic.AtomicBoolean;
022
023/**
024 * Manages variables which can be referenced in a JEXL expression.
025 *
026 * <p>JEXL variable names in their simplest form are 'java-like' identifiers.
027 * JEXL also considers 'ant' inspired variables expressions as valid.
028 * For instance, the expression 'x.y.z' is an 'antish' variable and will be resolved as a whole by the context,
029 * i.e. using the key "x.y.z". This proves to be useful to solve "fully qualified class names".</p>
030 *
031 * <p>The interpreter variable resolution algorithm will try the different sequences of identifiers till it finds
032 * one that exists in the context; if "x" is an object known in the context (JexlContext.has("x") returns true),
033 * "x.y" will <em>not</em> be looked up in the context but will most likely refer to "x.getY()".</p>
034 *
035 * <p>Note that JEXL may use '$jexl' and '$ujexl' variables for internal purpose; setting or getting those
036 * variables may lead to unexpected results unless specified otherwise.</p>
037 *
038 * @since 1.0
039 */
040public interface JexlContext {
041
042    /**
043     * Gets the value of a variable.
044     *
045     * @param name the variable's name
046     * @return the value
047     */
048    Object get(String name);
049
050    /**
051     * Sets the value of a variable.
052     *
053     * @param name the variable's name
054     * @param value the variable's value
055     */
056    void set(String name, Object value);
057
058    /**
059     * Checks whether a variable is defined in this context.
060     *
061     * <p>A variable may be defined with a null value; this method checks whether the
062     * value is null or if the variable is undefined.</p>
063     *
064     * @param name the variable's name
065     * @return true if it exists, false otherwise
066     */
067    boolean has(String name);
068
069    /**
070     * A marker interface of the JexlContext that declares how to resolve a namespace from its name;
071     * it is used by the interpreter during evaluation.
072     *
073     * <p>In JEXL, a namespace is an object that serves the purpose of encapsulating functions; for instance,
074     * the "math" namespace would be the proper object to expose functions like "log(...)", "sinus(...)", etc.</p>
075     *
076     * In expressions like "ns:function(...)", the resolver is called with resolveNamespace("ns").
077     *
078     * <p>JEXL itself reserves 'jexl' and 'ujexl' as namespaces for internal purpose; resolving those may lead to
079     * unexpected results.</p>
080     *
081     * @since 3.0
082     */
083    interface NamespaceResolver {
084
085        /**
086         * Resolves a namespace by its name.
087         * @param name the name
088         * @return the namespace object
089         */
090        Object resolveNamespace(String name);
091    }
092
093    /**
094     * A marker interface that solves a simple class name into a fully-qualified one.
095     * @since 3.3
096     */
097    interface ClassNameResolver {
098        /**
099         * 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         *         &#64;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}