Grape Dependency Management

The shorthand form takes group:module:version. Put the annotation on an import, which is the form the documentation recommends, because an annotated import is evaluated before the imported class is looked up:

The first run downloads commons-text and its dependency commons-lang3; later runs find them in the cache and start without touching the network. The long form names the parts as attributes, which is useful when a value comes with a classifier or other options:

Source: Groovy documentation: Grape, add a dependency

The version is a literal such as 1.13.0 or a range in Ivy notation: [1.16,1.18) is "1.16 up to but excluding 1.18", [2.2.1,) is "2.2.1 or any greater version". A range resolved against a cache that already holds a matching version picks from what is available, so a run can differ between machines. Pin an exact version in anything that must repeat:

With the default engine the artifact was found as version 1.17.1, as grape list showed afterwards. The Ivy engine looks in three places, in this order, as its verbose log lists them: cachedGrapes (the Grape cache), localm2 (the local Maven repository, ~/.m2/repository) and ibiblio (Maven Central). The local Maven repository is a convenient source, but it also means a half-populated Maven cache can fool a resolution; see Hardening.

The cache lives under the Grape root, ~/.groovy by default, in a directory named after the engine: grapes for the Ivy engine and grapesM2 for the Maven one. The grape.root system property moves the root, which is how the runs on this page were isolated. With -Dgrape.root=<scratch>/grape-root the first script above left this layout (shortened):

Sharing one cache between a team’s machines, putting it on a CI cache volume, or deleting it to force a fresh download are all done through this directory. Deleting one module directory is enough to make Grape fetch that module again.

Source: Groovy documentation: Grape, detail

Maven Central is searched by default. @GrabResolver adds another repository, such as a company’s Nexus or Artifactory server or a file system directory. This example uses a tiny repository created for the page: a one-class jar and its POM in Maven layout under a local directory (the directory was in the scratch area; it appears below as /path/to/local-repo):

The jar and the POM were found at com/example/greenhouse-sensors/1.0.0/ below the root, the path a Maven repository uses. The Ivy engine, while setting a custom resolver up, wrote a problems summary with the line unknown resolver greenhouse-local to standard error on the first run, and then resolved the artifact and ran the script anyway; the same script with the Maven engine printed nothing of the kind. Treat it as noise when the script ends with the expected result, and as a real problem when the resolution reports that the module could not be found. A resolver whose name collides with a built-in one (central, for instance) is a real error, as the page on the AST transformations shows. Pick a distinct name.

The root should be an https:// URL. A plain http:// root is reported by the hardening checks described below because anything fetched over it can be read or changed on the way.

Source: Groovy documentation: Grape, specify additional repositories

A Maven classifier picks a variant of the same coordinates, such as a tests or sources jar. Name it as the fourth element of the shorthand or in the classifier attribute:

A dependency brings its own dependencies along unless transitive = false says otherwise. To see exactly which jars an artifact brings, ask the facade, which returns the jar locations:

@GrabExclude is the finer tool: it drops one transitive module and keeps the rest, which is the way to stay on a version of a library that the application already provides, or to remove a module that would clash. The attributes are group and module, or @GrabExclude('xml-apis:xml-apis') for the shorthand. The effect on the classpath is the effect of removing the jar, so code that needs the class fails with NoClassDefFoundError, as the page linked in the previous section demonstrates.

Source: Groovy documentation: Grape, Maven classifiers

@GrabConfig configures the grab. Its most famous option is systemClassLoader = true, which attaches the jars to the system class loader instead of the loader of the script. It exists because of how JDBC finds drivers: DriverManager only offers a driver to code that can see the driver’s class loader. A driver grabbed into the script’s class loader is invisible to groovy.sql.Sql, which is loaded by the Groovy runtime. With H2 (an embedded database, see Databases with Groovy SQL):

The same script without the @GrabConfig line fails, in this setup, with:

Calling DriverManager.getConnection directly from the script did work without it, because the script’s own loader could see the driver. The other options of @GrabConfig:

Source: Groovy documentation: Grape, JDBC drivers

The annotation is the compile-time front end of a facade that can also be called directly. Grape.grab takes a map with group, module, version and optionally classifier, conf (Ivy configuration or Maven scope), force, changing and transitive. There are synonyms for the keys (groupId, organisation, organization, org for the group; artifactId and artifact for the module; version, revision and rev), and giving two synonyms at once is a runtime error. Because the call happens at run time, the classes are not known to the compiler: reach them with Class.forName or loadClass, or split the script so that the code using them is evaluated later.

The jars go to a class loader that must be a RootLoader or a GroovyClassLoader, found in this order: the one passed as classLoader:, the loader of the object passed as refObject:, and the loader of the class that calls grab. A script run by the groovy command has one. In an application that embeds Groovy, create a GroovyClassLoader, pass it, and load the classes through it:

The second map argument and its options (validate, noExceptions) belong to the two-map form Grape.grab(args, dependency1, dependency2, ...); a call with a single map uses it as both. Embedding is the subject of Integrating Groovy into Java Applications.

Source: Groovy documentation: Grape, method call

In the shell there are no annotations on imports to rely on, since every input is evaluated on its own. The documentation suggests the method call; groovysh also has a /grab command that wraps it (see groovysh & groovyconsole). Both were run by piping the lines to groovysh -q -C false:

The groovyConsole has no such command; start it with a script that holds the @Grab annotation, or call Grape.grab in the first lines of the script window.

