Grape (The Groovy Adaptable Packaging Engine or Groovy Advanced Packaging Engine) is the infrastructure enabling the grab() calls in Groovy, a set of classes leveraging Ivy to allow for a repository driven module system for Groovy. This allows a developer to write a script with an essentially arbitrary library requirement, and ship just the script. Grape will, at runtime, download as needed and link the named libraries and all dependencies forming a transitive closure when the script is run from existing repositories such as Ibiblio, Codehaus, and java.net.

Basics

Grape follows the Ivy conventions for module version identificaiton, with naming change.

group - Which module group the module comes from. Translates directly to a Maven groupId or an Ivy Organization. Any group matching /groovy[x][\..*]^/ is reserved and may have special meaning to the groovy endorsed modules.

module - The name of the module to load. Translated directly to a Maven artifactId or an Ivy artifact.

version - The version of the module to use. Either a literal version '1.1-RC3' or an Ivy Range '[2.2.1,)' meaning 2.2.1 or any greater version).

The downloaded modules will be stored according to Ivy's standard mechanism with a cache root of ~/.groovy/grape

Usage

Annotation

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.

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).

Method call

Typically a call to grab will occur early in the script or in class initialization. This is to insure 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:

Multiple calls to grab in the same context with the same parameters should be idempotent. However, if the same code is called with a different ClassLoader context then resolution may be re-run.

grab is disabled by default. Starting calling Grape.initGrape() will enable grab. Any calls to grab before initGrape() is called will be ignored. Hence Grape managed classloading is opt in only. Multiple calls ti Grape.initGrape() after the first successful call are ignored.

If the args map passed into the grab call has an attribute noExceptions that evaluates true no exceptions will be thrown.

grab requires that a RootLoader or GroovyClassLoader be specified or be in the ClassLoader chain of the calling class. By default failure to have such a ClassLoader available will result in module resolution and an exception being thrown (if initGrape() has been called).

The ClassLoader passed in via the classLoader: argument and it's parent classloaders.

The ClassLoader of the object passed in as the referenceObject: argument, and it's parent classloaders.

The ClassLoader of the class issuing the call to grab

grab(HashMap) Parameters

group: - <String> - Which module group the module comes from. Translates directly to a Maven groupId. Any group matching /groovy(|\..|x|x\..)/ is reserved and may have special meaning to the groovy endorsed modules.

module: - <String> - The name of the module to load. Translated directly to a Maven artifactId.

version: - <String> and possibly <Range> - The version of the module to use. Either a literal version '1.1-RC3' or an Ivy Range '[2.2.1,)' meaning 2.2.1 or any greater version).

conf: - <String>, default 'default' - The configuration or scope of the module to download. The default conf is default: which maps to the maven runtime and master scopes.

force:- <boolean>, defaults true - Used to indicate that this revision must be used in case of conflicts, independently of

transitive: - <boolean>, default true - Whether to resolve other dependencies this module has or not.

There are two principal variants of grab, one with a single Map and one with an arguments Map and multiple dependencies map. A call to the single map grab is the same as calling grab with the same map passed in twice, so grab arguments and dependencies can be mixed in the same map, and grab can be called as a single method with named parameters.

There are synonyms for these parameters. Submitting more than one is a runtime exception.

group:, groupId:, organisation:, organization:, org:

module:, artifactId:, artifact:

version:, revision:, rev:

conf:, scope:, configuration:

Arguments Map arguments

classLoader: - <GroovyClassLaoder> or <RootClassLoader> - The ClassLoader to add resolved Jars to

refObject: - <Object> - The closest parent ClassLoader for the object's class will be treated as though it were passed in as classLoader:

validate: - <boolean>, default false - Should poms or ivy files be validated (true), or should we trust the cache (false).

Command Line Tool

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 artifcats 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 respectibely.