001: /*
002: * %W% %E% %U%
003: *
004: * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
005: * SUN PROPRIETARY/CONFIDENTAIL. Use is subject to license terms.
006: */
007:
008: package javax.script;
009:
010: import java.util.List;
011:
012: /**
013: * <code>ScriptEngineFactory</code> is used to describe and instantiate
014: * <code>ScriptEngines</code>.
015: * <br><br>
016: * Each class implementing <code>ScriptEngine</code> has a corresponding factory
017: * that exposes metadata describing the engine class.
018: * <br><br>The <code>ScriptEngineManager</code>
019: * uses the service provider mechanism described in the <i>Jar File Specification</i> to obtain
020: * instances of all <code>ScriptEngineFactories</code> available in
021: * the current ClassLoader.
022: *
023: * @since 1.6
024: */
025: public interface ScriptEngineFactory {
026: /**
027: * Returns the full name of the <code>ScriptEngine</code>. For
028: * instance an implementation based on the Mozilla Rhino Javascript engine
029: * might return <i>Rhino Mozilla Javascript Engine</i>.
030: * @return The name of the engine implementation.
031: */
032: public String getEngineName();
033:
034: /**
035: * Returns the version of the <code>ScriptEngine</code>.
036: * @return The <code>ScriptEngine</code> implementation version.
037: */
038: public String getEngineVersion();
039:
040: /**
041: * Returns an immutable list of filename extensions, which generally identify scripts
042: * written in the language supported by this <code>ScriptEngine</code>.
043: * The array is used by the <code>ScriptEngineManager</code> to implement its
044: * <code>getEngineByExtension</code> method.
045: * @return The list of extensions.
046: */
047: public List<String> getExtensions();
048:
049: /**
050: * Returns an immutable list of mimetypes, associated with scripts that
051: * can be executed by the engine. The list is used by the
052: * <code>ScriptEngineManager</code> class to implement its
053: * <code>getEngineByMimetype</code> method.
054: * @return The list of mime types.
055: */
056: public List<String> getMimeTypes();
057:
058: /**
059: * Returns an immutable list of short names for the <code>ScriptEngine</code>, which may be used to
060: * identify the <code>ScriptEngine</code> by the <code>ScriptEngineManager</code>.
061: * For instance, an implementation based on the Mozilla Rhino Javascript engine might
062: * return list containing {"javascript", "rhino"}.
063: */
064: public List<String> getNames();
065:
066: /**
067: * Returns the name of the scripting langauge supported by this
068: * <code>ScriptEngine</code>.
069: * @return The name of the supported language.
070: */
071: public String getLanguageName();
072:
073: /**
074: * Returns the version of the scripting language supported by this
075: * <code>ScriptEngine</code>.
076: * @return The version of the supported language.
077: */
078: public String getLanguageVersion();
079:
080: /**
081: * Returns the value of an attribute whose meaning may be implementation-specific.
082: * Keys for which the value is defined in all implementations are:
083: * <ul>
084: * <li>ScriptEngine.ENGINE</li>
085: * <li>ScriptEngine.ENGINE_VERSION</li>
086: * <li>ScriptEngine.NAME</li>
087: * <li>ScriptEngine.LANGUAGE</li>
088: * <li>ScriptEngine.LANGUAGE_VERSION</li>
089: * </ul>
090: * <p>
091: * The values for these keys are the Strings returned by <code>getEngineName</code>,
092: * <code>getEngineVersion</code>, <code>getName</code>, <code>getLanguageName</code> and
093: * <code>getLanguageVersion</code> respectively.<br><br>
094: * A reserved key, <code><b>THREADING</b></code>, whose value describes the behavior of the engine
095: * with respect to concurrent execution of scripts and maintenance of state is also defined.
096: * These values for the <code><b>THREADING</b></code> key are:<br><br>
097: * <ul>
098: * <p><code>null</code> - The engine implementation is not thread safe, and cannot
099: * be used to execute scripts concurrently on multiple threads.
100: * <p><code>"MULTITHREADED"</code> - The engine implementation is internally
101: * thread-safe and scripts may execute concurrently although effects of script execution
102: * on one thread may be visible to scripts on other threads.
103: * <p><code>"THREAD-ISOLATED"</code> - The implementation satisfies the requirements
104: * of "MULTITHREADED", and also, the engine maintains independent values
105: * for symbols in scripts executing on different threads.
106: * <p><code>"STATELESS"</code> - The implementation satisfies the requirements of
107: * <code>"THREAD-ISOLATED"</code>. In addition, script executions do not alter the
108: * mappings in the <code>Bindings</code> which is the engine scope of the
109: * <code>ScriptEngine</code>. In particular, the keys in the <code>Bindings</code>
110: * and their associated values are the same before and after the execution of the script.
111: * </li>
112: * </ul>
113: * <br><br>
114: * Implementations may define implementation-specific keys.
115: *
116: * @param key The name of the parameter
117: * @return The value for the given parameter. Returns <code>null</code> if no
118: * value is assigned to the key.
119: *
120: */
121: public Object getParameter(String key);
122:
123: /**
124: * Returns a String which can be used to invoke a method of a Java object using the syntax
125: * of the supported scripting language. For instance, an implementaton for a Javascript
126: * engine might be;
127: * <p>
128: * <code><pre>
129: * public String getMethodCallSyntax(String obj,
130: * String method, String... args) {
131: * int ret = obj;
132: * obj += "." + method + "(";
133: * for (int i = 0; i < args.length; i++) {
134: * return += args[i];
135: * if (i == args.length - 1) {
136: * obj += ")";
137: * } else {
138: * obj += ",");
139: * }
140: * }
141: * return ret;
142: * }
143: *</pre></code>
144: * <p>
145: *
146: * @param obj The name representing the object whose method is to be invoked. The
147: * name is the one used to create bindings using the <code>put</code> method of
148: * <code>ScriptEngine</code>, the <code>put</code> method of an <code>ENGINE_SCOPE</code>
149: * <code>Bindings</code>,or the <code>setAttribute</code> method
150: * of <code>ScriptContext</code>. The identifier used in scripts may be a decorated form of the
151: * specified one.
152: *
153: * @param m The name of the method to invoke.
154: * @param args names of the arguments in the method call.
155: *
156: * @return The String used to invoke the method in the syntax of the scripting language.
157: */
158: public String getMethodCallSyntax(String obj, String m,
159: String... args);
160:
161: /**
162: * Returns a String that can be used as a statement to display the specified String using
163: * the syntax of the supported scripting language. For instance, the implementaton for a Perl
164: * engine might be;
165: * <p>
166: * <pre><code>
167: * public String getOutputStatement(String toDisplay) {
168: * return "print(" + toDisplay + ")";
169: * }
170: * </code></pre>
171: *
172: * @param toDisplay The String to be displayed by the returned statement.
173: * @return The string used to display the String in the syntax of the scripting language.
174: *
175: *
176: */
177: public String getOutputStatement(String toDisplay);
178:
179: /**
180: * Returns A valid scripting language executable progam with given statements.
181: * For instance an implementation for a PHP engine might be:
182: * <p>
183: * <pre><code>
184: * public String getProgram(String... statements) {
185: * $retval = "<?\n";
186: * int len = statements.length;
187: * for (int i = 0; i < len; i++) {
188: * $retval += statements[i] + ";\n";
189: * }
190: * $retval += "?>";
191: *
192: * }
193: * </code></pre>
194: *
195: * @param statements The statements to be executed. May be return values of
196: * calls to the <code>getMethodCallSyntax</code> and <code>getOutputStatement</code> methods.
197: * @return The Program
198: */
199:
200: public String getProgram(String... statements);
201:
202: /**
203: * Returns an instance of the <code>ScriptEngine</code> associated with this
204: * <code>ScriptEngineFactory</code>. A new ScriptEngine is generally
205: * returned, but implementations may pool, share or reuse engines.
206: *
207: * @return A new <code>ScriptEngine</code> instance.
208: */
209: public ScriptEngine getScriptEngine();
210: }
|