java.lang.Object

ch.grengine.BaseGrengine

ch.grengine.Grengine

All Implemented Interfaces:: Closeable, AutoCloseable

public class Grengine extends BaseGrengine

Grengine.

See BaseGrengine for most convenience methods for using Grengine.

The matrix for running scripts is as follows:

run(<loader>,<source>,<binding>)
<loader>: can be a specific loader or be omitted for the default loader
<source>: can be an instance of source or indicated by script text, file or URL
<binding>: can be an instance of Binding, a map or be omitted for an empty binding

Examples:

run("println 'hello world!'"): default loader, text-based source, empty binding
run(myLoader, URI.create("http://acme.org/myScript.groovy").toURL(), myBinding): given loader, URL-based source, given binding

The matrices for loading classes, creating script instances and for creating sources are similar:

load(<loader>,<source>)
create(<loader>,<source>)
source(<source>)

Grengine performance:

In my experience it is crucial to measure performance under circumstances that come as close as possible to the actual application.
What can be said independently of actual circumstances is:
- Compiling a very simple script is of the order of milliseconds.
- Running it with Grengine by script text or script file is of the order of microseconds (except for the first run or other circumstances where (re-)compilation is mandated).
- Running it from an already created instance of Script is of the order of nanoseconds.
Run the GrengineVisualPerformanceTest and see the options of DefaultSourceFactory.

Since:: 1.0
Author:: Alain Stalder, Made in Switzerland.

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static class

Grengine.Builder

Builder for instances of Grengine.

static class

Grengine.Grape

Convenience class for easily getting a Grengine that works with Grape.
Field Summary

Fields

Modifier and Type

Field

Description

static final long

LATENCY_MS_INFINITE_STATIC

constant for an infinite latency (static).

Fields inherited from class ch.grengine.BaseGrengine
engine, loader, sourceFactory
Constructor Summary

Constructors

Modifier

Constructor

Description

Grengine()

constructor for a Grengine without any (static) code layers, but with a top code cache.

protected

Grengine(Grengine.Builder builder)

constructor from builder.

Grengine(File dir)

constructor for a Grengine based on scripts in a given script directory, without subdirectories, and with a top code cache.

Grengine(File dir, DirMode dirMode)

constructor for a Grengine based on scripts in a given script directory, optionally including subdirectories (recursively), and with a top code cache.

Grengine(ClassLoader parent)

constructor for a Grengine without any (static) code layers, but with a top code cache.

Grengine(ClassLoader parent, File dir)

constructor for a Grengine based on scripts in a given script directory, without subdirectories, and with a top code cache.

Grengine(ClassLoader parent, File dir, DirMode dirMode)

constructor for a Grengine based on scripts in a given script directory, optionally including subdirectories (recursively), and with a top code cache.

Grengine(ClassLoader parent, Collection<URL> urls)

constructor for a Grengine based on a collection of URL-based scripts, with a top code cache, and with tracking URLs based on content.

Grengine(ClassLoader parent, CompilerConfiguration config)

constructor for a Grengine without any (static) code layers, but with a top code cache.

Grengine(ClassLoader parent, CompilerConfiguration config, File dir)

constructor for a Grengine based on scripts in a given script directory, without subdirectories, and with a top code cache.

Grengine(ClassLoader parent, CompilerConfiguration config, File dir, DirMode dirMode)

constructor for a Grengine based on scripts in a given script directory, optionally including subdirectories (recursively), and with a top code cache.

Grengine(ClassLoader parent, CompilerConfiguration config, Collection<URL> urls)

constructor for a Grengine based on a collection of URL-based scripts, with a top code cache, and with tracking URLs based on content.

Grengine(Collection<URL> urls)

constructor for a Grengine based on a collection of URL-based scripts, with a top code cache, and with tracking URLs based on content.

Grengine(CompilerConfiguration config)

constructor for a Grengine without any (static) code layers, but with a top code cache.

Grengine(CompilerConfiguration config, File dir)

constructor for a Grengine based on scripts in a given script directory, without subdirectories, and with a top code cache.

Grengine(CompilerConfiguration config, File dir, DirMode dirMode)

