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.List; 021import java.util.Map; 022import java.util.Set; 023import java.util.concurrent.Callable; 024 025/** 026 * A JEXL Script. 027 * 028 * <p>A script is some valid JEXL syntax to be executed with a given set of {@link JexlContext} variables.</p> 029 * 030 * <p>A script is a group of statements, separated by semicolons.</p> 031 * 032 * <p>The statements can be <code>blocks</code> (curly braces containing code), 033 * Control statements such as <code>if</code> and <code>while</code> 034 * as well as expressions and assignment statements.</p> 035 * 036 * <p>Do <em>not</em> create classes that implement this interface; delegate or compose instead.</p> 037 * 038 * @since 1.1 039 */ 040public interface JexlScript { 041 042 /** 043 * Returns the source text of this expression. 044 * 045 * @return the source text 046 */ 047 String getSourceText(); 048 049 /** 050 * Recreates the source text of this expression from the internal syntactic tree. 051 * 052 * @return the source text 053 */ 054 String getParsedText(); 055 056 /** 057 * Recreates the source text of this expression from the internal syntactic tree. 058 * 059 * @param indent the number of spaces for indentation, 0 meaning no indentation 060 * @return the source text 061 */ 062 String getParsedText(int indent); 063 064 /** 065 * Executes the script with the variables contained in the 066 * supplied {@link JexlContext}. 067 * 068 * @param context A JexlContext containing variables. 069 * @return The result of this script, usually the result of 070 * the last statement. 071 */ 072 Object execute(JexlContext context); 073 074 /** 075 * Executes the script with the variables contained in the 076 * supplied {@link JexlContext} and a set of arguments corresponding to the 077 * parameters used during parsing. 078 * 079 * @param context A JexlContext containing variables. 080 * @param args the arguments 081 * @return The result of this script, usually the result of 082 * the last statement. 083 * @since 2.1 084 */ 085 Object execute(JexlContext context, Object... args); 086 087 /** 088 * Gets this script parameters. 089 * 090 * @return the parameters or null 091 * @since 2.1 092 */ 093 String[] getParameters(); 094 095 /** 096 * Gets this script unbound parameters. 097 * <p>Parameters that haven't been bound by a previous call to curry().</p> 098 * @return the parameters or null 099 * @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}