groovy.util
Class GroovyScriptEngine

java.lang.Object
  extended by groovy.util.GroovyScriptEngine
All Implemented Interfaces:
ResourceConnector

public class GroovyScriptEngine
extends java.lang.Object
implements ResourceConnector

Specific script engine able to reload modified scripts as well as dealing properly with dependent scripts.

Author:
sam, Marc Palmer, Guillaume Laforge

Nested Class Summary
private static class GroovyScriptEngine.ScriptCacheEntry
           
 
Field Summary
private static java.lang.ThreadLocal currentCacheEntryHolder
           
private  GroovyClassLoader groovyLoader
           
private  ResourceConnector rc
           
private  java.net.URL[] roots
           
private  java.util.Map scriptCache
           
 
Constructor Summary
GroovyScriptEngine(ResourceConnector rc)
           
GroovyScriptEngine(ResourceConnector rc, java.lang.ClassLoader parentClassLoader)
           
GroovyScriptEngine(java.lang.String url)
           
GroovyScriptEngine(java.lang.String[] urls)
           
GroovyScriptEngine(java.lang.String[] urls, java.lang.ClassLoader parentClassLoader)
           
GroovyScriptEngine(java.lang.String url, java.lang.ClassLoader parentClassLoader)
           
GroovyScriptEngine(java.net.URL[] roots)
          The groovy script engine will run groovy scripts and reload them and their dependencies when they are modified.
GroovyScriptEngine(java.net.URL[] roots, java.lang.ClassLoader parentClassLoader)
           
 
Method Summary
 Script createScript(java.lang.String scriptName, Binding binding)
          Creates a Script with a given scriptName and binding.
private  boolean dependencyOutOfDate(GroovyScriptEngine.ScriptCacheEntry entry)
           
 GroovyClassLoader getGroovyClassLoader()
          Returns the GroovyClassLoader associated with this script engine instance.
 java.lang.ClassLoader getParentClassLoader()
          Get the ClassLoader that will serve as the parent ClassLoader of the GroovyClassLoader in which scripts will be executed.
 java.net.URLConnection getResourceConnection(java.lang.String resourceName)
          Get a resource connection as a URLConnection to retrieve a script from the ResourceConnector.
private  void initGroovyLoader(java.lang.ClassLoader parentClassLoader)
          Initialize a new GroovyClassLoader with the parentClassLoader passed as a parameter.
 java.lang.Class loadScriptByName(java.lang.String scriptName)
          Get the class of the scriptName in question, so that you can instantiate Groovy objects with caching and reloading.
 java.lang.Class loadScriptByName(java.lang.String scriptName, java.lang.ClassLoader parentClassLoader)
          Deprecated.  
static void main(java.lang.String[] urls)
          Simple testing harness for the GSE.
 java.lang.Object run(java.lang.String scriptName, Binding binding)
          Run a script identified by name with a given binding.
 java.lang.String run(java.lang.String scriptName, java.lang.String argument)
          Run a script identified by name with a single argument.
 void setParentClassLoader(java.lang.ClassLoader parentClassLoader)
          Deprecated.  
private  GroovyScriptEngine.ScriptCacheEntry updateCacheEntry(java.lang.String scriptName)
          Locate the class and reload it or any of its dependencies
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

roots

private java.net.URL[] roots

scriptCache

private java.util.Map scriptCache

rc

private ResourceConnector rc

currentCacheEntryHolder

private static java.lang.ThreadLocal currentCacheEntryHolder

groovyLoader

private GroovyClassLoader groovyLoader
Constructor Detail

GroovyScriptEngine

public GroovyScriptEngine(java.net.URL[] roots)
The groovy script engine will run groovy scripts and reload them and their dependencies when they are modified. This is useful for embedding groovy in other containers like games and application servers.

Parameters:
roots - This an array of URLs where Groovy scripts will be stored. They should be layed out using their package structure like Java classes

GroovyScriptEngine

public GroovyScriptEngine(java.net.URL[] roots,
                          java.lang.ClassLoader parentClassLoader)

GroovyScriptEngine

public GroovyScriptEngine(java.lang.String[] urls)
                   throws java.io.IOException
Throws:
java.io.IOException

GroovyScriptEngine

public GroovyScriptEngine(java.lang.String[] urls,
                          java.lang.ClassLoader parentClassLoader)
                   throws java.io.IOException
Throws:
java.io.IOException

GroovyScriptEngine

public GroovyScriptEngine(java.lang.String url)
                   throws java.io.IOException
Throws:
java.io.IOException

GroovyScriptEngine

public GroovyScriptEngine(java.lang.String url,
                          java.lang.ClassLoader parentClassLoader)
                   throws java.io.IOException
Throws:
java.io.IOException

GroovyScriptEngine

public GroovyScriptEngine(ResourceConnector rc)

