com.partnersoft.scripting

Interface Script

All Superinterfaces:

java.lang.Runnable

All Known Implementing Classes:

AbstractScript, BeanShellScript, GroovyScript, RubyScript, ScriptEngineScript, StringTemplateScript

public interface Script
extends java.lang.Runnable

Generic interface for scripting language scripts.

Implementations must obey the following rules.

First, no exceptions may be thrown by runScript(). In fact, catching Throwable (so as to get RuntimeExceptions, OutOfMemoryError, etc.) is generally recommended. Often a running system can recover from a script's OutOfMemoryError. Instead of being thrown, uncaught Throwables should be logged as errors and made available via the getThrown() method. Note that this does not prevent the script itself from catching and handling its own exceptions; it only applies to exceptions that are not caught by the script.

Second, scripts should be cached and compiled for efficiency (whatever that means for the given language). However, they should be reloaded and recompiled whenever the backing file(s) change. Use methods like VfsFile.getLastModifiedMillis() to determine whether a file has changed efficiently.

Scripts should have their own logging context. In general this should correspond to the full classname of the Script implementation, plus the URL, file, or other location of the script itself. For example:

 private static final Log log = LogFactory.getLog(FOOScript.class.getName()
                + ":" + scriptPath);
 

Most scripts require some kind of input; this is allowed through the use of settable variables (setVariable(String, Object) and setVariables(Naming)). The values of variables can be of any appropriate type (assuming that the scripting language understands it of course). All script implementations should provide "log" as a built-in variable, set to the Log instance as described above, and "script", set to the Script implementation itself. Generally "result" will be the variable used to set a return value.

Copyright 2005-2006 Partner Software, Inc.

Author:

Paul Reavis

Method Summary

Methods

Modifier and Type	Method and Description
VfsFile	getFile() If the script is associated with a file, return the file.
java.lang.String	getName() Returns the name of the script.
Log	getScriptLog() Returns the Log context for the script.
java.lang.Throwable	getThrown() If, during execution, the script terminates and throws an otherwise-uncaught exception, that exception will be available here.
java.lang.Object	getVariable(java.lang.String name) Gets a single variable defined for the script.
Naming<java.lang.Object>	getVariables() Gets all defined variables in the script.
boolean	isModified() Returns true if the script has changed since the last time it was run.
boolean	parse() Parses the script, and returns true if it looks reasonably valid.
void	run() Executes the script exactly as in runScript(), but without returning a result.
java.lang.Object	runScript() Executes the script, and returns a result.
ScriptThread	runThreaded() Executes the script exactly as in run(), but in a separate thread (specifically, a ScriptThread).
void	setVariable(java.lang.String name, java.lang.Object value) Sets a single variable in the script.
void	setVariables(Naming<java.lang.Object> newVariables) Sets all variables (except for predefined ones like "log") in one swell foop.

Method Detail

runScript

java.lang.Object runScript()

Executes the script, and returns a result. No exceptions will be thrown, at all. If the script terminates abnormally and an exception is caught, it will be logged; you may also retrieve such an exception from the getThrown() method.

Returns:

result of script (null if none)

run

void run()

Executes the script exactly as in runScript(), but without returning a result. The sole purpose of this method is to implement the Runnable interface, which makes threading etc. easier. Subclasses will generally simply call runScript().

Specified by:

run in interface java.lang.Runnable

runThreaded

ScriptThread runThreaded()

Executes the script exactly as in run(), but in a separate thread (specifically, a ScriptThread). Returns the thread.

parse

boolean parse()

Parses the script, and returns true if it looks reasonably valid. Parsing means different things to different script types, but generally this should do whatever preparation, parsing, compiling, etc. that can be done without actually performing the actions specified in the script.

getName

java.lang.String getName()

Returns the name of the script. Generally this is the file name (without file extension or path).

Returns:

script name

setVariable

void setVariable(java.lang.String name,
               java.lang.Object value)

Sets a single variable in the script. The name parameter must be a valid variable name in the scripting language.

Parameters:

name - name of the variable in the script

value - value of the variable in the script

getVariable

java.lang.Object getVariable(java.lang.String name)

Gets a single variable defined for the script. After a script run, can be used to get a variable set within the script itself. Before the script run only provides values that were set using setVariable(String, Object).

Parameters:

name - name of the variable in the script

Returns:

value of the variable, or null if it's not defined

getVariables

Naming<java.lang.Object> getVariables()

Gets all defined variables in the script.

Returns:

naming of all variables

setVariables

void setVariables(Naming<java.lang.Object> newVariables)

Sets all variables (except for predefined ones like "log") in one swell foop. Erases any previous definitions.

Parameters:

newVariables -

getThrown

java.lang.Throwable getThrown()

If, during execution, the script terminates and throws an otherwise-uncaught exception, that exception will be available here. Otherwise getThrown() returns null.

Returns:

uncaught exception from last script run, null if none

getScriptLog

Log getScriptLog()

Returns the Log context for the script. Each script should have its own logging context. In general this should correspond to the full classname of the Script implementation, plus the URL, file, or other location of the script itself. For example:

 private static final Log log = LogFactory.getLog(FOOScript.class.getName()
                + "." + scriptPath);
 

isModified

boolean isModified()

Returns true if the script has changed since the last time it was run.

getFile

VfsFile getFile()

If the script is associated with a file, return the file. Otherwise return null;