Package: groovy.util

## [Java] Class GroovyScriptEngine

- groovy.util.GroovyScriptEngine

- All Implemented Interfaces and Traits:
    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 and description
    `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.
    `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)` Creates a script engine for a single root location.
    `GroovyScriptEngine(String url, ClassLoader parentClassLoader)` Creates a script engine for a single root location.
    `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.

  - ### Methods Summary

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

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### public GroovyScriptEngine(URL[] roots)

      Creates a script engine rooted at the supplied URLs.

      Parameters:
        `roots` - script root URLs

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

    - #### public GroovyScriptEngine(String[] urls)

      Creates a script engine from string root locations.

      throws:
        IOException if a root cannot be converted to a URL
      Parameters:
        `urls` - script root URLs or file paths

    - #### public GroovyScriptEngine(String[] urls, ClassLoader parentClassLoader)

      Creates a script engine from string root locations.

      throws:
        IOException if a root cannot be converted to a URL
      Parameters:
        `urls` - script root URLs or file paths
        `parentClassLoader` - parent class loader for compiled scripts

    - #### public GroovyScriptEngine(String url)

      Creates a script engine for a single root location.

      throws:
        IOException if the root cannot be converted to a URL
      Parameters:
        `url` - script root URL or file path

    - #### public GroovyScriptEngine(String url, ClassLoader parentClassLoader)

      Creates a script engine for a single root location.

      throws:
        IOException if the root cannot be converted to a URL
      Parameters:
        `url` - script root URL or file path
        `parentClassLoader` - parent class loader for compiled scripts

    - #### public GroovyScriptEngine(ResourceConnector rc)

      Creates a script engine that delegates resource lookup to the supplied connector.

      Parameters:
        `rc` - resource connector used to resolve scripts

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

    - #### public Script createScript(String scriptName, Binding binding)

      Creates a Script with a given scriptName and binding.

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

    - #### public CompilerConfiguration getConfig()

      Returns:
        a non null compiler configuration

    - #### protected long getCurrentTime()

      Returns the current time used for recompilation checks.

      Returns:
        the current time in milliseconds

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

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

    - #### public URLConnection getResourceConnection(String resourceName)

      Get a resource connection as a `URLConnection` to retrieve a script from the `ResourceConnector`.

      throws:
        ResourceException
      Parameters:
        `resourceName` - name of the resource to be retrieved
      Returns:
        a URLConnection to the resource

    - #### protected boolean isSourceNewer(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

    - #### public Class loadScriptByName(String scriptName)

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

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

    - #### public static void main(String[] urls)

      Simple testing harness for the GSE. Enter script roots as arguments and then input script names to run them.

      throws:
        Exception if something goes wrong
      Parameters:
        `urls` - an array of URLs

    - #### public String run(String scriptName, String argument)

      Run a script identified by name with a single argument.

      throws:
        ResourceException if there is a problem accessing the script
      throws:
        ScriptException if there is a problem parsing the script
      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

    - #### public Object run(String scriptName, Binding binding)

      Run a script identified by name with a given binding.

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

    - #### public void setConfig(CompilerConfiguration config)

      sets a compiler configuration

      throws:
        NullPointerException if config is null
      Parameters:
        `config` - - the compiler configuration