Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3
Info
title訳注

以下はGroovy 1.6時点の情報です。1.7での変更点についてはGroovy 1.7のリリースノートを参照してください。

Excerpt
hiddentrue

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.


Grape (The Groovy Adaptable Packaging Engine または Groovy Advanced Packaging Engine) は、Groovyでgrab()呼び出しを可能にする基盤であり、Groovyのリポジトリベースのモジュールシステムを実現するためのIvyを活用した一連のクラスです。これによって、開発者が何らかのライブラリを必須とするスクリプトを書いても、そのスクリプトのみをリリースすることが可能になります。スクリプトが、IbiblioやCodehaus、java.netのような既存のリポジトリに基づいて実行されるとき、Grapeは(実行時に)必要に応じて指定されたライブラリやそのすべての依存物をダウンロードし、リンクします。

Table of Contents
maxLevel2

基本

Excerpt
hiddentrue

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


Grapeは、モジュールのバージョン識別に関しては(用語の変更はありますが)、Ivyのやり方に従っています。

Excerpt
hiddentrue
  • 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).
  • group - モジュールが所属するモジュールグループ。MavenのgroupIdやIvyのOrganizationに相当。/groovy[x][\..*]^/ にマッチするグループは予約されていて、Groovyの標準モジュールとして特別な意味を持つ場合がある。
  • module - ロードするモジュールの名前。MavenのartifactIdやIvyのartifactに相当。
  • version - 利用するモジュールのバージョン。'1.1-RC3' のようなリテラルバージョンかIvyの範囲。例えば '[2.2.1,)' はバージョン2.2.1以降の意味。
Excerpt
hiddentrue

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


ダウンロードされたモジュールは、キャッシュルート ~/.groovy/grape の下に、Ivyの標準メカニズムに従って保存されます。

使用方法

アノテーション

Excerpt
hiddentrue

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.


アノテーションが許されている場所であればどこでも、いくつでもgroovy.lang.Grabアノテーションを付けて、そのコードが特定のライブラリに依存していることをコンパイラに知らせることができます。これは、Groovyコンパイラのクラスローダにそのライブラリを追加する効果があります。このアノテーションは、スクリプト内の他のあらゆるクラス解決に先だって検出・評価されるので、@Grabアノテーションによって取り込まれたクラスも適切に解決されます。

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

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


対象クラス(スクリプト要素へのアノテーションの場合はScriptクラス)のstaticイニシャライザに、適切な grab(...) 呼び出しが追加されます。

複数のGrapeアノテーション

Excerpt
hiddentrue

In order to use a Grape annotation multiple times you must use the Grapes annotation, e.g.:


複数のGrapeアノテーションを使うためには、Grapesアノテーションを使う必要があります。例:

Code Block
@Grapes(
    @Grab(group='commons-primitives', module='commons-primitives', version='1.0'),
    @Grab(group='org.ccil.cowan.tagsoup', module='tagsoup', version='0.9.7'))
class Example {
// ...
}
Excerpt
hiddentrue

Otherwise you'll encounter the following error:


こうしないと、次のエラーが発生してしまうでしょう:

Code Block
Cannot specify duplicate annotation on the same member

.

メソッド呼び出し

Excerpt
hiddentrue

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:


通常、grabの呼び出しはスクリプト/クラス初期化の早い段階に起こります。これは、groovyコードが対象コードに依存する前に、クラスローダがそのライブラリを利用できるようになっていることを保証するためです。よくある呼び出し例を以下に示します。

Code Block
import groovy.grape.Grape
// random maven library
Grape.grab(group:'com.jidesoft', module:'jide-oss', version:'[2.2.0,)')
Grape.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')

Excerpt
hiddentrue

