    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     * Creates a Callable from this script.
    044     *
    045     * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
    046     * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
    047     *
    048     * @param context the context
    049     * @return the callable
    050     * @since 2.1
    051     */
    052    Callable<Object> callable(JexlContext context);
    053
    054    /**
    055     * Creates a Callable from this script.
    056     *
    057     * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
    058     * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
    059     *
    060     * @param context the context
    061     * @param args the script arguments
    062     * @return the callable
    063     * @since 2.1
    064     */
    065    Callable<Object> callable(JexlContext context, Object... args);
    066
    067    /**
    068     * Curries this script, returning a script with bound arguments.
    069     *
    070     * <p>If this script does not declare parameters or if all of them are already bound,
    071     * no error is generated and this script is returned.</p>
    072     *
    073     * @param args the arguments to bind
    074     * @return the curried script or this script if no binding can occur
    075     */
    076    JexlScript curry(Object... args);
    077
    078    /**
    079     * Executes the script with the variables contained in the
    080     * supplied {@link JexlContext}.
    081     *
    082     * @param context A JexlContext containing variables.
    083     * @return The result of this script, usually the result of
    084     *         the last statement.
    085     */
    086    Object execute(JexlContext context);
    087
    088    /**
    089     * Executes the script with the variables contained in the
    090     * supplied {@link JexlContext} and a set of arguments corresponding to the
    091     * parameters used during parsing.
    092     *
    093     * @param context A JexlContext containing variables.
    094     * @param args the arguments
    095     * @return The result of this script, usually the result of
    096     *         the last statement.
    097     * @since 2.1
    098     */
    099    Object execute(JexlContext context, Object... args);
    100
    101    /**
    102     * Gets this script local variables.
    103     *
    104     * @return the local variables or null
    105     * @since 2.1
    106     */
    107    String[] getLocalVariables();
    108
    109    /**
    110     * Gets this script parameters.
    111     *
    112     * @return the parameters or null
    113     * @since 2.1
    114     */
    115    String[] getParameters();
    116
    117    /**
    118     * Recreates the source text of this expression from the internal syntactic tree.
    119     *
    120     * @return the source text
    121     */
    122    String getParsedText();
    123
    124    /**
    125     * Recreates the source text of this expression from the internal syntactic tree.
    126     *
    127     * @param indent the number of spaces for indentation, 0 meaning no indentation
    128     * @return the source text
    129     */
    130    String getParsedText(int indent);
    131
    132    /**
    133     * Gets this script pragmas.
    134     *
    135     * @return the (non null, may be empty) pragmas map
    136     */
    137    Map<String, Object> getPragmas();
    138
    139    /**
    140     * Returns the source text of this expression.
    141      *
    142     * @return the source text
    143     */
    144    String getSourceText();
    145
    146    /**
    147     * Gets this script unbound parameters.
    148     * <p>Parameters that haven't been bound by a previous call to curry().</p>
    149     * @return the parameters or null
    150     * @since 3.2
    151     */
    152    String[] getUnboundParameters();
    153
    154    /**
    155     * Gets this script variables.
    156     * <p>Note that since variables can be in an ant-ish form (ie foo.bar.quux), each variable is returned as
    157     * a list of strings where each entry is a fragment of the variable ({"foo", "bar", "quux"} in the example.</p>
    158     *
    159     * @return the variables or null
    160     * @since 2.1
    161     */
    162    Set<List<String>> getVariables();
    163}