Groovy Enhancement Proposal













Paul King



Last modification:


Abstract: Modularization

Parts of GEP-9 have been incorporated into Groovy 2.0. Please see the Groovy 2.0 documentation for further details, e.g.: Creating an extension module


This GEP introduces the goals and proposed details behind a modularization effort that will:

This activity builds upon the work discussed previously: Groovy 2.0 modularization and the somewhat older profiles discussion Packaging and Modularity.

This document is part work in progress and part proposals and ideas. The final details may change from what is discussed here. User feedback (preferably on the user mailing list) is greatly appreciated.

Out of scope

While we should keep a watching brief on other modularization efforts, at this stage we are anticipating structural changes to the Groovy classes which are orthogonal to eventually using something like OSGi or Java 8's Jigsaw modularization.

Jar groupings

At the moment, Groovy provides two main jar artifacts:

After modularization, the main Groovy codebase will be packaged into additional jar artifacts:

Recommendations/suggestions for jar groupings are welcome. See some more details in the accompanying discussion: Groovy 2.0 modularization.

One of the goals of this bundling effort is to facilitate Groovy's evolution as a language by enabling:

Configuring a Groovy installation

Groovy bootstraps its configuration using a file in the conf/groovy-starter.conf file. It has entries like this:

# load required libraries
load !{groovy.home}/lib/*.jar

with required jars being in a lib directory which is part of a Groovy install.

The groovy install will now likely have a "modules" (or components or repository) directory.
The groovy-starter.conf file will have additional entries such as:

# load SQL component
grab org.codehaus.groovy groovy-sql 1.9.0
# load XML component
grab org.codehaus.groovy groovy-xml 1.9.0

Grapes are loaded via Ivy and configured from a settings file. This file might have an additional entry:

<ibiblio name="modules" root="file:${groovy.home}/modules/" m2compatible="true"/>

The Ivy library (or perhaps the wharf or aether libraries) will likely become a required jar - though it may be
that only a very limited form of grab is supported in which case no additional library might be necessary.

Runtime hooks/registration

When downloading a grape, the classes from its jar are added (currently appended) to the classpath. In addition, we are planning on supporting additional integration points:

potential hook



allow the module to define additional category methods


allow the module to define additional static category methods


allow the module to define additional expandometaclass methods


allow the module to define additional metaclasses similar to the current magic package mechanism**


allow the module to define additional category methods which have been serialized


allow the module to define additional normal, star, static imports, aliases


allow the module to define supported file extensions


allow the module to define AST transforms


provide a way to register builder metadata


should there by a way to 'publish' new commandline level startup scripts e.g. java2groovy


provide a way to register a runner class, e.g. EasyB - there might also be a need to detect runner types


provide a way to register special compiler flags, e.g. '--indy'


provide a way to inject special AST customizations

**This needs to mesh in with the existing magic package mechanism for defining custom metaclasses.

This is also where we could specify additional requirements, e.g. require 'invoke dynamic' - but see later also. Could we declaratively specify our security policy requirements. Or can we disable specific aspects of functionality, e.g. disable some standard global AST transform because we want to provide a better one. (There are obviously security implications for this!)

Another question is whether all these features will be available also via an API. Would such an API allow modules to be "unregistered"?

Groovydoc/source pointers

Some modularization systems support the "installation" of documentation (and/or sources) along with the module.
Should a module have a pointer to (or be bundled with) its GroovyDoc and/or source.

In the Java ecosystem, many libraries are published with their javadoc/sources according to common conventions or have javadoc available online. Do we rely on these established conventions or provide additional support? For users without access to sophisticated IDEs it could be convenient to have all the documentation available in "merged" form in one place.

Build Impacts

Mostly discussed here: Groovy 2.0 modularization

Should each "submodule" be able to be built on its own? Will it have its own javadoc, own coding style rules, own coverage metrics etc.

Module robustness

Should we provide a standard hook/mechanism to try to combat the following scenarios:

Runtime Introspection

In Groovy you can currently determine the Groovy version using:

println GroovySystem.version

which returns a String.

In GROOVY-2422 it talks about the desire for additional version checks.

It also talks about listing capabilities. This could be "is invokeDynamic" available or could really just be about available loaded modules. In general, we would expect our dependencies to be specified as part of our pom and loaded for us automatically but it can sometimes be useful to do special things.

In general, should we be able to find out the list of loaded modules and versions? Or ask about which module/version a particular class belongs to?

Assisting IDE support

We may define a standard place or convention, e.g. META-INF/services/groovy/dsld or META-INF/services/groovy/gdsl where IDEs can find DSL descriptors relevant for that module.


Should modules themselves have a standard way to do logging? Is that j.u.l.Logger? Perhaps bridged with slf4j?

JIRA issues

Useful links