* 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を呼び出しても効果は同じになります。ただし、同じコードでも異なるクラスローダコンテキストで呼び出せば、再度依存性の解決が実行されます。
Excerpt
hiddentrue
  • 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 はデフォルトでは利用できなくなっています。 Grape.initGrape() を呼ぶことで利用可能になります。 initGrape() 以前にgrabを呼んでも無視されます。Grape管理下でのクラスローディングはあくまでオプションだからです。一度呼び出しに成功した後は、何度 Grape.initGrape() を呼んでも無視されます。
  • grab 呼び出しに渡される args マップの noExceptions 属性が true と評価される場合、例外は発生しなくなります。
  • grab では、RootLoaderまたはGroovyClassLoaderが指定されるか、あるいは呼び出し元クラスのクラスローダチェインの中に存在することが必要です。デフォルトでは、これらのクラスローダが利用できないと、モジュール解決で例外が発生します( initGrape()が呼ばれている場合)。
    • classLoader: 引数で渡されたクラスローダと、その親クラスローダ
    • referenceObject: 引数で渡されたオブジェクトのクラスローダと、その親クラスローダ
    • grab の呼び出し元クラスのクラスローダ

grab(HashMap) パラメータ

Excerpt
hiddentrue
  • 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).
  • classifier: - <String> - The Maven classifier to resolve by.
  • 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
  • conflicts manager
  • changing: - <boolean>, default false - Whether the artifact can change without it's version designation changing.
  • transitive: - <boolean>, default true - Whether to resolve other dependencies this module has or not.

  • group: - <String> - モジュールが属するモジュールグループ。MavenのgroupIdに相当。 /groovy(|\..|x|x\..)/ にマッチするグループは予約されていて、Groovyの標準モジュールとして特別な意味を持つ場合がある。
  • module: - <String> - ロードするモジュールの名前。MavenのartifactIdに相当。
  • version: - <String> または <Range> - 利用するモジュールのバージョン。'1.1-RC3' のようなリテラルバージョンかIvyの範囲。例えば '[2.2.1,)' はバージョン2.2.1以降の意味。
  • classifier: - <String> - 解決時に使うMavenのclassifier
  • conf: - <String>, デフォルトは'default' - ダウンロードするモジュールの設定やスコープ。confのデフォルトは default: で、mavenの runtimemaster スコープに対応する。
  • force:- <boolean>, デフォルトはtrue - コンフリクト発生時に、コンフリクトマネージャとは無関係に必ずこのリビジョンが必要であることを示す。
  • changing: - <boolean>, デフォルトはfalse - バージョン名は同じままでartifactが変更されることがあるか。
  • transitive: - <boolean>, デフォルトはtrue - このモジュールが、解決すべき他の依存関係を持っているかどうか。

Excerpt
hiddentrue

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.


grab には二つの主要なバリエーションがあります。単一のMapをとるものと、引数Mapおよび複数の依存先Mapをとるものです。一つのマップをとるgrabの呼び出しは、同じマップを二回渡してgrabを呼ぶのと同じことです。grabの引数と依存先は一つのマップに合成されるので、名前付きパラメータをとる単一のメソッドとしてgrabを呼び出すことも可能です。
Excerpt
hiddentrue

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:

引数Mapの引数

Excerpt
hiddentrue
  • 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).
  • noExceptions: - <boolean>, default false - If ClassLoader resolution or repository querying fails, should we throw an exception (false) or fail silently (true).

  • classLoader: - <GroovyClassLaoder> または <RootClassLoader> - 解決されたJarを追加するクラスローダ
  • refObject: - <Object> - このオブジェクトのクラスの直接の親クラスローダが classLoader: で指定されたように扱われる。
  • validate: - <boolean>, デフォルトはfalse - pomやivy関連ファイルを検証すべきか(true)、またはキャッシュを信用するか(false)。
  • noExceptions: - <boolean>, デフォルトはfalse - クラスローダの解決やリポジトリの問い合わせが失敗したとき、例外を発生させるか(false)、または黙って失敗するか(true)

コマンドラインツール

Excerpt
hiddentrue

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


Grapeでは、ローカルgrapeキャッシュの検査や管理のために、コマンドラインから実行可能な 'grape' コマンドが追加されました。

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

Excerpt
hiddentrue

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


これは指定されたgroovyモジュールまたはmaven artifactをインストールします。バージョンを指定した場合はそのバージョンがインストールされ、省略されれば('*'を指定したときのように)最新のバージョンが使われます。

