Grapes and grab()

...

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.

...

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.

import com.jidesoft.swing.JideSplitButton
@Grab(group='com.jidesoft', module='jide-oss', version='[2.2.1,)')
public class TestClassAnnotation {
    public static String testMethod () {
        return JideSplitButton.class.name
    }
}

...

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:

// random maven library
grab(group:'org.jidesoft', module:'jide-oss', version:'[2.2.0,)')
grab([group:'org.apache.ivy', module:'ivy', version:'2.0.0-beta1', conf:['default', 'optional']],
     [group:'org.apache.ant', module:'ant', version:'1.7.0'])


// endorsed Groovy Module
// FUTURE grab('Scriptom')

* grab(Object self, String module),- grab(Object self, Map attrs), and grab(Object self, Map attrs, Map... dependencies) will be added to the DGM so that references to the backing Grape classes will not be needed. These will be proxies to the main Grape class calls.

• 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.
• 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(String) is a shortcut for endorsed groovy modules and will be equivilant to grab(group:'groovy.endorsed', module:<the module>, version:<the version of groovy being run>)-

  TODO: all discussion of grab(String} are purely hypothetical as it hasn't been prototyped or the needed infrastructure set up

...

Command Line Tools

grape install <groupId> <artifactId> [<version>]

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

grape list

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

grape resolve (<groupId> <artifactId> <version>)+

...