constructor for a Grengine based on scripts in a given script directory, optionally including subdirectories (recursively), and with a top code cache.

Grengine(CompilerConfiguration config, Collection<URL> urls)

constructor for a Grengine based on a collection of URL-based scripts, with a top code cache, and with tracking URLs based on content.
Method Summary

Modifier and Type

Method

Description

Grengine.Builder

getBuilder()

gets the builder.

GrengineException

getLastUpdateException()

updates code layers if necessary and gets the exception that occurred at the last update.

Class<?>

loadClass(Loader loader, Source source, String name)

loads a class with the given name and from the given source from the given loader.

Class<?>

loadClass(Loader loader, String name)

loads a class by name from the given loader.

Class<?>

loadClass(Source source, String name)

loads a class with the given name and from the given source from the default loader.

Class<?>

loadClass(String name)

loads a class by name from the default loader.

Class<?>

loadMainClass(Loader loader, Source source)

loads the main class of the given source from the given loader.

Class<?>

loadMainClass(Source source)

loads the main class of the given source from the default loader.

protected void

updateEngineIfSourcesLayersModified()

updates the engine if sources layers have been modified.

Methods inherited from class ch.grengine.BaseGrengine
asClassLoader, asClassLoader, binding, binding, binding, binding, binding, binding, close, create, create, create, create, create, create, create, create, create, create, create, getEngine, getLoader, getSourceFactory, load, load, load, load, load, load, load, load, load, load, newAttachedLoader, newDetachedLoader, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, run, source, source, source, source

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- LATENCY_MS_INFINITE_STATIC
  
  public static final long LATENCY_MS_INFINITE_STATIC
  
  constant for an infinite latency (static).
  Since:
  
  1.0
  
  See Also:
  
  Constant Field Values
Constructor Details
- Grengine
  
  protected Grengine(Grengine.Builder builder)
  
  constructor from builder.
  Call getLastUpdateException() after constructing if you need to make sure all sources could be compiled without errors.
  
  Parameters:
  
  builder - builder
  
  Since:
  
  1.0
- Grengine
  
  public Grengine()
  
  constructor for a Grengine without any (static) code layers, but with a top code cache.
  Constructed from a builder with default settings.
  
  Since:
  
  1.0
- Grengine
  
  public Grengine(CompilerConfiguration config)
  
  constructor for a Grengine without any (static) code layers, but with a top code cache.
  Constructed from a builder with default settings.
  
  Parameters:
  
  config - compiler configuration to use for compiling all sources
  
  Throws:
  
  NullPointerException - if the compiler configuration is null
  
  Since:
  
  1.0
- Grengine
  
  public Grengine(ClassLoader parent)
  
  constructor for a Grengine without any (static) code layers, but with a top code cache.
  Constructed from a builder with default settings.
  
  Parameters:
  
  parent - parent class loader for the engine
  
  Throws:
  
  NullPointerException - if the parent class loader is null
  
  Since:
  
  1.0.3
- Grengine
  
  public Grengine(ClassLoader parent, CompilerConfiguration config)
  
  constructor for a Grengine without any (static) code layers, but with a top code cache.
  Constructed from a builder with default settings.
  
  Parameters:
  
  parent - parent class loader for the engine
  
  config - compiler configuration to use for compiling all sources
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0.3
- Grengine
  
  public Grengine(File dir)
  
  constructor for a Grengine based on scripts in a given script directory, without subdirectories, and with a top code cache.
  Script extensions are the single extension "groovy".
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  dir - script directory
  
  Throws:
  
  NullPointerException - if the directory is null
  
  Since:
  
  1.0