Code Block
grape list

Excerpt
hiddentrue

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


ローカルにインストールされているモジュールとそのバージョンを(groovyモジュールについてはそのフルmaven名と共に)一覧表示します。

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

Excerpt
hiddentrue

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 respectively. -ivy may be passed to see the dependencies expressed in an ivy like format.


指定されたモジュールおよびそれが依存するモジュールに対応するjarファイルの場所を返します。オプションで -ant, -dos, -shell などを指定すれば、それぞれAntスクリプト、Windowsバッチファイル、Unixシェルスクリプトなどに適した形式で取得できます。-ivy を指定すれば、ivyに適した形式で表示することも可能です。

高度な設定

プロキシ設定

Excerpt
hiddentrue

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:


ファイアウォールの存在などで、プロキシサーバ経由でGroovy/Grapeを使う必要がある場合、http.proxyHostおよびhttp.proxyPortシステムプロパティを使って、コマンドにその設定を指定できます:

Code Block
groovy -Dhttp.proxyHost=yourproxy -Dhttp.proxyPort=8080 yourscript.groovy

Excerpt
hiddentrue

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


あるいは、JAVA_OPTS環境変数にこれらのプロパティを追加することで、これをシステムワイドに設定することもできます:

Code Block
JAVA_OPTS = -Dhttp.proxyHost=yourproxy -Dhttp.proxyPort=8080

リポジトリディレクトリ

Excerpt
hiddentrue

If you need to change the directory grape uses for downloading libraries you can specify the grape.root system property to change the default (which is ~/.groovy/grape)


grapeがライブラリのダウンロードに使うディレクトリを変更する必要がある場合、grape.rootシステムプロパティを指定して、デフォルト値(~/.groovy/grape)を変えることができます。

Code Block
groovy -Dgrape.root=/repo/grape yourscript.groovy

Ivy設定のカスタマイズ

Excerpt
hiddentrue

//TODO expand on discussion of grapeConfig.xml

You can customize the ivy settings that Grape uses by creating a ~/.groovy/grapeConfig.xml file. If no such file exists, here are the default settings used by Grape:


//TODO grapeConfig.xmlについてもっと詳しく

~/.groovy/grapeConfig.xmlファイルを作成することで、Grapeが使うivyの設定をカスタマイズすることができます。このファイルが存在しないときは、これがGrapeが使うデフォルト設定になります:

Code Block
<ivysettings>
  <settings defaultResolver="downloadGrapes"/>
  <resolvers>
    <chain name="downloadGrapes">
      <filesystem name="cachedGrapes">
        <ivy pattern="${user.home}/.groovy/grapes/[organisation]/[module]/ivy-[revision].xml"/>
        <artifact pattern="${user.home}/.groovy/grapes/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
      </filesystem>
      <!-- todo add 'endorsed groovy extensions' resolver here -->
      <ibiblio name="codehaus" root="http://repository.codehaus.org/" m2compatible="true"/>
      <ibiblio name="ibiblio" m2compatible="true"/>
      <ibiblio name="java.net2" root="http://download.java.net/maven/2/" m2compatible="true"/>
    </chain>
  </resolvers>
</ivysettings>

Excerpt
hiddentrue

For more information on how to customize these settings, please refer to the Ivy documentation.


この設定のカスタマイズ方法の詳細は、Ivyのドキュメントを参照してください。

ローカルなMaven2リポジトリの追加

Excerpt
hiddentrue

If you find yourself wanting to reuse artifacts that you already have locally in your Maven2 repository, then you can add this line to your ~/.groovy/grapeConfig.xml:


自前のローカルなMaven2リポジトリの中の既存のartifactを再利用したい場合には、~/.groovy/grapeConfig.xml に次の行を追加することができます:

Code Block
<ibiblio name="local" root="file:${user.home}/.m2/repository/" m2compatible="true"/>

Excerpt
hiddentrue

And further customize your Grape configuration:


そしてGrape設定を次のようにカスタマイズします:

Code Block
<?xml version="1.0"?>
<ivysettings>
  <settings defaultResolver="downloadGrapes"/>
  <resolvers>
    <chain name="downloadGrapes">
      <!-- todo add 'endorsed groovy extensions' resolver here -->
      <ibiblio name="local" root="file:${user.home}/.m2/repository/" m2compatible="true"/>
      <filesystem name="cachedGrapes">
        <ivy pattern="${user.home}/.groovy/grapes/[organisation]/[module]/ivy-[revision].xml"/>
        <artifact pattern="${user.home}/.groovy/grapes/[organisation]/[module]/[type]s/[artifact]-[revision].[ext]"/>
      </filesystem>
      <ibiblio name="codehaus" root="http://repository.codehaus.org/" m2compatible="true"/>
      <ibiblio name="ibiblio" m2compatible="true"/>
      <ibiblio name="java.net2" root="http://download.java.net/maven/2/" m2compatible="true"/>
    </chain>
  </resolvers>
</ivysettings>

利用例

Excerpt
hiddentrue

Using Apache Commons Collections:


Apache Commonsコレクションの利用:

Code Block
// create and use a primitive array
import org.apache.commons.collections.primitives.ArrayIntList

@Grab(group='commons-primitives', module='commons-primitives', version='1.0')
def createEmptyInts() { new ArrayIntList() }

def ints = createEmptyInts()
ints.add(0, 42)
assert ints.size() == 1
assert ints.get(0) == 42

Excerpt
hiddentrue

Using TagSoup:


TagSoupの利用:

Code Block
// find the PDF links in the Java 1.5.0 documentation
@Grab(group='org.ccil.cowan.tagsoup', module='tagsoup', version='0.9.7')
def getHtml() {
    def parser = new XmlParser(new org.ccil.cowan.tagsoup.Parser())
    parser.parse("http://java.sun.com/j2se/1.5.0/download-pdf.html")
}
html.body.'**'.a.@href.grep(~/.*\.pdf/).each{ println it }

Excerpt
hiddentrue

Using Google Collections:


Googleコレクションの利用:

Code Block
// Google Collections example


import com.google.common.collect.HashBiMap
@Grab(group='com.google.code.google-collections', module='google-collect', version='snapshot-20080530')
def getFruit() { [grape:'purple', lemon:'yellow', orange:'orange'] as HashBiMap }
assert fruit.lemon == 'yellow'
assert fruit.inverse().yellow == 'lemon'

Excerpt
hiddentrue

Launching a Jetty server to server Groovy templates:


Groovyテンプレートが使えるJettyサーバの起動:

Code Block
@Grapes([
    @Grab(group='org.eclipse.jetty.aggregate', module='jetty-server', version='8.1.7.v20120910'),
    @Grab(group='org.eclipse.jetty.aggregate', module='jetty-servlet', version='8.1.7.v20120910'),
    @Grab(group='javax.servlet', module='javax.servlet-api', version='3.0.1')])

import org.eclipse.jetty.server.Server
import org.eclipse.jetty.servlet.*
import groovy.servlet.*

def runServer(duration) {
    def server = new Server(8080)
    def context = new ServletContextHandler(server, "/", ServletContextHandler.SESSIONS)
    context.resourceBase = "."
    context.addServlet(TemplateServlet, "*.gsp")
    server.start()
    sleep duration
    server.stop()
}

runServer(10000)

Excerpt
hiddentrue

Grape will download Jetty and its dependencies on first launch of this script, and cache them. We're creating 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.


このスクリプトの最初の起動時に、GrapeはJettyとそれが依存するモジュールをダウンロードし、キャッシュします。新しいJetty Serverをポート8080で生成し、コンテキストのルートでGroovyのTemplateServletを使えるようにします(Groovyには強力なテンプレートエンジンメカニズムが備わっています)。そしてサーバを起動し、一定時間実行させます。誰かがhttp://localhost:8080/somepage.gspにアクセスするたびに、ユーザにはsomepage.gspテンプレートが表示されるでしょう。このテンプレートページはサーバスクリプトと同じディレクトリに置く必要があります。

関連情報:

Using Hibernate with Groovy
http://stackoverflow.com/questions/192432/getting-groovys-grape-going