Grengine User Manual

With Grengine, a script can essentially be run by script text, script file or script URL:

A binding can optionally be indicated by passing a Binding object or a Map<String,Object>.

In Groovy, passing a map is easier than in Java:

For more convenient use in Java, Grengine provides an easier way to construct a Binding by indicating alternating String and Object parameters in pairs:

What happens "behind the scenes" when you run a Groovy script?

A simple Groovy script like "return 2" is implicitly roughly equivalent to the following Java source:

First this source is compiled. (Unlike some other script languages, Groovy is always compiled to bytecode for a Java VM; it is never interpreted directly.) In this simple case, with no inner classes, the result is a single byte array (byte[]) associated with the class name "SomeGeneratedClassName".

The next step is loading the class, for that you need a java.lang.ClassLoader. From the outside, the class is loaded by calling

Inside the class loader, at the first request to load the class by name, the class is "defined". This is the moment when the bytecode is actually loaded into the VM as an instance of java.lang.Class:

It is important to be aware that a class can only be defined once per class loader instance. There is no way to "unload" a class in a Java VM or to replace the bytecode. If a class loader and its classes are not used (referenced) any more, it is eventually garbage collected by the VM. If you need a new version of the same class, at least implicitly a new class loader instance is always required.

Once a class is loaded, an instance can be created and the script can be run, optionally with a specific binding:

With Grengine (as with the Groovy JDK) it is possible to separate class loading from object creation and from running. Grengine offers a lot of convenience here, again:

The interface Source abstracts a Groovy script source. It has essentially the following two methods:

For sources from script text, file and URL, there are interfaces that extend Source, with the following (pretty obvious) additional methods:

For the default implementations, the source ID is as follows:

Last modified is as follows:

Grengine provides convenience methods for getting Source instances, and these sources can also be directly used to load classes, create Script instances and to run scripts:

Here’s a sample output of the above:

In order to create sources, Grengine uses a SourceFactory, by default set to new DefaultSourceFactory(), which provides instances of the default source implementations. Alternatively, the DefaultSourceFactory can be constructed with different settings: [1]

The options of the DefaultSourceFactory.Builder in detail:

For further optimizations, you could override some methods in DefaultSourceFactory or provide your own implementation of the SourceFactory interface.

Often you may have some Groovy scripts in a directory which you may want to run directly or use as a library or API. To make things concrete, suppose there are the following two files in the current working directory:

Now create and use a Grengine based on these sources:

By default, changes in the sources in the directory are detected with a latency of 5 seconds. This includes modifications of file content, as well as creating and deleting files in the directory. If changes are detected, all sources in the directory are recompiled, with dependencies between the scripts fully considered by the compiler.

Example (in Groovy):

By default, only files with extension .groovy in the script directory are considered and subdirectories are ignored. Optionally, you can change both, as follows:

There are again quite a few differences between what Grengine does and what different classes in the Groovy JDK do in similar situations. Let’s assume again that there are the two files "Util.groovy" and "Test.java" in the current working directory. With a GroovyShell from the Groovy JDK:

"xx:yy" is printed, but if you try the same with a default Grengine (one that is not directory-based):

execution fails at the last line with a CompileException stating that the class Util could not be resolved.

Why?

Grengine strictly separates between scripts in its "container", i.e. scripts that are defined for the Grengine when it is created, and scripts that are given to be run (or created or loaded) by the Grengine at runtime.

The latter scripts run each in their own individual class loader. They all share the same parent class loader, which includes all of the compiled "container" script classes, but they do not see each other’s classes. These individual class loaders are managed by what is called a TopCodeCache in Grengine.

This more structured approach has some advantages.

The approach in the Groovy JDK’s GroovyShell is well suited for interactive use, where you may usually want to be able to add code script by script. Beyond that, depending on the use case, this behavior may be more problematic:

The correct handling of dependencies between scripts is also a (minor) issue if you add a script directory to a GroovyClassLoader, but that approach already covers more cases in practice. For example

prints out "xx:yy". The GroovyClassLoader tries to load classes by name, i.e. because Test.groovy references a class Util, the loader searches for a file Util.groovy in its classpath and, if found, compiles it and loads the class. This works only if the file name matches the class name. For example, in Groovy a file Extras.groovy might contain several non-inner classes, including Util (which is not possible in Java) - in that case the loader would not find the class Util (unless Test.groovy or another of its dependencies would first refer to a class Extras and there was a class Extras in Extras.groovy).