- Grengine
  
  public Grengine(ClassLoader parent, File dir)
  
  constructor for a Grengine based on scripts in a given script directory, without subdirectories, and with a top code cache.
  Script extensions are the single extension "groovy".
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  parent - parent class loader for the engine
  
  dir - script directory
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0.3
- Grengine
  
  public Grengine(CompilerConfiguration config, File dir)
  
  constructor for a Grengine based on scripts in a given script directory, without subdirectories, and with a top code cache.
  Script extensions are taken from the given compiler configuration, which defaults to the single extension "groovy".
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  config - compiler configuration to use for compiling all sources
  
  dir - script directory
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0
- Grengine
  
  public Grengine(ClassLoader parent, CompilerConfiguration config, File dir)
  
  constructor for a Grengine based on scripts in a given script directory, without subdirectories, and with a top code cache.
  Script extensions are taken from the given compiler configuration, which defaults to the single extension "groovy".
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  parent - parent class loader for the engine
  
  config - compiler configuration to use for compiling all sources
  
  dir - script directory
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0.3
- Grengine
  
  public Grengine(File dir, DirMode dirMode)
  
  constructor for a Grengine based on scripts in a given script directory, optionally including subdirectories (recursively), and with a top code cache.
  Script extensions are the single extension "groovy".
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  dir - script directory
  
  dirMode - dir mode
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0
- Grengine
  
  public Grengine(ClassLoader parent, File dir, DirMode dirMode)
  
  constructor for a Grengine based on scripts in a given script directory, optionally including subdirectories (recursively), and with a top code cache.
  Script extensions are the single extension "groovy".
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  parent - parent class loader for the engine
  
  dir - script directory
  
  dirMode - dir mode
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0.3
- Grengine
  
  public Grengine(CompilerConfiguration config, File dir, DirMode dirMode)
  
  constructor for a Grengine based on scripts in a given script directory, optionally including subdirectories (recursively), and with a top code cache.
  Script extensions are taken from the given compiler configuration, which defaults to the single extension "groovy".
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  config - compiler configuration to use for compiling all sources
  
  dir - script directory
  
  dirMode - dir mode
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0
- Grengine
  
  public Grengine(ClassLoader parent, CompilerConfiguration config, File dir, DirMode dirMode)
  
  constructor for a Grengine based on scripts in a given script directory, optionally including subdirectories (recursively), and with a top code cache.
  Script extensions are taken from the given compiler configuration, which defaults to the single extension "groovy".
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  parent - parent class loader for the engine
  
  config - compiler configuration to use for compiling all sources
  
  dir - script directory
  
  dirMode - dir mode
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0.3
- Grengine
  
  public Grengine(Collection<URL> urls)
  
  constructor for a Grengine based on a collection of URL-based scripts, with a top code cache, and with tracking URLs based on content.
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Uses a DefaultSourceFactory with tracking URL content set to true. Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  urls - collection of URL-based scripts
  
  Throws:
  
  NullPointerException - if the URL collection is null
  
  Since:
  
  1.0
- Grengine
  
  public Grengine(ClassLoader parent, Collection<URL> urls)
  
  constructor for a Grengine based on a collection of URL-based scripts, with a top code cache, and with tracking URLs based on content.
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Uses a DefaultSourceFactory with tracking URL content set to true. Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  parent - parent class loader for the engine
  
  urls - collection of URL-based scripts
  
  Throws:
  
  NullPointerException - if the URL collection is null
  
  Since:
  
  1.0.3
- Grengine
  
  public Grengine(CompilerConfiguration config, Collection<URL> urls)
  
  constructor for a Grengine based on a collection of URL-based scripts, with a top code cache, and with tracking URLs based on content.
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Uses a DefaultSourceFactory with tracking URL content set to true. Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  config - compiler configuration to use for compiling all sources
  
  urls - collection of URL-based scripts
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0
- Grengine
  
  public Grengine(ClassLoader parent, CompilerConfiguration config, Collection<URL> urls)
  
  constructor for a Grengine based on a collection of URL-based scripts, with a top code cache, and with tracking URLs based on content.
  Load modes are "current first" for the script directory code layer and "parent first" for the top code cache.
  Uses a DefaultSourceFactory with tracking URL content set to true. Constructed from builders with otherwise default settings.
  Call getLastUpdateException() after constructing if you need to make sure all sources can be compiled without errors.
  
  Parameters:
  
  parent - parent class loader for the engine
  
  config - compiler configuration to use for compiling all sources
  
  urls - collection of URL-based scripts
  
  Throws:
  
  NullPointerException - if any argument is null
  
  Since:
  
  1.0.3
