1 /*

     2  * Copyright 2005 Sun Microsystems, Inc.  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.  Sun designates this

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

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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 {"javascript", "rhino"}.

    83      */

    84     public List<String> getNames();

    85 

    86     /**

    87      * Returns the name of the scripting langauge supported by this

    88      * <code>ScriptEngine</code>.

    89      * @return The name of the supported language.

    90      */

    91     public String getLanguageName();

    92 

    93     /**

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

    95      * <code>ScriptEngine</code>.

    96      * @return The version of the supported language.

    97      */

    98     public String getLanguageVersion();

    99 

   100     /**

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

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

   103      * <ul>

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

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

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

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

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

   109      * </ul>

   110      * <p>

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

   112      * <code>getEngineVersion</code>, <code>getName</code>, <code>getLanguageName</code> and

   113      * <code>getLanguageVersion</code> respectively.<br><br>

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

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

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

   117      * <ul>

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

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

   120      * <p><code>&quot;MULTITHREADED&quot;</code> - The engine implementation is internally

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

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

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

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

   125      * for symbols in scripts executing on different threads.

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

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

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

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

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

   131      * </li>

   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 implementaton for a Javascript

   146      * engine might be;

   147      * <p>

   148      * <code><pre>

   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      *          } else {

   158      *              ret += ",";

   159      *          }

   160      *      }

   161      *      return ret;

   162      * }

   163      *</pre></code>

   164      * <p>

   165      *

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

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

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

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

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

   171      * specified one.

   172      *

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

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

   175      *

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

   177      */

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

   179 

   180     /**

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

   182      * the syntax of the supported scripting language.  For instance, the implementaton for a Perl

   183      * engine might be;

   184      * <p>

   185      * <pre><code>

   186      * public String getOutputStatement(String toDisplay) {

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

   188      * }

   189      * </code></pre>

   190      *

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

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

   193      *

   194      *

   195      */

   196     public String getOutputStatement(String toDisplay);

   197 

   198 

   199     /**

   200      * Returns A valid scripting language executable progam with given statements.

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

   202      * <p>

   203      * <pre><code>

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

   205      *      $retval = "<?\n";

   206      *      int len = statements.length;

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

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

   209      *      }

   210      *      $retval += "?>";

   211      *

   212      * }

   213      * </code></pre>

   214      *

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

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

   217      *  @return The Program

   218      */

   219 

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

   221 

   222     /**

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

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

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

   226      *

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

   228      */

   229     public  ScriptEngine getScriptEngine();

   230 }