    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}