Source: Groovy documentation: Grape, using Grape from the Groovy shell

The grape executable in $GROOVY_HOME/bin inspects and manages the cache. Its commands in 6.0.0:

The global options are -q, -w, -i, -V and -d (log level 0 to 4), -D to define a system property, -r to add a resolver for an install, -h and -v. Since 6.0 install also accepts the coordinate shorthands of @Grab. The three forms below are equivalent; the third one is the Ivy notation group#module;version, and a classifier and an extension are written group:module:version:classifier@ext (this form is from the 6.0 release notes):

A session with a fresh cache (the cache path is shortened to <grape.root>):

grape install is the way to warm a cache in advance, for instance in the image build of a container that later runs scripts without network access. grape resolve turns a Grape dependency into a plain classpath for Java, Ant or a shell script. uninstall deletes the jar but the module still shows in list, with an empty version list; remove the module directory by hand when you want it to disappear. Without -q the Ivy engine prints its resolution messages at INFO level, which is noisy in scripts.

Source: Groovy documentation: Grape, command line tool

Groovy 6.0 ships two implementations of the Grape engine behind the same annotations and facade (incubating in 6.0):

When both engines are on the classpath, GrapeIvy wins. Select the other one with the groovy.grape.impl system property, on the command line or globally in JAVA_OPTS. A script that prints which engine served it, run twice against the same Grape root:

Source: Groovy 6.0 release notes: Grape: Dual Engine Support, Groovy 6.0 release notes: Selecting the engine

Afterwards the Grape root held both caches side by side: grapes from the first run and grapesM2 (with org/apache/commons/commons-text/1.13.0/commons-text-1.13.0.jar below it) from the second. The SLF4J lines come from Maven Resolver, which looks for a logging binding; they are harmless. Both engines honour grape.root. The local file repository script from the section on @GrabResolver also ran unchanged with the Maven engine.

A value of groovy.grape.impl that names a class that does not exist leaves no engine to resolve the annotation, and the script fails at compile time with unable to resolve class for the imports it was meant to supply. A custom engine is a class implementing groovy.grape.GrapeEngine, registered in META-INF/services/groovy.grape.GrapeEngine of a jar on the classpath and selected with the same property; if it is the only one on the classpath it is found without it.

Behind a proxy, pass the standard JVM properties, on the command line or for every run in JAVA_OPTS:

This was not run here (it needs a proxy); the host names are placeholders. For https repositories the matching https.proxyHost and https.proxyPort properties apply as for any JVM program. Credentials for a repository that needs them do not belong in the script or in an annotation; they belong in the build tool or in the environment, and a script that needs a private repository is better turned into a Gradle or Maven project.

To see what Grape is doing, the Ivy engine accepts -Dgroovy.grape.report.downloads=true, which prints one line for each resolve and download to standard error. Against an empty cache:

(The download here came from the local Maven repository, hence the short times.) Since 6.0 Groovy routes its diagnostics through the JDK’s platform logging, so the detailed output is controlled with a logging.properties file: Groovy reads ~/.groovy/logging.properties or the file named by -Djava.util.logging.config.file. A file that raises the Ivy engine’s logger to FINE:

printed, among many lines, the resolver chain and each step of the resolution:

The levels are INFO, FINE and FINEST for increasing detail, and the grape command’s -q, -w, -i, -V and -d flags adjust the Ivy level for one invocation. The Maven engine ignores groovy.grape.report.downloads; its switch is -Dgroovy.grape.debug=true, which prints lines such as:

Source: Groovy documentation: Grape, logging

Grape downloads code and puts it on the class path of a program that is about to run it. Whatever the repository serves, it executes with the rights of the script. Three habits matter more than any option: pin exact versions, use only repositories you control or trust, and prefer https://. Groovy 6.0 added several checks of its own:

The first two bullets were run. The coordinate check and the two policies against Grape.addResolver:

With the default warn policy the plaintext resolver was added after a log line from checkResolverRootProtocol, and the loopback one never triggered the check. The host is a reserved test name; the script never connected to it. Checksum and cache handling are described in the release notes and were not exercised here.

Finally, -Dgroovy.grape.enable=false switches @Grab off. A script that depends on one fails to compile, with the import it was meant to provide reported as unable to resolve class. That is the switch for an environment (a locked-down CI job or a server that compiles user scripts) where code must not fetch anything. Compile-time restrictions for scripts that come from outside are described on Compilation Customizers & Secure Scripting.

Source: Groovy 6.0 release notes: Grape hardening

The first edition of the reference book (Groovy 1.0, 2007) predates Grape altogether: Grape arrived in Groovy 1.6 (2009). A script of the book’s era placed jars on the command line with -cp, in $GROOVY_HOME/lib or in ~/.groovy/lib, and that still works but is the opposite of a self-contained script. What differs now: the @Grab annotation on an import, the shorthand coordinates and the grape command, the grape.root property to move the cache, and, new in 6.0, the split of the Ivy engine into its own module, the second engine based on Maven Resolver, platform logging, the shorthands of grape install and the hardening checks. Documentation written for 2.x or 3.x still describes the Ivy engine only, the groovy.grape.report.downloads property as the logging switch and ~/.groovy/grapeConfig.xml as the way to configure it; those remain true for GrapeIvy but not for the new engine. Examples that grab a http:// repository are also dated, since Maven Central itself is https only and the plaintext check now warns. The collected list of changes is on What’s New & Migrating from Older Versions.