Dependency management with Grape

Grape is a JAR dependency manager embedded into Groovy. Grape lets you quickly add maven repository dependencies to your classpath, making scripting even easier. The simplest use is as simple as adding an annotation to your script:

@Grab also supports a shorthand notation:

Note that we are using an annotated import here, which is the recommended way. You can also search for dependencies on mvnrepository.com and it will provide you the @Grab annotation form of the pom.xml entry.

Not all dependencies are in maven central. You can add new ones like this:

Some maven dependencies need classifiers in order to be able to resolve. You can fix that like this:

Sometimes you will want to exclude transitive dependencies as you might be already using a slightly different but compatible version of some artifact. You can do this as follows:

Because of the way JDBC drivers are loaded, you’ll need to configure Grape to attach JDBC driver dependencies to the system class loader. I.e:

From groovysh use the method call variant:

If you are behind a firewall and/or need to use Groovy/Grape through a proxy server, you can specify those settings on the command like via the http.proxyHost and http.proxyPort system properties:

Or you can make this system-wide by adding these properties to your JAVA_OPTS environment variable:

The Grape facade (groovy.grape.Grape) uses JDK Platform Logging and can be configured through ~/.groovy/logging.properties (see the groovy command for details).

Logging of the underlying engine depends on which Grape implementation is active.

Groovy ships with two built-in Grape engine implementations. Both support the same core @Grab, @GrabResolver, and @GrabExclude annotations and method calls. They differ in their underlying resolution mechanism, cache layout, and some advanced configuration options.

One or more groovy.lang.Grab annotations can be added at any place that annotations are accepted to tell the compiler that this code relies on the specific library. This will have the effect of adding the library to the classloader of the groovy compiler. This annotation is detected and evaluated before any other resolution of classes in the script, so imported classes can be properly resolved by a @Grab annotation.

Supported annotation targets include imports (recommended), classes, methods, constructors, fields, parameters, and local variables.

Here is an example placing @Grab on a class:

Here is an example placing @Grab on a local variable:

An appropriate grab(…​) call will be added to the static initializer of the class of the containing class (or script class in the case of an annotated script element).

In early versions of Groovy, if you wanted to use a Grab annotation multiple times on the same node you had to use the @Grapes annotation, e.g.:

Otherwise you’d encounter the following error:

But in recent versions, @Grapes is purely optional.

Technical notes:

Typically a call to grab will occur early in the script or in class initialization. This is to ensure that the libraries are made available to the ClassLoader before the groovy code relies on the code. A couple of typical calls may appear as follows:

Grape added a command line executable `grape' that allows for the inspection and management of the local grape cache.

This installs the specified groovy module or maven artifact. If a version is specified that specific version will be installed, otherwise the most recent version will be used (as if `*' we passed in).

Lists locally installed modules (with their full maven name in the case of groovy modules) and versions.

This returns the file locations of the jars representing the artifacts for the specified module(s) and the respective transitive dependencies. You may optionally pass in -ant, -dos, or -shell to get the dependencies expressed in a format applicable for an ant script, windows batch file, or unix shell script respectively. -ivy may be passed to see the dependencies expressed in an ivy like format.

This uninstalls a particular grape: it non-transitively removes the respective jar file from the grape cache.

Using Apache Commons Collections:

Using TagSoup:

Using Google Collections:

Launching a Jetty server to serve Groovy templates:

Grape will download Jetty and its dependencies on first launch of this script, and cache them. We create a new Jetty Server on port 8080, then expose Groovy’s TemplateServlet at the root of the context — Groovy comes with its own powerful template engine mechanism. We start the server and let it run for a certain duration. Each time someone will hit http://localhost:8080/somepage.gsp, it will display the somepage.gsp template to the user — those template pages should be situated in the same directory as this server script.