GroovyScriptEngine

public GroovyScriptEngine(ResourceConnector rc,
                          java.lang.ClassLoader parentClassLoader)
Method Detail

main

public static void main(java.lang.String[] urls)
                 throws java.lang.Exception
Simple testing harness for the GSE. Enter script roots as arguments and then input script names to run them.

Parameters:
urls - an array of URLs
Throws:
java.lang.Exception - if something goes wrong

initGroovyLoader

private void initGroovyLoader(java.lang.ClassLoader parentClassLoader)
Initialize a new GroovyClassLoader with the parentClassLoader passed as a parameter. A GroovyScriptEngine should only use one GroovyClassLoader but since in version prior to 1.0-RC-01 you could set a new parentClassLoader Ultimately groovyLoader should be final and only set in the constructor

Parameters:
parentClassLoader - the class loader to use

getResourceConnection

public java.net.URLConnection getResourceConnection(java.lang.String resourceName)
                                             throws ResourceException
Get a resource connection as a URLConnection to retrieve a script from the ResourceConnector.

Specified by:
getResourceConnection in interface ResourceConnector
Parameters:
resourceName - name of the resource to be retrieved
Returns:
a URLConnection to the resource
Throws:
ResourceException

getParentClassLoader

public java.lang.ClassLoader getParentClassLoader()
Get the ClassLoader that will serve as the parent ClassLoader of the GroovyClassLoader in which scripts will be executed. By default, this is the ClassLoader that loaded the GroovyScriptEngine class.

Returns:
parent classloader used to load scripts

setParentClassLoader

public void setParentClassLoader(java.lang.ClassLoader parentClassLoader)
Deprecated. 

Parameters:
parentClassLoader - ClassLoader to be used as the parent ClassLoader for scripts executed by the engine

loadScriptByName

public java.lang.Class loadScriptByName(java.lang.String scriptName)
                                 throws ResourceException,
                                        ScriptException
Get the class of the scriptName in question, so that you can instantiate Groovy objects with caching and reloading.

Parameters:
scriptName - resource name pointing to the script
Returns:
the loaded scriptName as a compiled class
Throws:
ResourceException - if there is a problem accessing the script
ScriptException - if there is a problem parsing the script

loadScriptByName

public java.lang.Class loadScriptByName(java.lang.String scriptName,
                                        java.lang.ClassLoader parentClassLoader)
                                 throws ResourceException,
                                        ScriptException
Deprecated. 

Get the class of the scriptName in question, so that you can instantiate Groovy objects with caching and reloading.

Parameters:
scriptName - resource name pointing to the script
parentClassLoader - the class loader to use when loading the script
Returns:
the loaded scriptName as a compiled class
Throws:
ResourceException - if there is a problem accessing the script
ScriptException - if there is a problem parsing the script

updateCacheEntry

private GroovyScriptEngine.ScriptCacheEntry updateCacheEntry(java.lang.String scriptName)
                                                      throws ResourceException,
                                                             ScriptException
Locate the class and reload it or any of its dependencies

Parameters:
scriptName - resource name pointing to the script
Returns:
the cache entry for scriptName
Throws:
ResourceException - if there is a problem accessing the script
ScriptException - if there is a problem parsing the script

dependencyOutOfDate

private boolean dependencyOutOfDate(GroovyScriptEngine.ScriptCacheEntry entry)

run

public java.lang.String run(java.lang.String scriptName,
                            java.lang.String argument)
                     throws ResourceException,
                            ScriptException
Run a script identified by name with a single argument.

Parameters:
scriptName - name of the script to run
argument - a single argument passed as a variable named arg in the binding
Returns:
a toString() representation of the result of the execution of the script
Throws:
ResourceException - if there is a problem accessing the script
ScriptException - if there is a problem parsing the script

run

public java.lang.Object run(java.lang.String scriptName,
                            Binding binding)
                     throws ResourceException,
                            ScriptException
Run a script identified by name with a given binding.

Parameters:
scriptName - name of the script to run
binding - the binding to pass to the script
Returns:
an object
Throws:
ResourceException - if there is a problem accessing the script
ScriptException - if there is a problem parsing the script

createScript

public Script createScript(java.lang.String scriptName,
                           Binding binding)
                    throws ResourceException,
                           ScriptException
Creates a Script with a given scriptName and binding.

Parameters:
scriptName - name of the script to run
binding - the binding to pass to the script
Returns:
the script object
Throws:
ResourceException - if there is a problem accessing the script
ScriptException - if there is a problem parsing the script

getGroovyClassLoader

public GroovyClassLoader getGroovyClassLoader()
Returns the GroovyClassLoader associated with this script engine instance. Useful if you need to pass the class loader to another library.

Returns:
the GroovyClassLoader


Copyright © ${year} The Codehaus. All Rights Reserved.