ScriptEngineManager A class that is the entry point into the Scripting API. It discovers and instantiates script engine factories, providing a method that lets an application enumerate these factories and retrieve a script engine that exposes the appropriate metadata (such as the correct language name and version number) from a factory. It also provides various methods for obtaining script engines by extension, MIME type, or short name. This class maintains a global scope; this scope’s key/value pairs are available to all script engines created by the script engine manager. ScriptException A class that describes syntax errors and other problems that occur during script execution. Class members store the line number and column position where a problem occurred, and also the name of the file containing the script that was executing. The availability of this information depends on the context in which the problem occurred. For example, a ScriptException thrown from executing a script that is not based on a file is unlikely to record a filename. SimpleBindings A class that provides a simple implementation of Bindings, which is backed by some kind of java.util.Map implementation. SimpleScriptContext A class that provides a simple implementation of ScriptContext. In addition to javax.script and its classes and interfaces, Java SE 6 includes a script engine that understands JavaScript. This script engine is based on the Mozilla Rhino JavaScript implementation. Check out Mozilla’s Rhino: JavaScript for Java page ( http://www.mozilla.org/rhino/) to learn about Rhino. ■Note Mozilla Rhino version 1.6R2 is included with Java SE 6 build 105. This implementation includes most of Mozilla Rhino, except for JavaScript-to-bytecode compilation, Rhino’s JavaAdapter for extending Java classes and implementing Java interfaces with JavaScript (Sun’s JavaAdapter is used instead), ECMAScript for XML, and Rhino command-line tools. An experimental command-line tool, named jrunscript, is available. I discuss this tool in the “Playing with the Command-Line Script Shell” section later in this chapter, and also in Appendix B. CHAPTER 9 ■ SCRIPTING 283 Class/Interface Description 830-X CH09.qxd 9/20/07 2:08 PM Page 283 SCRIPTING API RESOURCES I recommend several resources for learning more about the Scripting API after you’ve read this chapter: • The JDK’s script notepad Swing application, which is mostly implemented in JavaScript • Sun developer Sundar Athijegannathan’s useful and interesting Scripting API blog entries, such as “JavaScript debugging tips (for Mustang context)” ( http://blogs.sun.com/sundararajan/ entry/javascript_debugging_tips_for_mustang) • John O’Conner’s “Scripting for the Java Platform” article ( http://java.sun.com/developer/ technicalArticles/J2SE/Desktop/scripting/) If you’re interested in taking advantage of the Scripting API for web-based scripting, check out the following: • Daniel López’s “A Dynamic MVC Development Approach Using Java 6 Scripting, Groovy, and WebLEAF” article ( http://today.java.net/pub/a/today/2007/06/19/ mvc-webappps-with-groovy-scripting-and-webleaf.html) • java.net’s Project Phobos home page ( https://phobos.dev.java.net/), which describes Phobos as “a lightweight, scripting-friendly, web application environment running on the Java platform” Obtaining Script Engines from Factories via the Script Engine Manager Prior to performing other scripting tasks, a Java program must obtain an appropriate script engine. A script engine exists as an instance of a class that implements the ScriptEngine interface or extends the AbstractScriptEngine class. The program begins this task by creating an instance of the ScriptEngineManager class via one of these constructors: • The public ScriptEngineManager() constructor works with the calling thread’s context classloader if one is available, or the bootstrap classloader otherwise, and a discovery mechanism to locate ScriptEngineFactory providers. • The public ScriptEngineManager(ClassLoader loader) constructor works with the specified classloader and the discovery mechanism to locate ScriptEngineFactory providers. Passing null to loader is equivalent to calling the former constructor. CHAPTER 9 ■ SCRIPTING284 830-X CH09.qxd 9/20/07 2:08 PM Page 284 The program uses the ScriptEngineManager instance to obtain a list of factories via this class’s public List<ScriptEngineFactory> getEngineFactories() method. For each factory, ScriptEngineFactory methods, such as String getEngineName(), return metadata describing the factory’s script engine. Listing 9-1 presents an application that demon- strates most of the metadata methods. Listing 9-1. EnumerateScriptEngines.java // EnumerateScriptEngines.java import java.util.*; import javax.script.*; public class EnumerateScriptEngines { public static void main (String [] args) { ScriptEngineManager manager = new ScriptEngineManager (); List<ScriptEngineFactory> factories = manager.getEngineFactories (); for (ScriptEngineFactory factory: factories) { System.out.println ("Engine name (full): "+ factory.getEngineName ()); System.out.println ("Engine version: "+ factory.getEngineVersion ()); System.out.println ("Supported extensions:"); List<String> extensions = factory.getExtensions (); for (String extension: extensions) System.out.println (" "+extension); System.out.println ("Language name: "+ factory.getLanguageName ()); System.out.println ("Language version: "+ factory.getLanguageVersion ()); System.out.println ("Supported MIME types:"); List<String> mimetypes = factory.getMimeTypes (); for (String mimetype: mimetypes) System.out.println (" "+mimetype); System.out.println ("Supported short names:"); List<String> shortnames = factory.getNames (); for (String shortname: shortnames) CHAPTER 9 ■ SCRIPTING 285 830-X CH09.qxd 9/20/07 2:08 PM Page 285 System.out.println (" "+shortname); System.out.println (); } } } Assuming that no additional script engines have been installed, you should observe the following output when you run this application against Java SE 6 build 105: Engine name (full): Mozilla Rhino Engine version: 1.6 release 2 Supported extensions: js Language name: ECMAScript Language version: 1.6 Supported MIME types: application/javascript application/ecmascript text/javascript text/ecmascript Supported short names: js rhino JavaScript javascript ECMAScript ecmascript The output reveals that an engine can have both a full name ( Mozilla Rhino) and multiple short names ( rhino, for example). The short name is more useful than the full name, as you will see. It also shows that an engine can be associated with multiple extensions and multiple MIME types, and that the engine is associated with a scripting language. ScriptEngineFactory’s getEngineName() and a few other metadata methods defer to ScriptEngineFactory’s Object getParameter(String key) method, which returns the script- engine-specific value associated with the argument passed to key, or null if the argument is not recognized. Methods such as getEngineName() invoke getParameter() with key set to an appropri- ate ScriptEngine constant, such as ScriptEngine.ENGINE. As Listing 9-2 demonstrates, you can also pass "THREADING" as key, to identify a script engine’s threading behavior, which you need to know if you plan to evaluate multiple scripts concurrently. getParameter() CHAPTER 9 ■ SCRIPTING286 830-X CH09.qxd 9/20/07 2:08 PM Page 286 returns null if the engine is not thread-safe, or one of "MULTITHREADED", "THREAD-ISOLATED", or "STATELESS", identifying specific threading behavior. Listing 9-2. ThreadingBehavior.java // ThreadingBehavior.java import java.util.*; import javax.script.*; public class ThreadingBehavior { public static void main (String [] args) { ScriptEngineManager manager = new ScriptEngineManager (); List<ScriptEngineFactory> factories = manager.getEngineFactories (); for (ScriptEngineFactory factory: factories) System.out.println ("Threading behavior: "+ factory.getParameter ("THREADING")); } } Assuming that Mozilla Rhino 1.6 release 2 is the only installed script engine, ThreadingBehavior outputs Threading behavior: MULTITHREADED. Scripts can execute con- currently on different threads, although the effects of executing a script on one thread might be visible to threads executing on other threads. Check out the getParameter() section of ScriptEngineFactory’s SDK documentation to learn more about threading behaviors. After determining the appropriate script engine, the program can invoke ScriptEngineFactory’s ScriptEngine getScriptEngine() method to return an instance of the script engine associated with the factory. Although new script engines are usually returned, a factory implementation is free to pool, reuse, or share implementations. The following code fragment shows how to accomplish this task: if (factory.getLanguageName ().equals ("ECMAScript")) { engine = factory.getScriptEngine (); break; } CHAPTER 9 ■ SCRIPTING 287 830-X CH09.qxd 9/20/07 2:08 PM Page 287 Think of the code fragment as being part of Listing 9-1 or 9-2’s for (ScriptEngineFactory factory: factories) loop; assume that the ScriptEngine variable engine already exists. If the scripting language hosted by the factory is ECMAScript (language version does not matter in this example), a script engine is obtained from the factory and the loop is terminated. Because the previous approach to obtaining a script engine is cumbersome, ScriptEngineManager provides three convenience methods that take on this burden, listed in Table 9-2. These methods let you obtain a script engine based on file extension (possibly obtained via a dialog-selected script file), MIME type (possibly returned from a server), and short name (possibly chosen from a menu). Table 9-2. ScriptEngineManager Convenience Methods for Obtaining a Script Engine Method Description public ScriptEngine getEngineByExtension(String extension) Creates and returns a script engine that corresponds to the given extension. If a script engine is not available, this method returns null. A NullPointerException is thrown if null is passed as extension. public ScriptEngine getEngineByMimeType(String mimeType) Creates and returns a script engine that corresponds to the given MIME type. If a script engine is not available, this method returns null. A NullPointerException is thrown if null is passed as mimeType. public ScriptEngine getEngineByName(String shortName) Creates and returns a script engine that corresponds to the given short name. If a script engine is not available, this method returns null. A NullPointerException is thrown if null is passed as shortName. Listing 9-3 presents an application that invokes getEngineByExtension(), getEngineByMimeType(), and getEngineByName() to obtain a Rhino script engine instance. Behind the scenes, these methods take care of enumerating factories and invoking ScriptEngineFactory’s getScriptEngine() method to create the script engine. CHAPTER 9 ■ SCRIPTING288 830-X CH09.qxd 9/20/07 2:08 PM Page 288 Listing 9-3. ObtainScriptEngine.java // ObtainScriptEngine.java import javax.script.*; public class ObtainScriptEngine { public static void main (String [] args) { ScriptEngineManager manager = new ScriptEngineManager (); ScriptEngine engine1 = manager.getEngineByExtension ("js"); System.out.println (engine1); ScriptEngine engine2 = manager.getEngineByMimeType ("application/javascript"); System.out.println (engine2); ScriptEngine engine3 = manager.getEngineByName ("rhino"); System.out.println (engine3); } } After compiling ObtainScriptEngine.java, running the application generates output that is similar to the following, indicating that different script engine instances are returned: com.sun.script.javascript.RhinoScriptEngine@1f14ceb com.sun.script.javascript.RhinoScriptEngine@f0eed6 com.sun.script.javascript.RhinoScriptEngine@691f36 Once a script engine has been obtained (via ScriptEngineFactory’s getScriptEngine() method or one of ScriptEngineManager’s three convenience methods), a program can access the engine’s factory via ScriptEngine’s convenient ScriptEngineFactory getFactory() method. The program can also invoke various ScriptEngine methods to evaluate scripts. CHAPTER 9 ■ SCRIPTING 289 830-X CH09.qxd 9/20/07 2:08 PM Page 289 ■Note ScriptEngineManager provides public void registerEngineExtension(String extension, ScriptEngineFactory factory) , public void registerEngineMimeType(String type, ScriptEngineFactory factory) , and public void registerEngineName(String name, ScriptEngineFactory factory) methods that let Java programs dynamically register script engine factories with the script engine manager. Because these methods circumvent the discovery mechanism, you can replace an existing script engine factory and script engine with your own implementation, which is returned in subsequent calls to the “getEngine” methods. Evaluating Scripts After obtaining a script engine, a Java program can work with ScriptEngine’s six over- loaded eval() methods to evaluate scripts. Each method throws a ScriptException if there is a problem with the script. Assuming successful script evaluation, an eval() method returns the script’s result as some kind of Object, or null if the script does not return a value. The simplest of the eval() methods are Object eval(String script) and Object eval(Reader reader). The former method is invoked to evaluate a script expressed as a String; the latter method is invoked to read a script from some other source (such as a file) and evaluate the script. Each method throws a NullPointerException if its argument is null. Listing 9-4 demonstrates these methods. Listing 9-4. FuncEvaluator.java // FuncEvaluator.java import java.io.*; import javax.script.*; public class FuncEvaluator { public static void main (String [] args) { if (args.length != 2) { System.err.println ("usage: java FuncEvaluator scriptfile "+ "script-exp"); return; } CHAPTER 9 ■ SCRIPTING290 830-X CH09.qxd 9/20/07 2:08 PM Page 290 ScriptEngineManager manager = new ScriptEngineManager (); ScriptEngine engine = manager.getEngineByName ("rhino"); try { System.out.println (engine.eval (new FileReader (args [0]))); System.out.println (engine.eval (args [1])); } catch (ScriptException se) { System.err.println (se.getMessage ()); } catch (IOException ioe) { System.err.println (ioe.getMessage ()); } } } FuncEvaluator is designed to evaluate the functions in a Rhino-based script file via eval(Reader reader). It also uses eval(String script) to evaluate an expression that invokes one of the functions. Both the script file and script expression are passed to FuncEvaluator as command-line arguments. Listing 9-5 presents a sample script file. Listing 9-5. stats.js function combinations (n, r) { return fact (n)/(fact (r)*fact (n-r)) } function fact (n) { if (n == 0) return 1; else return n*fact (n-1); } The stats.js file presents combinations(n, r) and fact(n) functions as part of a sta- tistics package. The combinations(n, r) function works with the factorial function to CHAPTER 9 ■ SCRIPTING 291 830-X CH09.qxd 9/20/07 2:08 PM Page 291 calculate and return the number of different combinations of n items taken r items at a time. For example, how many different poker hands in five-card draw poker (where five cards are dealt to each player) can be dealt from a full card deck? Invoke java FuncEvaluator stats.js combinations(52,5) to discover the answer. After outputting null on the first line (to indicate that stats.js does not return a value), FuncEvaluator outputs 2598960.0 on the line below. The Double value returned from combinations(52,5) indicates that there are 2,598,960 possible poker hands. ■Note Wikipedia’s Combination entry (http://en.wikipedia.org/wiki/Combination) introduces the statistical concept of combinations. Also, Wikipedia’s Five-card draw entry ( http://en.wikipedia.org/ wiki/Five-card_draw) introduces the five-card draw poker variation. Interacting with Java Classes and Interfaces from Scripts The Scripting API is associated with Java language bindings, which are mechanisms that let scripts access Java classes and interfaces, create objects, and invoke methods accord- ing to the syntax of the scripting language. To access a Java class or interface, this type must be prefixed with its fully qualified package name. For example, in a Rhino-based script, you would specify java.lang.Math.PI to access the PI member in Java’s Math class. In contrast, specifying Math.PI accesses the PI member in JavaScript’s Math object. To avoid needing to specify package names throughout a Rhino-based script, the script can employ the importPackage() and importClass() built-in functions to import an entire package of Java types or only a single type, respectively. For example, importPackage(java.awt); imports all of package java.awt’s types, and importClass(java.awt.Frame); imports only the Frame type from this package. ■Note According to the Java Scripting Programmer’s Guide (http://java.sun.com/javase/6/docs/ technotes/guides/scripting/programmer_guide/index.html ), java.lang is not imported by default, to prevent conflicts with same-named JavaScript types—Object, Math, Boolean, and so on. The problem with importPackage() and importClass() is that they pollute JavaScript’s global variable scope. Rhino overcomes this problem by providing a JavaImporter class that works with JavaScript’s with statement to let you specify classes and interfaces with- out their package names from within this statement’s scope. Listing 9-6’s swinggui.js script demonstrates JavaImporter. CHAPTER 9 ■ SCRIPTING292 830-X CH09.qxd 9/20/07 2:08 PM Page 292 [...]... choose to manipulate the default script context instead For example, if you want to send a script’s output to a GUI’s text component, you might install a new writer into the default script context, as demonstrated in Listing 9-9 Listing 9-9 RedirectScriptOutputToGUI .java // RedirectScriptOutputToGUI .java import java. awt.*; import java. awt.event.*; import java. io.*; import javax.script.*; import javax.swing.*;... periods to amortize the loan Running this application with P set to 20000, I set to 6% , and N set to 360 results in this output: Principal = 20000.0 Interest Rate = 6. 0% Months = 360 Monthly Payment = 119.91 The script depends on the existence of script variables principal, intrate, and months These variables (with their object values) are introduced to the script via the put() method—20000.0 and 6. 0 are... are boxed into Doubles; 360 is boxed into an Integer The calculation result is stored in the payment script variable get() returns this Double’s value to Java The get() method returns null if key does not exist Java programs are free to choose any syntactically correct string-based key (based on scripting language syntax) for a script variable’s name, except for those keys beginning with the javax.script... event-dispatching thread The JavaImporter class imports types from the java. awt and javax.swing packages, which are accessible from the with statement’s scope Because JavaImporter does not import java. lang’s types, java. lang must be prepended to Runnable 293 830-X CH09.qxd 294 9/20/ 07 2:08 PM Page 294 CHAPTER 9 ■ SCRIPTING ■ Note Listing 9 -6 also demonstrates implementing Java s Runnable interface in JavaScript via... slightly different results However, these results show a significant speed improvement For example, you might see that the evaluated script took 1515 milliseconds and the compiled script took 78 2 milliseconds ■ Note TestCompilationSpeed does not assume that JavaScript corresponds to the Mozilla Rhino 1 .6 release 2 script engine Recall that a script engine factory and its script engine can be overridden... (http:/ /java. sun.com/javase /6/ docs/technotes/guides/scripting/programmer_guide/index html#interfaces) presents the source code for a pair of applications that further demonstrate the getInterface() methods 315 830-X CH09.qxd 3 16 9/20/ 07 2:08 PM Page 3 16 CHAPTER 9 ■ SCRIPTING Playing with the Command-Line Script Shell Java SE 6 provides jrunscript, an experimental command-line, script-shell tool for... communication with Java The SDK documentation’s jrunscript - command line script shell page (http:/ /java. sun.com/javase /6/ docs/ technotes/tools/share/jrunscript.html) offers a tool reference Also, Appendix B presents a table of command-line options and four usage examples Although jrunscript can be used to evaluate file-based scripts or scripts that are specified on the command line, the easiest way to work with... are prefixed with their java. util and java. lang package names, respectively jrunscript does not import the java. util and java. lang packages by default, although it does import the java. io and java. net packages by default This session also demonstrates the use of JavaScript’s delete operator to delete list and map entries ■ Note If you are wondering why delete sl [1] outputs false, whereas delete props... { new RedirectScriptOutputToGUI (); } }; EventQueue.invokeLater (r); } } class GUIWriter extends Writer { private JTextArea txtOutput; GUIWriter (JTextArea txtOutput) { this.txtOutput = txtOutput; } public void close () { System.out.println ("close"); } public void flush () { System.out.println ("flush"); } public void write (char [] cbuf, int off, int len) { txtOutput.setText (txtOutput.getText ()+new... component Click the Clear button to erase the contents of both text components Figure 9-1 shows the GUI Figure 9-1 By installing a new writer into the default script context, you can send a script’s output to a GUI’s text component To redirect a script’s output to the lower text component, RedirectScriptOutputToGUI creates an instance of GUIWriter and makes this instance available to the script engine via . periods to amortize the loan. Run- ning this application with P set to 20000, I set to 6% , and N set to 360 results in this output: Principal = 20000.0 Interest Rate = 6. 0% Months = 360 Monthly. JavaImporter class imports types from the java. awt and javax.swing packages, which are accessible from the with statement’s scope. Because JavaImporter does not import java. lang’s types, java. lang. version 1.6R2 is included with Java SE 6 build 105. This implementation includes most of Mozilla Rhino, except for JavaScript -to- bytecode compilation, Rhino’s JavaAdapter for extending Java classes