1 /*

     2  * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.script;

    27 

    28 import java.util.List;

    29 

    30 /**

    31  * <code>ScriptEngineFactory</code> is used to describe and instantiate

    32  * <code>ScriptEngines</code>.

    33  * <br><br>

    34  * Each class implementing <code>ScriptEngine</code> has a corresponding

    35  * factory that exposes metadata describing the engine class.

    36  * <br><br>The <code>ScriptEngineManager</code>

    37  * uses the service-provider loader mechanism described in the

    38  * {@link java.util.ServiceLoader} class to obtain

    39  * instances of {@code ScriptEngineFactory} instances.

    40  * See {@link ScriptEngineManager#ScriptEngineManager()} and

    41  * {@link ScriptEngineManager#ScriptEngineManager(java.lang.ClassLoader)}.

    42  *

    43  * @since 1.6

    44  */

    45 public interface ScriptEngineFactory {

    46     /**

    47      * Returns the full  name of the <code>ScriptEngine</code>.  For

    48      * instance an implementation based on the Mozilla Rhino Javascript engine

    49      * might return <i>Rhino Mozilla Javascript Engine</i>.

    50      * @return The name of the engine implementation.

    51      */

    52     public String getEngineName();

    53 

    54     /**

    55      * Returns the version of the <code>ScriptEngine</code>.

    56      * @return The <code>ScriptEngine</code> implementation version.

    57      */

    58     public String getEngineVersion();

    59 

    60 

    61     /**

    62      * Returns an immutable list of filename extensions, which generally identify scripts

    63      * written in the language supported by this <code>ScriptEngine</code>.

    64      * The array is used by the <code>ScriptEngineManager</code> to implement its

    65      * <code>getEngineByExtension</code> method.

    66      * @return The list of extensions.

    67      */

    68     public List<String> getExtensions();

    69 

    70 

    71     /**

    72      * Returns an immutable list of mimetypes, associated with scripts that

    73      * can be executed by the engine.  The list is used by the

    74      * <code>ScriptEngineManager</code> class to implement its

    75      * <code>getEngineByMimetype</code> method.

    76      * @return The list of mime types.

    77      */

    78     public List<String> getMimeTypes();

    79 

    80     /**

    81      * Returns an immutable list of  short names for the <code>ScriptEngine</code>, which may be used to

    82      * identify the <code>ScriptEngine</code> by the <code>ScriptEngineManager</code>.

    83      * For instance, an implementation based on the Mozilla Rhino Javascript engine might

    84      * return list containing {"javascript", "rhino"}.

    85      * @return an immutable list of short names

    86      */

    87     public List<String> getNames();

    88 

    89     /**

    90      * Returns the name of the scripting language supported by this

    91      * <code>ScriptEngine</code>.

    92      * @return The name of the supported language.

    93      */

    94     public String getLanguageName();

    95 

    96     /**

    97      * Returns the version of the scripting language supported by this

    98      * <code>ScriptEngine</code>.

    99      * @return The version of the supported language.

   100      */

   101     public String getLanguageVersion();

   102 

   103     /**

   104      * Returns the value of an attribute whose meaning may be implementation-specific.

   105      * Keys for which the value is defined in all implementations are:

   106      * <ul>

   107      * <li>ScriptEngine.ENGINE</li>

   108      * <li>ScriptEngine.ENGINE_VERSION</li>

   109      * <li>ScriptEngine.LANGUAGE</li>

   110      * <li>ScriptEngine.LANGUAGE_VERSION</li>

   111      * <li>ScriptEngine.NAME</li>

   112      * </ul>

   113      * <p>

   114      * The values for these keys are the Strings returned by <code>getEngineName</code>,

   115      * <code>getEngineVersion</code>, <code>getLanguageName</code>,

   116      * <code>getLanguageVersion</code> for the first four keys respectively. For NAME, one of the Strings

   117      * returned by <code>getNames</code> is returned.<br><br>

   118      * A reserved key, <code><b>THREADING</b></code>, whose value describes the behavior of the engine

   119      * with respect to concurrent execution of scripts and maintenance of state is also defined.

   120      * These values for the <code><b>THREADING</b></code> key are:<br><br>

   121      * <ul>

   122      * <li><code>null</code> - The engine implementation is not thread safe, and cannot

   123      * be used to execute scripts concurrently on multiple threads.

   124      * <li><code>&quot;MULTITHREADED&quot;</code> - The engine implementation is internally

   125      * thread-safe and scripts may execute concurrently although effects of script execution

   126      * on one thread may be visible to scripts on other threads.

   127      * <li><code>&quot;THREAD-ISOLATED&quot;</code> - The implementation satisfies the requirements

   128      * of "MULTITHREADED", and also, the engine maintains independent values

   129      * for symbols in scripts executing on different threads.

   130      * <li><code>&quot;STATELESS&quot;</code> - The implementation satisfies the requirements of

   131      * <code>&quot;THREAD-ISOLATED&quot;</code>.  In addition, script executions do not alter the

   132      * mappings in the <code>Bindings</code> which is the engine scope of the

   133      * <code>ScriptEngine</code>.  In particular, the keys in the <code>Bindings</code>

   134      * and their associated values are the same before and after the execution of the script.

   135      * </ul>

   136      * <br><br>

   137      * Implementations may define implementation-specific keys.

   138      *

   139      * @param key The name of the parameter

   140      * @return The value for the given parameter. Returns <code>null</code> if no

   141      * value is assigned to the key.

   142      *

   143      * @throws NullPointerException if the key is null.

   144      */

   145     public Object getParameter(String key);

   146 

   147     /**

   148      * Returns a String which can be used to invoke a method of a  Java object using the syntax

   149      * of the supported scripting language.  For instance, an implementation for a Javascript

   150      * engine might be;

   151      *

   152      * <pre>{@code

   153      * public String getMethodCallSyntax(String obj,

   154      *                                   String m, String... args) {

   155      *      String ret = obj;

   156      *      ret += "." + m + "(";

   157      *      for (int i = 0; i < args.length; i++) {

   158      *          ret += args[i];

   159      *          if (i < args.length - 1) {

   160      *              ret += ",";

   161      *          }

   162      *      }

   163      *      ret += ")";

   164      *      return ret;

   165      * }

   166      * } </pre>

   167      *

   168      * @param obj The name representing the object whose method is to be invoked. The

   169      * name is the one used to create bindings using the <code>put</code> method of

   170      * <code>ScriptEngine</code>, the <code>put</code> method of an <code>ENGINE_SCOPE</code>

   171      * <code>Bindings</code>,or the <code>setAttribute</code> method

   172      * of <code>ScriptContext</code>.  The identifier used in scripts may be a decorated form of the

   173      * specified one.

   174      *

   175      * @param m The name of the method to invoke.

   176      * @param args names of the arguments in the method call.

   177      *

   178      * @return The String used to invoke the method in the syntax of the scripting language.

   179      */

   180     public String getMethodCallSyntax(String obj, String m, String... args);

   181 

   182     /**

   183      * Returns a String that can be used as a statement to display the specified String  using

   184      * the syntax of the supported scripting language.  For instance, the implementation for a Perl

   185      * engine might be;

   186      *

   187      * <pre><code>

   188      * public String getOutputStatement(String toDisplay) {

   189      *      return "print(" + toDisplay + ")";

   190      * }

   191      * </code></pre>

   192      *

   193      * @param toDisplay The String to be displayed by the returned statement.

   194      * @return The string used to display the String in the syntax of the scripting language.

   195      *

   196      *

   197      */

   198     public String getOutputStatement(String toDisplay);

   199 

   200 

   201     /**

   202      * Returns a valid scripting language executable program with given statements.

   203      * For instance an implementation for a PHP engine might be:

   204      *

   205      * <pre>{@code

   206      * public String getProgram(String... statements) {

   207      *      String retval = "<?\n";

   208      *      int len = statements.length;

   209      *      for (int i = 0; i < len; i++) {

   210      *          retval += statements[i] + ";\n";

   211      *      }

   212      *      return retval += "?>";

   213      * }

   214      * }</pre>

   215      *

   216      *  @param statements The statements to be executed.  May be return values of

   217      *  calls to the <code>getMethodCallSyntax</code> and <code>getOutputStatement</code> methods.

   218      *  @return The Program

   219      *

   220      *  @throws NullPointerException if the <code>statements</code> array or any of its elements is null

   221      */

   222     public String getProgram(String... statements);

   223 

   224     /**

   225      * Returns an instance of the <code>ScriptEngine</code> associated with this

   226      * <code>ScriptEngineFactory</code>. A new ScriptEngine is generally

   227      * returned, but implementations may pool, share or reuse engines.

   228      *

   229      * @return A new <code>ScriptEngine</code> instance.

   230      */

   231     public  ScriptEngine getScriptEngine();

   232 }