Package groovy.util

# Class GroovyScriptEngine

java.lang.Object
groovy.util.GroovyScriptEngine

All Implemented Interfaces:
  `ResourceConnector`

public class GroovyScriptEngine extends Object implements ResourceConnector
Specific script engine able to reload modified scripts as well as dealing properly with dependent scripts.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GroovyScriptEngine(ResourceConnector rc)`
  Creates a script engine that delegates resource lookup to the supplied connector.
  `GroovyScriptEngine(ResourceConnector rc, ClassLoader parentClassLoader)`
  Creates a script engine that delegates resource lookup to the supplied connector.
  `GroovyScriptEngine(String url)`
  Creates a script engine for a single root location.
  `GroovyScriptEngine(String[] urls)`
  Creates a script engine from string root locations.
  `GroovyScriptEngine(String[] urls, ClassLoader parentClassLoader)`
  Creates a script engine from string root locations.
  `GroovyScriptEngine(String url, ClassLoader parentClassLoader)`
  Creates a script engine for a single root location.
  `GroovyScriptEngine(URL[] roots)`
  Creates a script engine rooted at the supplied URLs.
  `GroovyScriptEngine(URL[] roots, ClassLoader parentClassLoader)`
  Creates a script engine rooted at the supplied URLs.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Script`
  `createScript(String scriptName, Binding binding)`
  Creates a Script with a given scriptName and binding.
  `CompilerConfiguration`
  `getConfig()`
  `protected long`
  `getCurrentTime()`
  Returns the current time used for recompilation checks.
  `GroovyClassLoader`
  `getGroovyClassLoader()`
  Returns the GroovyClassLoader associated with this script engine instance.
  `ClassLoader`
  `getParentClassLoader()`
  Get the `ClassLoader` that will serve as the parent ClassLoader of the `GroovyClassLoader` in which scripts will be executed.
  `URLConnection`
  `getResourceConnection(String resourceName)`
  Get a resource connection as a `URLConnection` to retrieve a script from the `ResourceConnector`.
  `protected boolean`
  `isSourceNewer(groovy.util.GroovyScriptEngine.ScriptCacheEntry entry)`
  Determines whether a cached script or one of its dependencies should be recompiled.
  `Class`
  `loadScriptByName(String scriptName)`
  Get the class of the scriptName in question, so that you can instantiate Groovy objects with caching and reloading.
  `static void`
  `main(String[] urls)`
  Simple testing harness for the GSE.
  `Object`
  `run(String scriptName, Binding binding)`
  Run a script identified by name with a given binding.
  `String`
  `run(String scriptName, String argument)`
  Run a script identified by name with a single argument.
  `void`
  `setConfig(CompilerConfiguration config)`
  sets a compiler configuration

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### GroovyScriptEngine

    public GroovyScriptEngine(URL[] roots)
    Creates a script engine rooted at the supplied URLs.
    Parameters:
      `roots` - script root URLs

  - ### GroovyScriptEngine

    public GroovyScriptEngine(URL[] roots, ClassLoader parentClassLoader)
    Creates a script engine rooted at the supplied URLs.
    Parameters:
      `roots` - script root URLs
      `parentClassLoader` - parent class loader for compiled scripts

  - ### GroovyScriptEngine

    public GroovyScriptEngine(String[] urls) throws IOException
    Creates a script engine from string root locations.
    Parameters:
      `urls` - script root URLs or file paths
    Throws:
      `IOException` - if a root cannot be converted to a URL

  - ### GroovyScriptEngine

    public GroovyScriptEngine(String[] urls, ClassLoader parentClassLoader) throws IOException
    Creates a script engine from string root locations.
    Parameters:
      `urls` - script root URLs or file paths
      `parentClassLoader` - parent class loader for compiled scripts
    Throws:
      `IOException` - if a root cannot be converted to a URL

  - ### GroovyScriptEngine

    public GroovyScriptEngine(String url) throws IOException
    Creates a script engine for a single root location.
    Parameters:
      `url` - script root URL or file path
    Throws:
      `IOException` - if the root cannot be converted to a URL

  - ### GroovyScriptEngine

    public GroovyScriptEngine(String url, ClassLoader parentClassLoader) throws IOException
    Creates a script engine for a single root location.
    Parameters:
      `url` - script root URL or file path
      `parentClassLoader` - parent class loader for compiled scripts
    Throws:
      `IOException` - if the root cannot be converted to a URL

  - ### GroovyScriptEngine

    public GroovyScriptEngine(ResourceConnector rc)
    Creates a script engine that delegates resource lookup to the supplied connector.
    Parameters:
      `rc` - resource connector used to resolve scripts

  - ### GroovyScriptEngine

    public GroovyScriptEngine(ResourceConnector rc, ClassLoader parentClassLoader)
    Creates a script engine that delegates resource lookup to the supplied connector.
    Parameters:
      `rc` - resource connector used to resolve scripts
      `parentClassLoader` - parent class loader for compiled scripts

- ## Method Details

  - ### main

    public static void main(String[] urls) throws 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:
      `Exception` - if something goes wrong

  - ### getResourceConnection

    public URLConnection getResourceConnection(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 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:
      the parent classloader used to load scripts

  - ### loadScriptByName

    public Class loadScriptByName(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

  - ### run

    public String run(String scriptName, 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 Object run(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(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

  - ### isSourceNewer

    protected boolean isSourceNewer(groovy.util.GroovyScriptEngine.ScriptCacheEntry entry)
    Determines whether a cached script or one of its dependencies should be recompiled.
    Parameters:
      `entry` - the cached script entry
    Returns:
      `true` if recompilation is required

  - ### 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

  - ### getConfig

    public CompilerConfiguration getConfig()
    Returns:
      a non null compiler configuration

  - ### setConfig

    public void setConfig(CompilerConfiguration config)
    sets a compiler configuration
    Parameters:
      `config` - - the compiler configuration
    Throws:
      `NullPointerException` - if config is null

  - ### getCurrentTime

    protected long getCurrentTime()
    Returns the current time used for recompilation checks.
    Returns:
      the current time in milliseconds