Message-ID: <1159696981.22024.1406843174902.JavaMail.email@example.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_22023_1192064892.1406843174901" ------=_Part_22023_1192064892.1406843174901 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Grape (The Groovy Adaptable Packaging Engine or Groovy Advanced Packagin=
g Engine) is the infrastructure enabling the
grab() calls in G=
roovy, a set of classes leveraging Ivy to allow for a repository dr=
iven module system for Groovy. This allows a developer to write a script wi=
th 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.
The prototype is ready for inclusion into the trunk immediately, however= the principal dependent library used (Apache Ivy) is a SVN snapsh= ot. We should at least wait for a Beta 2 release and preferably for a= n RC release of the library before merging into trunk. That makes it = a possible 1.6 candidate, and more likely a 1.7 candidate.=20
Grape follows the Ivy conventions for module version identificaiton, wit= h naming change.=20
group- Which module group the module comes from. Translat= es directly to a Maven groupId or an Ivy Organization. Any group matching <= code>/groovy[x][\..*]^/ is reserved and may have special meaning to = the groovy endorsed modules.
module- The name of the module to load. Translated direct= ly to a Maven artifactId or an Ivy artifact.
version- The version of the module to use. Either a liter= al version '1.1-RC3' or an Ivy Range '[2.2.1,)' meaning 2.2.1 or any greate= r version).
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 cl= assloader 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.=20 =20
grab(...) call will be added to the static i=
nitializer of the class of the containing class (or script class in the cas=
e of an annotated script element).
TODO: How do we add a grab annotation to straight scripts? The current w= orkaround is to annotate something in the script that can accept an annotat= ion, like a method or parameter.
Typically a call to grab will occur early in the script or in class init= ialization. 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:=20 =20
grab(Object self, Map attrs), =
grab(Object self, Map attrs, Map... dependencies) will be =
added to the DGM so that references to the backing Grape classes will not b=
e needed. These will be proxies to the main Grape class calls.
grabis disabled by default. Starting calling
Grape.= initGrape()will enable grab. Any calls to grab before
initGra= pe()is called will be ignored. Hence Grape managed classloading is = opt in only.
argsmap passed into the
grabcall has= an attribute
noExceptionsthat evaluates true no exceptions w= ill be thrown.
grabrequires that a RootLoader or GroovyClassLoader be sp= ecified or be in the ClassLoader chain of the calling class. By default fai= lure to have such a ClassLoader available will result in module resolution = and an exception being thrown (if
initGrape()has been called)= .=20
classLoader:argument an= d it's parent classloaders.
referenceObject:= code> argument, and it's parent classloaders.
grab(String)is a shortcut for e= ndorsed groovy modules and will be equivilant to
grab(group:'groovy.endorsed', module:&l= t;the module>, version:<the version of groovy being run>)= code>
TODO: all discussion of grab(String} are purely hypothetical as it hasn'= t been prototyped or the needed infrastructure set up
group:- <String> - Which module group the module co= mes from. Translates directly to a Maven groupId. Any group matching
)/is reserved a= nd 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 configurat= ion or scope of the module to download. The default conf is
default:<= /code> which maps to the maven
force:- <boolean>, defaults true - Used to indicate = that this revision must be used in case of conflicts, independently of
changing:- <boolean>, default false - Whether the a= rtifact can change without it's version designation changing.
transitive:- <boolean>, default true - Whether to r= esolve 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 i=
n twice, so grab arguments and dependencies can be mixed in the same map, a=
nd grab can be called as a single method with named parameters.
There are synonyms for these parameters. Submitting more than one is a r= untime exception.=20
Grape may want support simple ranges ('2.2.1'..'*') or '2.2.1'..<'3.0= .0' meaning any version greater than 2.2.1 but no 3.x version. But there ar= e implementation problems, trying either of these ranges creates a runtime = error having to do with enumerating the list.
classLoader:- <GroovyClassLaoder> or <RootClassL= oader> - The ClassLoader to add resolved Jars to
refObject:- <Object> - The closest parent ClassLoad= er for the object's class will betreated as though it were passed in as
validate:- <boolean>, default false - Should poms o= r ivy files be validated (true), or should we trust the cache (false).
noExceptions:- <boolean>, default false - If ClassL= oader resolution or repository querying fails, should we throw an exception= (false) or fail silently (true).
GroovyStarter has been enhanced with an additonal
rab option. All three main arguments are required (group, module, ve=
rsion). Resolved jars will be added to the
RootLoader. These m=
odules will be resolved prior to the main class call.
LoaderConfigu= rationconf files
LoaderConfiguration has been enhanced with an additional 'g=
rab' line option, where the option is followed by all three arguments (grou=
p, module, version). Resolved jars will be added as though they were specif=
ically mentioned by a 'load' line option. These lines are similarly subject=
to property replacement as 'load' lines are.
The GroovyC ant task has been enhanced with
ild elements. The attributes
module, and <=
code>version specify the module to grab.
TODO: currently this doesn't work when fork=3D'true'
The downloaded modules will be stored according to Ivy's standard mechan=
ism with a cache root of
This installs the specified groovy module or maven artifact. If a versio= n is specified that specific version will be installed, otherwise the most = recent version will be used (as if '*' we passed in).=20 =20
Lists locally installed modules (with their full maven name in the case = of groovy modules) and versions.=20 =20
This returns the file locations of the jars representing the artifcats f= or the specified module(s) and the respective transitive dependencies.= =20
The motivation for introducing Grape into groovy is to resolve the libra= ry and module proliferation problem we are encountering. As a general purpo= se language Grape is suitable for a lot of wildly variable tasks. Providing= groovy ways to do those things can crate 'bloat' because a large number of= classes that are=20
Credit for coming up with the name Grape goes to Jörg Staudemeyer a= nd grab Andres Almiray.=20
Maven is big, there are tons of Java libraries that are already deployed= in a well-known infrastructure. Because almost all of these a= re straight Java they are all usable in Groovy out of the box.=20
GroovyStarter does do some existing library management, namely loading e= very singe jar in ~/.groovy/lib into the RootLoader. With Grape installed s= uch behavior can continue, and is merely duplicate effort with no adverse i= mplications. In the 2.0 timeframe we may want to look into deprecating or r= emoving the auto-include of the ~/groovy/lib directory.=20
A 0.1.0 protptype is a=
vailable. This shows the
grab(...) method, the
annotation, and command line tools. Examples are available in subve=
rsion in src/examples=
, except for the annotation, where the best examples are in the test class.
This version may conflict with Gant, only one of the Ivy files should ex=
$GROOVY_HOME/libs. If the beta-1 jar is left in plac=
e then Grape may not work.
We may want to increase the kind of repositories that Grape can handle f= rom simple Ivy and Maven repositories to other areas such as OSGi Repositor= y Bundles , JNLP (WebStart) files and JSR-277 JAM files.