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 local variables.
097     * 
098     * @return the local variables or null
099     * @since 2.1
100     */
101    String[] getLocalVariables();
102
103    /**
104     * Gets this script variables.
105     * <p>Note that since variables can be in an ant-ish form (ie foo.bar.quux), each variable is returned as
106     * a list of strings where each entry is a fragment of the variable ({"foo", "bar", "quux"} in the example.</p>
107     * 
108     * @return the variables or null
109     * @since 2.1
110     */
111    Set<List<String>> getVariables();
112
113    /**
114     * Gets this script pragmas.
115     * 
116     * @return the (non null, may be empty) pragmas map
117     */
118    Map<String, Object> getPragmas();
119
120    /**
121     * Creates a Callable from this script.
122     * 
123     * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
124     * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
125     * 
126     * @param context the context
127     * @return the callable
128     * @since 2.1
129     */
130    Callable<Object> callable(JexlContext context);
131
132    /**
133     * Creates a Callable from this script.
134     * 
135     * <p>This allows to submit it to an executor pool and provides support for asynchronous calls.</p>
136     * <p>The interpreter will handle interruption/cancellation gracefully if needed.</p>
137     * 
138     * @param context the context
139     * @param args the script arguments
140     * @return the callable
141     * @since 2.1
142     */
143    Callable<Object> callable(JexlContext context, Object... args);
144
145    /**
146     * Curries this script, returning a script with bound arguments.
147     * 
148     * <p>If this script does not declare parameters or if all of them are already bound,
149     * no error is generated and this script is returned.</p>
150     * 
151     * @param args the arguments to bind
152     * @return the curried script or this script if no binding can occur
153     */
154    JexlScript curry(Object... args);
155}