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 * @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}