    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    }