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 package org.apache.commons.jexl2;
018
019 import java.util.List;
020 import java.util.Set;
021 import java.util.concurrent.Callable;
022
023 /**
024 * <p>A JEXL Script.</p>
025 * <p>A script is some valid JEXL syntax to be executed with
026 * a given set of {@link JexlContext} variables.</p>
027 * <p>A script is a group of statements, separated by semicolons.</p>
028 * <p>The statements can be <code>blocks</code> (curly braces containing code),
029 * Control statements such as <code>if</code> and <code>while</code>
030 * as well as expressions and assignment statements.</p>
031 *
032 * @since 1.1
033 */
034 public interface Script {
035 /**
036 * Executes the script with the variables contained in the
037 * supplied {@link JexlContext}.
038 *
039 * @param context A JexlContext containing variables.
040 * @return The result of this script, usually the result of
041 * the last statement.
042 */
043 Object execute(JexlContext context);
044
045 /**
046 * Executes the script with the variables contained in the
047 * supplied {@link JexlContext} and a set of arguments corresponding to the
048 * parameters used during parsing.
049 *
050 * @param context A JexlContext containing variables.
051 * @param args the arguments
052 * @return The result of this script, usually the result of
053 * the last statement.
054 * @since 2.1
055 */
056 Object execute(JexlContext context, Object... args);
057
058 /**
059 * Returns the text of this Script.
060 * @return The script to be executed.
061 */
062 String getText();
063
064 /**
065 * Gets this script parameters.
066 * @return the parameters or null
067 * @since 2.1
068 */
069 String[] getParameters();
070
071 /**
072 * Gets this script local variables.
073 * @return the local variables or null
074 * @since 2.1
075 */
076 String[] getLocalVariables();
077
078 /**
079 * Gets this script variables.
080 * <p>Note that since variables can be in an ant-ish form (ie foo.bar.quux), each variable is returned as
081 * a list of strings where each entry is a fragment of the variable ({"foo", "bar", "quux"} in the example.</p>
082 * @return the variables or null
083 * @since 2.1
084 */
085 Set<List<String>> getVariables();
086
087 /**
088 * Creates a Callable from this script.
089 * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
090 * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
091 * @param context the context
092 * @return the callable
093 * @since 2.1
094 */
095 Callable<Object> callable(JexlContext context);
096
097 /**
098 * Creates a Callable from this script.
099 * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
100 * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
101 * @param context the context
102 * @param args the script arguments
103 * @return the callable
104 * @since 2.1
105 */
106 Callable<Object> callable(JexlContext context, Object... args);
107 }