If you need 100% correct handling of dependencies using the Groovy JDK, you use a GroovyScriptEngine, but then you are limited to running only the scripts that are defined for the engine.

Grengine allows to do both, and more, as will be shown shortly.

For the moment note that you can simply use Grengine as the parent class loader of a GroovyShell or GroovyClassLoader etc.:

Or you can have it the other way round, i.e. use a GroovyClassLoader as the parent class loader of Grengine:

Since with Grengine you can add more controlled sets of Groovy sources "between" the top Grengine API and the GroovyClassLoader you can often have both the flexibility of the Groovy JDK and the control and additional features of Grengine, depending on what you need.

In general, a Grengine’s "container" scripts can consist of any number of layers of sources:

These sources are compiled layer by layer and each layers implicitly gets its own class loader instance. The lowest layer can only see its scripts (and all classes in the parent class loader). The next layer can see its scripts and everything below, and so on. Each class loader in the top code cache can see all of that and its own script.

Now, it can happen — by accident or by design — that a class with the same name appears more than once in different class loaders in this layered structure.

Which class should be loaded?

Traditionally, in Java it was recommended to load from the lowest possible class loader, i.e. "parent-first", also in order to economize resources. Nowadays the opposite, let me call it "current-first", is not uncommon. For example, some Java web application containers prefer to load classes from the webapp first before loading classes from the container. In general, "parent-first" is maybe more suited in "static" setups and "current-first" more in "dynamic" setups, like maybe also often with Groovy scripts.

In Grengine, the default for sources layers is "current-first", but for the top code layer it is "parent-first", in order to give the precompiled layers (with their full dependency awareness) precedence over a dynamically compiled version.

In other words, for a directory-based Grengine:

"Test.groovy" is run from the compiled code in the only sources layer and no extra copy will be made in the top code cache. "Test2.groovy", in turn, is compiled and made part of the top code cache. In terms of latency, this means, in this case, that updates to "Test.groovy" will have a latency of 5 seconds, but for "Test2.groovy", it will only be the latency of File.lastModified().

When you create a Grengine based on sources layers and compilation fails, you get an exception immediately. Later on, if sources have changed and no longer compile without errors, you get no exception when using Grengine, instead the last state of Grengine where compilation worked remains in use.

If you want to know if compilation of sources layers failed, you have two options. Either you call:

or you register a callback when creating the engine. For that you have to implement the interface UpdateExceptionNotifier:

and register it when creating the Grengine:

Note that there are no additional threads in a Grengine. The Grengine only checks for updated sources when you call any of its methods that require it to do so, like load/create/run.

In addition to compilation errors, you can optionally also prohibit duplicate classes with the same name, within the sources layers or between the sources layers and the parent class loader:

If set like this, class name conflicts lead to a ClassNameConflictException at compile time, which is a subclass of GrengineException

Grengine defines its own GrengineException. Nothing special, except maybe that it also declares a method that allows to obtain the date and time the exception had been thrown:

The following exceptions are subclasses of GrengineException:

Grengine provides a unique feature that is difficult to achieve with the Groovy JDK, except in simple cases: The same compiled bytecode, including all compiled sources layers of a Grengine and the top code cache can be shared in multiple, completely isolated "sessions".

Suppose a web application allows its administrator to configure a login with some Groovy scripts and the administrator, not much of a programmer, more a scripter, writes and configures a simple static utility class like this one:

Now, suppose there is a shared GroovyShell for all user sessions in the web application and the directory that contains "LoginUtil.groovy" has been added to the GroovyClassLoader of the GroovyShell. Finally, during each login, configured scripts like these are run:

Now, if several users log in at the same time, it can happen that username and password set for one user are overwritten by the ones for another user before Util.login() is called for the first user, so that in the end the first user has successfully logged in as the second user!

With the Groovy JDK, you could use separate instances of GroovyShell for each session, which would mean that all scripts would have to be compiled for each session. Or you could have a master GroovyClassLoader that has a target directory set in its CompilerConfiguration and then add the target directory to the classpath of a slave GroovyClassLoader instance per session.

With Grengine, you can use separate class loaders based on the same compiled byte code with a single Grengine instance. You can choose between "attached" loaders that are automatically updated when the Grengine’s sources layers change and all share a top code cache, or you can have "detached" loaders that remain constant during the session, i.e. compiled sources layers remain constant during the lifetime of the loader and have a top code cache only shared with loaders that have the same compiled sources layers.

