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 }