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}