001: /*
002: * Copyright (c) 1998-2006 Caucho Technology -- all rights reserved
003: *
004: * This file is part of Resin(R) Open Source
005: *
006: * Each copy or derived work must preserve the copyright notice and this
007: * notice unmodified.
008: *
009: * Resin Open Source is free software; you can redistribute it and/or modify
010: * it under the terms of the GNU General Public License as published by
011: * the Free Software Foundation; either version 2 of the License, or
012: * (at your option) any later version.
013: *
014: * Resin Open Source is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
017: * of NON-INFRINGEMENT. See the GNU General Public License for more
018: * details.
019: *
020: * You should have received a copy of the GNU General Public License
021: * along with Resin Open Source; if not, write to the
022: * Free SoftwareFoundation, Inc.
023: * 59 Temple Place, Suite 330
024: * Boston, MA 02111-1307 USA
025: *
026: * @author Scott Ferguson
027: */
028:
029: package com.caucho.es;
030:
031: import com.caucho.java.LineMap;
032: import com.caucho.util.Exit;
033: import com.caucho.vfs.Path;
034:
035: import java.util.HashMap;
036:
037: /**
038: * The Script object represents a compiled JavaScript. Executing it
039: * is thread safe. To create a Script, use the Parser class to parse
040: * a file.
041: *
042: * <p>Java programs set JavaScript Global properties by adding objects to
043: * a HashMap. Typically you will at least assign the 'File' and
044: * the 'out' objects. The running script will
045: * see these objects as properties of the Global object. If you set the
046: * 'out' object, the script can use the bare bones 'writeln("foo")' to
047: * write to 'out'.
048: *
049: * <pre><code>
050: * HashMap map = new HashMap();
051: * map.put("File", Vfs.lookup());
052: * map.put("out", System.out);
053: * map.put("myObject", myObject);
054: *
055: * script.execute(map, null);
056: * </code></pre>
057: *
058: * <p>You can also make any Java object be the global prototype.
059: * Essentially, the effect is similar to the HashMap technique, but
060: * it's a little simpler.
061: *
062: * <p>Scripts are thread-safe. Multiple script instances can
063: * safely execute in separate threads. Script.execute creates the
064: * entire JavaScript global object hierarchy fresh for each execution.
065: * So one Script execution cannot interfere with another, even by doing
066: * evil things like modifying the Object prototype.
067: *
068: * <p>Of course, wrapped Java objects shared by script invocations
069: * must still be synchronized.
070: */
071:
072: abstract public class Script {
073: protected Path scriptPath;
074: protected Path classDir;
075:
076: /**
077: * Internal method to check if the source files have changed.
078: */
079: public boolean isModified() {
080: return true;
081: }
082:
083: /**
084: * Internal method to set the script search path for imported
085: * scripts.
086: */
087: public void setScriptPath(Path scriptPath) {
088: this .scriptPath = scriptPath;
089: }
090:
091: /**
092: * Internal method to set the work directory for generated *.java
093: * and *.class.
094: */
095: public void setClassDir(Path classDir) {
096: this .classDir = classDir;
097: }
098:
099: /**
100: * Returns the map from source file line numbers to the generated
101: * java line numbers.
102: */
103: public LineMap getLineMap() {
104: return null;
105: }
106:
107: /**
108: * Execute the script; the main useful entry.
109: *
110: * <p>Calling programs can make Java objects available as properties
111: * of the global object by creating a property hash map or assigning
112: * a global prototype.
113: *
114: * <pre><code>
115: * HashMap map = new HashMap();
116: * map.put("File", Vfs.lookup());
117: * map.put("out", System.out);
118: * map.put("myObject", myObject);
119: * script.execute(map, null);
120: * </code></pre>
121: *
122: * Then the JavaScript can use the defined objects:
123: * <pre><code>
124: * out.println(myObject.myMethod("foo"));
125: * </code></pre>
126: *
127: * @param properties A hash map of global properties.
128: * @param proto Global prototype. Gives the script direct access to
129: * the java methods of the object.
130: *
131: * @return String value of the last expression, like the JavaScript eval.
132: * This is useful only for testing.
133: */
134: public String execute(HashMap properties, Object proto)
135: throws Throwable {
136: Global oldGlobal = Global.getGlobalProto();
137: boolean doExit = Exit.addExit();
138:
139: try {
140: Global resin = new Global(properties, proto, classDir,
141: scriptPath, getClass().getClassLoader());
142:
143: resin.begin();
144:
145: ESGlobal global = initClass(resin);
146:
147: ESBase value = global.execute();
148:
149: if (value == null)
150: return null;
151: else
152: return value.toStr().toString();
153: } finally {
154: Global.end(oldGlobal);
155:
156: if (doExit)
157: Exit.exit();
158: }
159: }
160:
161: /**
162: * Execute the program, returning a closure of the global state.
163: * <code>executeClosure</code> will execute the global script.
164: *
165: * <p>Later routines can then call into the closure. The closure
166: * is not thread-safe. So only a single thread may execute the
167: * closure.
168: *
169: * @param properties A hash map of global properties.
170: * @param proto Global prototype. Gives the script direct access to
171: * the java methods of the object.
172: *
173: * @return the closure
174: */
175: public ScriptClosure executeClosure(HashMap properties, Object proto)
176: throws Throwable {
177: Global resin = new Global(properties, proto, classDir,
178: scriptPath, getClass().getClassLoader());
179: boolean doExit = Exit.addExit();
180: Global oldGlobal = resin.begin();
181:
182: try {
183: ESGlobal global = initClass(resin);
184:
185: global.execute();
186:
187: return new ScriptClosure(resin, global, this );
188: } finally {
189: resin.end(oldGlobal);
190: if (doExit)
191: Exit.exit();
192: }
193: }
194:
195: /**
196: * Internal method to initialize the script after loading it.
197: */
198: public ESGlobal initClass(Global resin, ESObject global)
199: throws Throwable {
200: return initClass(resin);
201: }
202:
203: /**
204: * Internal method implemented by the generated script for initialization.
205: */
206: public abstract ESGlobal initClass(Global resin) throws Throwable;
207:
208: /**
209: * Internal method to export objects.
210: */
211: public void export(ESObject dest, ESObject src) throws Throwable {
212: }
213: }
|