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 */
017package org.apache.commons.jexl2;
018
019import java.util.List;
020import java.util.Set;
021import 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 */
034public 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}