Method Details
- getBuilder
  
  public Grengine.Builder getBuilder()
  
  gets the builder.
  
  Returns:
  
  builder
  
  Since:
  
  1.0
- getLastUpdateException
  
  public GrengineException getLastUpdateException()
  
  updates code layers if necessary and gets the exception that occurred at the last update.
  
  Returns:
  
  last exception or null if none
  
  Since:
  
  1.0
- updateEngineIfSourcesLayersModified
  
  protected void updateEngineIfSourcesLayersModified()
  
  updates the engine if sources layers have been modified.
  
  Since:
  
  1.0
- loadMainClass
  
  public Class<?> loadMainClass(Loader loader, Source source)
  
  Description copied from class: BaseGrengine
  
  loads the main class of the given source from the given loader.
  Note that if a class with the main class name is available for loading, but was not compiled as part of a set of Source that included the given source, that class will not count for loading.
  Specified by:
  
  loadMainClass in class BaseGrengine
  
  Parameters:
  
  loader - loader
  
  source - source
  
  Returns:
  
  main class
  
  See Also:
  
  Engine.loadMainClass(Loader loader, Source source)
- loadMainClass
  
  public Class<?> loadMainClass(Source source)
  
  Description copied from class: BaseGrengine
  
  loads the main class of the given source from the default loader.
  Note that if a class with the main class name is available for loading, but was not compiled as part of a set of Source that included the given source, that class will not count for loading.
  Specified by:
  
  loadMainClass in class BaseGrengine
  
  Parameters:
  
  source - source
  
  Returns:
  
  main class
  
  See Also:
  
  Engine.loadMainClass(Loader loader, Source source)
- loadClass
  
  public Class<?> loadClass(Loader loader, Source source, String name)
  
  Description copied from class: BaseGrengine
  
  loads a class with the given name and from the given source from the given loader.
  Note that if a class with the given class name is available for loading, but was not compiled as part of a set of Source that included the given source, that class will not count for loading.
  Specified by:
  
  loadClass in class BaseGrengine
  
  Parameters:
  
  loader - loader
  
  source - source
  
  name - class name
  
  Returns:
  
  class
  
  See Also:
  
  Engine.loadClass(Loader loader, Source source, String name)
- loadClass
  
  public Class<?> loadClass(Source source, String name)
  
  Description copied from class: BaseGrengine
  
  loads a class with the given name and from the given source from the default loader.
  Note that if a class with the given class name is available for loading, but was not compiled as part of a set of Source that included the given source, that class will not count for loading.
  Specified by:
  
  loadClass in class BaseGrengine
  
  Parameters:
  
  source - source
  
  name - class name
  
  Returns:
  
  class
  
  See Also:
  
  Engine.loadClass(Loader loader, Source source, String name)
- loadClass
  
  public Class<?> loadClass(Loader loader, String name)
  
  Description copied from class: BaseGrengine
  
  loads a class by name from the given loader.
  Note that a top code cache is not searched in this case, because each set of source has its own top loader.
  Specified by:
  
  loadClass in class BaseGrengine
  
  Parameters:
  
  loader - loader
  
  name - class name
  
  Returns:
  
  class
  
  See Also:
  
  Engine.loadClass(Loader loader, String name)
- loadClass
  
  public Class<?> loadClass(String name)
  
  Description copied from class: BaseGrengine
  
  loads a class by name from the default loader.
  Note that a top code cache is not searched in this case, because each set of source has its own top loader.
  Specified by:
  
  loadClass in class BaseGrengine
  
  Parameters:
  
  name - class name
  
  Returns:
  
  class
  
  See Also:
  
  Engine.loadClass(Loader loader, String name)

Class Grengine

Nested Class Summary

Field Summary

Fields inherited from class ch.grengine.BaseGrengine

Constructor Summary

Method Summary

Methods inherited from class ch.grengine.BaseGrengine

Methods inherited from class java.lang.Object

Field Details

LATENCY_MS_INFINITE_STATIC

Constructor Details

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Grengine

Method Details

getBuilder

getLastUpdateException

updateEngineIfSourcesLayersModified

loadMainClass

loadMainClass

loadClass

loadClass

loadClass

loadClass