com.partnersoft.scripting
Class AbstractScript

java.lang.Object
  com.partnersoft.scripting.AbstractScript

All Implemented Interfaces:

Script, java.lang.Runnable

Direct Known Subclasses:

BeanShellScript, GroovyScript, ScriptEngineScript, StringTemplateScript

public abstract class AbstractScript
extends java.lang.Object
implements Script

Abstract implementation of Script. Provides a standard framework for reloadable, "compileable" scripts.

You should only have to implement the *Imp() methods; you may feel free to throw any exceptions and they will be dealt with appropriately.

Example implementation:

 public class FooScript extends AbstractScript {
        protected void reloadImp() throws Exception {
                // source file changed; compile or reparse or reload or whatever
        }
 
        protected Object runScriptImp(Naming<Object> variables) throws Exception {
                // set variables and run the script, returning the result
        }
 }
 

Copyright 2007 Partner Software, Inc.

Version:

$Id: AbstractScript.java 2474 2010-03-13 14:28:43Z paul $

Author:

Paul Reavis

Constructor Summary

AbstractScript(VfsFile file)

Method Summary

VfsFile	getFile()
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.
protected abstract void	reloadImp() Subclasses should implement this method to do any maintenance associated with changes in the source file.
void	run() Executes the script exactly as in Script.runScript(), but without returning a result.
java.lang.Object	runScript() Executes the script, and returns a result.
protected abstract java.lang.Object	runScriptImp(Naming<java.lang.Object> variables) Subclasses should implement this method with their actual script-running implementation.
ScriptThread	runThreaded() Executes the script exactly as in Script.run(), but in a separate thread (specifically, a ScriptThread).
protected void	setThrown(java.lang.Throwable throwup) Subclasses can use this to set the exception returned by getThrown().
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.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractScript

public AbstractScript(VfsFile file)

Method Detail

setThrown

protected void setThrown(java.lang.Throwable throwup)

Subclasses can use this to set the exception returned by getThrown(). Note that this is taken care of by the default run() and runScript() methods, so shouldn't be necessary unless you have overridden those in some fashion.

reloadImp

protected abstract void reloadImp()
                           throws java.lang.Exception

Subclasses should implement this method to do any maintenance associated with changes in the source file. This method is called whenever the source file's modification timestamp changes. Use it to load, parse, compile, or whatever you do with the scripting language in question to get it ready to execute. Feel free to throw exceptions; these will be caught and handled appropriately (logging the error, providing the Throwable in getThrown(), etc.).

Throws:

java.lang.Exception

runScriptImp

protected abstract java.lang.Object runScriptImp(Naming<java.lang.Object> variables)
                                          throws java.lang.Exception

Subclasses should implement this method with their actual script-running implementation. They should feel free to throw exceptions; these will be caught and handled appropriately (logging the error, providing the Throwable in getThrown(), etc.).

Throws:

java.lang.Exception

runThreaded

public ScriptThread runThreaded()

Description copied from interface: Script

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

Specified by:

runThreaded in interface Script

parse

public boolean parse()

Description copied from interface: Script

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.

Specified by:

parse in interface Script

runScript

public java.lang.Object runScript()

Description copied from interface: Script

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 Script.getThrown() method.

Specified by:

runScript in interface Script

Returns:

result of script (null if none)

getName

public java.lang.String getName()

Description copied from interface: Script

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

Specified by:

getName in interface Script

Returns:

script name

getThrown

public java.lang.Throwable getThrown()

Description copied from interface: Script

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

Specified by:

getThrown in interface Script

Returns:

uncaught exception from last script run, null if none

getVariable

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

Description copied from interface: Script

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 Script.setVariable(String, Object).

Specified by:

getVariable in interface Script

Parameters:

name - name of the variable in the script

Returns:

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

getVariables

public Naming<java.lang.Object> getVariables()

Description copied from interface: Script

Gets all defined variables in the script.

Specified by:

getVariables in interface Script

Returns:

naming of all variables

run

public void run()

Description copied from interface: Script

Executes the script exactly as in Script.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 Script

Specified by:

run in interface java.lang.Runnable

setVariable

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

Description copied from interface: Script

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

Specified by:

setVariable in interface Script

Parameters:

name - name of the variable in the script

value - value of the variable in the script

setVariables

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

Description copied from interface: Script

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

Specified by:

setVariables in interface Script

getScriptLog

public Log getScriptLog()

Description copied from interface: Script

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);
 

Specified by:

getScriptLog in interface Script

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getFile

public VfsFile getFile()

isModified

public boolean isModified()

Description copied from interface: Script

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

Specified by:

isModified in interface Script