All variations of load/create/run can optionally have a loader as its first parameter. If not indicated, the default loader is used, an attached loader that can be obtained with gren.getLoader().

Note that the Loader class is an opaque wrapper around an actual class loader.

Although loading classes from bytecode obtained from compiling Groovy scripts is a lot less expensive than compiling them (plus afterwards also loading the resulting bytecode), it is still somewhat more expensive than one might naively expect and there are a few things to be aware of when operating that way.

In the following, I will simply call classes compiled by the Groovy compiler from Groovy scripts/sources Groovy classes and classes compiled by the Java compiler from Java sources Java classes.

In a setup in which you don’t know when a loaded class will not be needed any more, and you want or need to load many Groovy classes repeatedly, first set a limit on PermGen/Metaspace, then verify that classes can be garbage collected once the limit is reached and that throughput is sufficient for your needs (despite the relatively slow class loading performance of Groovy (and Java) classes in the Java VM). And don’t forget to repeat this at least when you upgrade Groovy to a new version, but probably also when you upgrade Java.

In a setup in which you know exactly when you won’t need a Grengine or a Loader any more (including all the classes it ever loaded), you can explicitly make it available by calling its close() method.

Example 1:

Example 2:

This eliminates all the OutOfMemoryError issues described above. With Oracle Java 8 (and apparently with Oracle Java 6 and 7 on Windows) this leads generally to "on-the-fly" garbage collection, i.e. classes and their loaders are generally already collected before any limit on PermGen/Metaspace or Heap is reached. On VMs in which this is not the case, garbage collection when the limit is reached causes no noticeable delay, as opposed to when not closing, where the delay can easily be several seconds in which the VM does not respond to anything at all…​

Finally, note that you can even provide a custom cleanup function, just implement the ClassReleaser interface and set it in the Engine.

The ability to get dependencies from a Maven repository (or similar), at runtime, including transitive dependencies, which Grape offers, is a pretty much unique and cool feature that almost only Groovy offers so easily:

With Grengine this does not work if you just create e.g. a Grengine instance with new Grengine(), because Grape only works if there is a GroovyClassLoader (or a RootLoader) somewhere up in the class loader parent hierarchy. (The workaround @GrabConfig(systemClassLoader=true) before a grab does not always help, most prominently it fails in a webapp container like Tomcat.) In addition, in the case of Grengine, that GroovyClassLoader would not be the one that was used to compile the sources, which can lead to race conditions when loading classes from bytecode, because the Grape dependencies are added to the classpath in a static initializer, which may or may not run before classes from those dependencies are attempted to be loaded by the Java VM. (This is a general issue that affects loading of any classes compiled from sources that grab dependencies with Grape, see GROOVY-8108.)

Moreover, there is an open bug in Groovy Grape, GROOVY-7407, which is hard to fix in full generality. Namely, grabs are only thread-safe if they all go through the same GroovyClassLoader. They are not if you use different GroovyClassLoader instances, and also not across different class loaders for the Grape classes or different Java VMs (GROOVY-8097).

Grengine provides easy support for alleviating GROOVY-7407 in practice, except across different Java VMs, and prevents GROOVY-8108 from affecting Grengine.

Optionally the GrapeEngine in the Grape.class, which is obtained with Grape.getInstance() — and so far is always an instance of a class called GrapeIvy (using Apache Ivy to resolve dependencies) — is wrapped with a Grengine-specific instance that locks all grabs on Grape.class or on a freely eligible lock object and passes on all calls to the original GrapeEngine instance. For example, if you wanted to safely use Grape across different webapps in a Tomcat, the webapps might lock on some rather unusual class in the Java JDK, instead of on Grape.class, which would typically be separately loaded classes if the Groovy JAR is part of each webapp and not installed at the Tomcat level. Also part of the wrapper is a mechanism where you can optionally pass the runtime GroovyClassLoader while compiling via a CompilationCustomizer, with the effect that grabs are made on both the runtime class loader and the compile time class loader, thus eliminating GROOVY-8108.

In practice, things are quite easy to use. For a Grengine that uses Grape and is based of sources in a given directory, instead of

you would do this:

