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 {&quot;javascript&quot;, &quot;rhino&quot;}.
  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 &quot;MULTITHREADED&quot;, 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 
 221     public String getProgram(String... statements);
 222 
 223     /**
 224      * Returns an instance of the <code>ScriptEngine</code> associated with this
 225      * <code>ScriptEngineFactory</code>. A new ScriptEngine is generally
 226      * returned, but implementations may pool, share or reuse engines.
 227      *
 228      * @return A new <code>ScriptEngine</code> instance.
 229      */
 230     public  ScriptEngine getScriptEngine();
 231 }