ch.grengine.engine

Interface Engine

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

LayeredEngine

public interface Engine
extends Closeable

Engine interface.

Provides the base functionality for a Grengine, without all the convenience methods.

Since:

1.0

Author:

Alain Stalder, Made in Switzerland.

Method Summary

Modifier and Type	Method and Description
ClassLoader	asClassLoader(Loader loader) returns a class loader based on this engine and the given loader.
void	close() release metadata for all classed ever loaded using this engine.
Loader	getLoader() gets the default attached loader.
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<?>	loadMainClass(Loader loader, Source source) loads the main class of the given source from the given loader.
Loader	newAttachedLoader() creates and gets a new attached loader, backed by the same bytecode as all other shared loaders created by this engine and automatically updated if code layers are set.
Loader	newDetachedLoader() creates and gets a new detached loader, backed initially by the same bytecode as all attached loaders created by this engine, but not updated if code layers are set.
void	setCodeLayers(List<Code> codeLayers) sets (replaces) code layers of the engine, based on already compiled code layers.
void	setCodeLayersBySource(List<Sources> sourcesLayers) sets (replaces) code layers of the engine, based on sources to compile to code layers.

Method Detail

getLoader

Loader getLoader()

gets the default attached loader.

Returns:

default attached loader

Since:

1.0

newAttachedLoader

Loader newAttachedLoader()

creates and gets a new attached loader, backed by the same bytecode as all other shared loaders created by this engine and automatically updated if code layers are set.

Returns:

new attached loader

Since:

1.0

newDetachedLoader

Loader newDetachedLoader()

creates and gets a new detached loader, backed initially by the same bytecode as all attached loaders created by this engine, but not updated if code layers are set.

For example, a web application might create a detached loader for each new HTTP session: A new loader in order to separate static variables of scripts between sessions (security feature); a detached loader in order to keep code layers constant during the lifetime of the session (consistent behavior of Groovy script calls).

Returns:

new detached loader

Since:

1.0

loadMainClass

Class<?> loadMainClass(Loader loader,
                       Source source)

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.

Parameters:

loader - loader

source - source

Returns:

loaded class

Throws:

CompileException - if compilation was necessary to load the class and failed

LoadException - if loading failed, including if the class was not found

Since:

1.0

loadClass

Class<?> loadClass(Loader loader,
                   Source source,
                   String name)

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.

Parameters:

loader - loader

source - source

name - class name

Returns:

loaded class

Throws:

CompileException - if compilation was necessary to load the class and failed

LoadException - if loading failed, including if the class was not found

Since:

1.0

loadClass

Class<?> loadClass(Loader loader,
                   String name)

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.

Parameters:

loader - loader

name - class name

Returns:

loaded class

Throws:

LoadException - if loading failed, including if the class was not found

Since:

1.0

setCodeLayers

void setCodeLayers(List<Code> codeLayers)

sets (replaces) code layers of the engine, based on already compiled code layers.

Note that normally it is supported to do this "live", while the engine is used.

Parameters:

codeLayers - code layers

Throws:

ClassNameConflictException - optionally if the same class name occurs in different code layers or would already be available from a parent class loader

NullPointerException - if code layers are null

Since:

1.0

setCodeLayersBySource

void setCodeLayersBySource(List<Sources> sourcesLayers)

sets (replaces) code layers of the engine, based on sources to compile to code layers.

Note that normally it is supported to do this "live", while the engine is used.

Parameters:

sourcesLayers - sources layers

Throws:

CompileException - if compilation failed

ClassNameConflictException - optionally if the same class name resulted from compiling different sources layers or would already be available from a parent class loader

NullPointerException - if sources layers are null

Since:

1.0

close

void close()

release metadata for all classed ever loaded using this engine.

Allows to remove metadata associated by Groovy (or Java) with a class, which is often necessary to get on-the-fly garbage collection.

Generally call only when really done using this engine and all loaded classes; subsequently trying to use this engine or its classes results generally in undefined behavior.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Since:

1.1

asClassLoader

ClassLoader asClassLoader(Loader loader)

returns a class loader based on this engine and the given loader.

Note that the returned class loader typically does not load classes itself; it just wraps the engine and its loader.

Parameters:

loader - loader

Returns:

class loader

Throws:

NullPointerException - if the loader is null

IllegalArgumentException - if the loader does not match the engine

Since:

1.3