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}