The first call wraps the GrapeEngine in the Grape class, which has a "global" impact on all Groovy scripts and classes that grab dependencies, but this does no harm to others, in fact it has no effect except on them except that it eliminates the GROOVY-7407 issue within the scope of the loaded Grape.class. (With the exception of performance: If one grab takes a few seconds because it has to download a dependency from a remote repository, any other scripts that want to grab, too, must wait. On the other hand, if those scripts would not wait, their grabs might fail or even get Grape into a state in which grabbing would not work any more until exiting the Java VM.)

The above shortcut works with all convenience Grengine constructors, the ones from directories, a collection of URLs or without any sources layers. To deactivate wrapping again, simply call:

If you want to use a different lock, use:

In more sophisticated use cases where you define the elements of the Grengine in more detail, you can directly use the DefaultGroovyCompiler class. The methods enableGrapeSupport() and disableGrapeSupport() have exactly the same effect als the activate/deactivate methods mentioned above. The only thing you usually have to do in addition, is to modify the CompilerConfiguration with a call like this, where runtimeLoader would be the parent loader of the Engine you create:

The compiler configuration is then set in the CompilerFactory, which, in turn, is used for the Sources and the TopCodeCache of the Engine. Here is a real example in Groovy (from Jexler):

Note that there are only two things done specifically to support Grape here, the activation call and the call to adapt the compiler configuration which is then passed to the constructed CompilerFactory.

By the way, you might also want to use the activate/deactivate calls simply to eliminate the GROOVY-7407 issue when using only the Groovy JDK, but nothing from Grengine except for those calls.

The compiler interface is very simple:

The interface Code wraps bytecode plus associated class names, including the name of the main class per Source instance, plus some information about the Sources, namely last modified at compile time and the sources name.

The class Bytecode is just a simple bean that wraps a class name and its bytecode byte array.

There are two implementations of Code, one for an arbitrary number of Source instances in the Sources given at compilation, DefaultCode, and DefaultSingleSourceCode for a single Source instance. The latter is primarily useful in the context of the top code cache.

The default implementation of Compiler is DefaultGroovyCompiler. It does nothing special, during compilation a GroovyClassLoader is created and optionally it writes classes also to to a target directory, if indicated in the compiler configuration.

It is imaginable to implement Compiler for other languages, like Java or Scala. Difficulties would be to find out the main class name and which class names come from which source and methods like gren.run(…​) would maybe not make that much sense if you had to explicitly implement groovy.lang.Script in Java or Scala scripts, but on a lower level, you could still use a lot of the automatisms of Grengine regarding compilation and management of compiled code.

The interface CompilerFactory and its default implementation are straightforward.

Use the static utility methods in ClassNameConflictAnalyzer to check for class name conflicts between different instances of Code or relative to a parent class loader.

The abstract class SourceClassLoader extends ClassLoader essentially with the following methods for loading classes by Source and (main) class name:

When loading a class by source, first the matching source is searched by ID in the class loader hierarchy. If found there, the main class can be returned or any other class that resulted from compiling the same source. Classes not associated with that source or not with any source at all, are not found this way, only if loaded directly with loadClass(className).

The load mode is an enum with two values, PARENT_FIRST and CURRENT_FIRST.

The basic implementation of SourceClassLoader is BytecodeClassLoader. Constructor:

It can operate in both load modes; I recommend to take a look at the code.

It also contains two static utility methods that are used by other source class loaders, loadMainClassBySource(…​) and loadClassBySourceAndName(…​).

Based on BytecodeClassLoader is LayeredClassLoader, which contains several layers of BytecodeClassLoader, associated with layers of Sources resp. Code, plus optionally a TopCodeCache.

The LayeredClassLoader can be cloned to copies based on identical bytecode.

The interface Engine defines the essential functionality for a Grengine, without all the convenience methods for load/create/run and without automatic updates of sources layers. These layers can be updated by providing layers of Sources or layers of already compiled Code.

The so far only implementation LayeredEngine uses a LayeredClassLoader. Layers can be updated while the engine is used.

The abstract class BaseGrengine implements most of the matrix of convenience methods for Grengine, which extends BaseGrengine. In addition, Grengine provides the automatic updates of sources layers and the callback for update exceptions.

A Grengine can be constructed with a custom Engine and SourceFactory, plus the notifier for update exceptions.

Many classes override toString() in order to produce strings useful for logging. A few classes, including all implementations of Source, override equals() and hashCode(), so that they can be used as map keys or in sets.

Many classes have an inner Builder class for flexible creation of instances, as well as to make it easier to add features in the future with a consistent interface.