1 /*
   2  * Copyright (c) 2005, 2013, 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 factory
  35  * that exposes metadata describing the engine class.
  36  * <br><br>The <code>ScriptEngineManager</code>
  37  * uses the service provider mechanism described in the <i>Jar File Specification</i> to obtain
  38  * instances of all <code>ScriptEngineFactories</code> available in
  39  * the current ClassLoader.
  40  *
  41  * @since 1.6
  42  */
  43 public interface ScriptEngineFactory {
  44     /**
  45      * Returns the full  name of the <code>ScriptEngine</code>.  For
  46      * instance an implementation based on the Mozilla Rhino Javascript engine
  47      * might return <i>Rhino Mozilla Javascript Engine</i>.
  48      * @return The name of the engine implementation.
  49      */
  50     public String getEngineName();
  51 
  52     /**
  53      * Returns the version of the <code>ScriptEngine</code>.
  54      * @return The <code>ScriptEngine</code> implementation version.
  55      */
  56     public String getEngineVersion();
  57 
  58 
  59     /**
  60      * Returns an immutable list of filename extensions, which generally identify scripts
  61      * written in the language supported by this <code>ScriptEngine</code>.
  62      * The array is used by the <code>ScriptEngineManager</code> to implement its
  63      * <code>getEngineByExtension</code> method.
  64      * @return The list of extensions.
  65      */
  66     public List<String> getExtensions();
  67 
  68 
  69     /**
  70      * Returns an immutable list of mimetypes, associated with scripts that
  71      * can be executed by the engine.  The list is used by the
  72      * <code>ScriptEngineManager</code> class to implement its
  73      * <code>getEngineByMimetype</code> method.
  74      * @return The list of mime types.
  75      */
  76     public List<String> getMimeTypes();
  77 
  78     /**
  79      * Returns an immutable list of  short names for the <code>ScriptEngine</code>, which may be used to
  80      * identify the <code>ScriptEngine</code> by the <code>ScriptEngineManager</code>.
  81      * For instance, an implementation based on the Mozilla Rhino Javascript engine might
  82      * return list containing {&quot;javascript&quot;, &quot;rhino&quot;}.
  83      * @return an immutable list of short names
  84      */
  85     public List<String> getNames();
  86 
  87     /**
  88      * Returns the name of the scripting langauge supported by this
  89      * <code>ScriptEngine</code>.
  90      * @return The name of the supported language.
  91      */
  92     public String getLanguageName();
  93 
  94     /**
  95      * Returns the version of the scripting language supported by this
  96      * <code>ScriptEngine</code>.
  97      * @return The version of the supported language.
  98      */
  99     public String getLanguageVersion();
 100 
 101     /**
 102      * Returns the value of an attribute whose meaning may be implementation-specific.
 103      * Keys for which the value is defined in all implementations are:
 104      * <ul>
 105      * <li>ScriptEngine.ENGINE</li>
 106      * <li>ScriptEngine.ENGINE_VERSION</li>
 107      * <li>ScriptEngine.NAME</li>
 108      * <li>ScriptEngine.LANGUAGE</li>
 109      * <li>ScriptEngine.LANGUAGE_VERSION</li>
 110      * </ul>
 111      * <p>
 112      * The values for these keys are the Strings returned by <code>getEngineName</code>,
 113      * <code>getEngineVersion</code>, <code>getName</code>, <code>getLanguageName</code> and
 114      * <code>getLanguageVersion</code> respectively.<br><br>
 115      * A reserved key, <code><b>THREADING</b></code>, whose value describes the behavior of the engine
 116      * with respect to concurrent execution of scripts and maintenance of state is also defined.
 117      * These values for the <code><b>THREADING</b></code> key are:<br><br>
 118      * <ul>
 119      * <li><code>null</code> - The engine implementation is not thread safe, and cannot
 120      * be used to execute scripts concurrently on multiple threads.
 121      * <li><code>&quot;MULTITHREADED&quot;</code> - The engine implementation is internally
 122      * thread-safe and scripts may execute concurrently although effects of script execution
 123      * on one thread may be visible to scripts on other threads.
 124      * <li><code>&quot;THREAD-ISOLATED&quot;</code> - The implementation satisfies the requirements
 125      * of &quot;MULTITHREADED&quot;, and also, the engine maintains independent values
 126      * for symbols in scripts executing on different threads.
 127      * <li><code>&quot;STATELESS&quot;</code> - The implementation satisfies the requirements of
 128      * <li><code>&quot;THREAD-ISOLATED&quot;</code>.  In addition, script executions do not alter the
 129      * mappings in the <code>Bindings</code> which is the engine scope of the
 130      * <code>ScriptEngine</code>.  In particular, the keys in the <code>Bindings</code>
 131      * and their associated values are the same before and after the execution of the script.
 132      * </ul>
 133      * <br><br>
 134      * Implementations may define implementation-specific keys.
 135      *
 136      * @param key The name of the parameter
 137      * @return The value for the given parameter. Returns <code>null</code> if no
 138      * value is assigned to the key.
 139      *
 140      */
 141     public Object getParameter(String key);
 142 
 143     /**
 144      * Returns a String which can be used to invoke a method of a  Java object using the syntax
 145      * of the supported scripting language.  For instance, an implementation for a Javascript
 146      * engine might be;
 147      *
 148      * <pre>{@code
 149      * public String getMethodCallSyntax(String obj,
 150      *                                   String m, String... args) {
 151      *      String ret = obj;
 152      *      ret += "." + m + "(";
 153      *      for (int i = 0; i < args.length; i++) {
 154      *          ret += args[i];
 155      *          if (i < args.length - 1) {
 156      *              ret += ",";
 157      *          }
 158      *      }
 159      *      ret += ")";
 160      *      return ret;
 161      * }
 162      * } </pre>
 163      *
 164      * @param obj The name representing the object whose method is to be invoked. The
 165      * name is the one used to create bindings using the <code>put</code> method of
 166      * <code>ScriptEngine</code>, the <code>put</code> method of an <code>ENGINE_SCOPE</code>
 167      * <code>Bindings</code>,or the <code>setAttribute</code> method
 168      * of <code>ScriptContext</code>.  The identifier used in scripts may be a decorated form of the
 169      * specified one.
 170      *
 171      * @param m The name of the method to invoke.
 172      * @param args names of the arguments in the method call.
 173      *
 174      * @return The String used to invoke the method in the syntax of the scripting language.
 175      */
 176     public String getMethodCallSyntax(String obj, String m, String... args);
 177 
 178     /**
 179      * Returns a String that can be used as a statement to display the specified String  using
 180      * the syntax of the supported scripting language.  For instance, the implementation for a Perl
 181      * engine might be;
 182      *
 183      * <pre><code>
 184      * public String getOutputStatement(String toDisplay) {
 185      *      return "print(" + toDisplay + ")";
 186      * }
 187      * </code></pre>
 188      *
 189      * @param toDisplay The String to be displayed by the returned statement.
 190      * @return The string used to display the String in the syntax of the scripting language.
 191      *
 192      *
 193      */
 194     public String getOutputStatement(String toDisplay);
 195 
 196 
 197     /**
 198      * Returns a valid scripting language executable program with given statements.
 199      * For instance an implementation for a PHP engine might be:
 200      *
 201      * <pre>{@code
 202      * public String getProgram(String... statements) {
 203      *      String retval = "<?\n";
 204      *      int len = statements.length;
 205      *      for (int i = 0; i < len; i++) {
 206      *          retval += statements[i] + ";\n";
 207      *      }
 208      *      return retval += "?>";
 209      * }
 210      * }</pre>
 211      *
 212      *  @param statements The statements to be executed.  May be return values of
 213      *  calls to the <code>getMethodCallSyntax</code> and <code>getOutputStatement</code> methods.
 214      *  @return The Program
 215      */
 216 
 217     public String getProgram(String... statements);
 218 
 219     /**
 220      * Returns an instance of the <code>ScriptEngine</code> associated with this
 221      * <code>ScriptEngineFactory</code>. A new ScriptEngine is generally
 222      * returned, but implementations may pool, share or reuse engines.
 223      *
 224      * @return A new <code>ScriptEngine</code> instance.
 225      */
 226     public  ScriptEngine getScriptEngine();
 227 }