ch.grengine

Class Grengine

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, new URL("http://acme.org/myScript.groovy", 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 and 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, eliminating also a Groovy issue related to Grape (GROOVY-7407).

Field Summary

Fields

Modifier and Type	Field and Description
static 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 and Description
	Grengine() constructor for a Grengine without any (static) code layers, but 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, 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, org.codehaus.groovy.control.CompilerConfiguration config) constructor for a Grengine without any (static) code layers, but with a top code cache.
	Grengine(ClassLoader parent, org.codehaus.groovy.control.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(ClassLoader parent, org.codehaus.groovy.control.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, org.codehaus.groovy.control.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, 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(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(org.codehaus.groovy.control.CompilerConfiguration config) constructor for a Grengine without any (static) code layers, but with a top code cache.
	Grengine(org.codehaus.groovy.control.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(org.codehaus.groovy.control.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(org.codehaus.groovy.control.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(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.
protected	Grengine(Grengine.Builder builder) constructor from builder.

Method Summary

Modifier and Type	Method and 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 Detail

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 Detail

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(org.codehaus.groovy.control.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,
                org.codehaus.groovy.control.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(org.codehaus.groovy.control.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,
                org.codehaus.groovy.control.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(org.codehaus.groovy.control.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,
                org.codehaus.groovy.control.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(org.codehaus.groovy.control.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,
                org.codehaus.groovy.control.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 Detail

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)