1. 快速入门

1.1. 添加依赖

Grape 是一个嵌入到 Groovy 中的 JAR 依赖管理器。Grape 允许您快速将 Maven 仓库依赖添加到您的类路径中，使脚本编写更加容易。最简单的用法就像向脚本添加注解一样简单：

@Grab(group='org.springframework', module='spring-orm', version='5.2.8.RELEASE')
import org.springframework.jdbc.core.JdbcTemplate

@Grab 也支持简写符号：

@Grab('org.springframework:spring-orm:5.2.8.RELEASE')
import org.springframework.jdbc.core.JdbcTemplate

请注意，我们这里使用的是带注解的导入，这是推荐的方式。您还可以在 mvnrepository.com 上搜索依赖项，它会为您提供 pom.xml 条目的 @Grab 注解形式。

1.2. 指定额外的仓库

并非所有依赖项都在 Maven Central 中。您可以像这样添加新的依赖项：

@GrabResolver(name='restlet', root='http://maven.restlet.org/')
@Grab(group='org.restlet', module='org.restlet', version='1.1.6')

1.3. Maven 分类器

有些 Maven 依赖项需要分类器才能解析。您可以像这样修复它：

@Grab(group='net.sf.json-lib', module='json-lib', version='2.2.3', classifier='jdk15')

1.4. 排除传递性依赖

有时您会希望排除传递性依赖，因为您可能已经在使用某个构件的稍微不同但兼容的版本。您可以按如下方式进行操作：

@Grab('net.sourceforge.htmlunit:htmlunit:2.8')
@GrabExclude('xml-apis:xml-apis')

1.5. JDBC 驱动

由于 JDBC 驱动的加载方式，您需要配置 Grape 将 JDBC 驱动依赖项附加到系统类加载器。即：

@GrabConfig(systemClassLoader=true)
@Grab(group='mysql', module='mysql-connector-java', version='5.1.6')

1.6. 在 Groovy Shell 中使用 Grape

从 groovysh 中使用方法调用变体：

groovy.grape.Grape.grab(group:'org.springframework', module:'spring', version:'2.5.6')

1.7. 代理设置

如果您在防火墙后面和/或需要通过代理服务器使用 Groovy/Grape，您可以通过 http.proxyHost 和 http.proxyPort 系统属性在命令行中指定这些设置：

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

或者您可以通过将这些属性添加到您的 JAVA_OPTS 环境变量中来使其系统范围生效：

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

1.8. 日志

如果您想查看 Grape 正在做什么，请将系统属性 groovy.grape.report.downloads 设置为 true（例如，在调用或 JAVA_OPTS 中添加 -Dgroovy.grape.report.downloads=true），Grape 将在 System.error 中打印以下信息：

  • 开始解析依赖项

  • 开始下载构件

  • 重试下载构件

  • 已下载构件的下载大小和时间

要以更详细的方式记录，请提高 Ivy 日志级别（默认为 -1）。例如 -Divy.message.logger.level=4。

2. 详情

Grape (Groovy 可调整打包引擎 或 Groovy 高级打包引擎) 是在 Groovy 中启用 grab() 调用的基础设施，它是一组利用 Ivy 的类，允许 Groovy 拥有一个仓库驱动的模块系统。这使得开发人员可以编写一个具有任意库需求的脚本，并且只发布脚本。Grape 将在运行时，在脚本从现有仓库（如 Maven Central）运行时，按需下载并链接命名库和所有形成传递闭包的依赖项。

Grape 遵循 Ivy 的模块版本识别约定，但名称有所更改。

  • group - 模块来自哪个模块组。直接转换为 Maven groupId 或 Ivy Organization。任何与 /groovy[x][\..*]^/ 匹配的组都被保留，并且可能对 Groovy 认可的模块具有特殊含义。

  • module - 要加载的模块的名称。直接转换为 Maven artifactId 或 Ivy artifact。

  • version - 要使用的模块的版本。可以是文字版本 `1.1-RC3' 或 Ivy 范围 `[2.2.1,)'（表示 2.2.1 或任何更高版本）。

  • classifier - 要使用的可选分类器（例如，jdk15）

下载的模块将根据 Ivy 的标准机制存储，缓存根目录为 ~/.groovy/grapes

3. 用法

3.1. 注解

可以在任何接受注解的地方添加一个或多个 groovy.lang.Grab 注解，以告知编译器此代码依赖于特定的库。这将导致将该库添加到 Groovy 编译器的类加载器中。此注解在脚本中任何其他类解析之前被检测和评估，因此导入的类可以通过 @Grab 注解正确解析。

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
    }
}

一个适当的 grab(…​) 调用将被添加到包含类（或带注解的脚本元素情况下的脚本类）的静态初始化器中。

3.2. 多个 Grape 注解

在 Groovy 的早期版本中，如果你想在同一个节点上多次使用 Grab 注解，你必须使用 @Grapes 注解，例如：

@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 {
// ...
}

否则你会遇到以下错误：

Cannot specify duplicate annotation on the same member

但在最新版本中，@Grapes 纯粹是可选的。

技术说明

  • 最初，Groovy 存储 Grab 注解以供运行时访问，并且字节码中不允许重复。在当前版本中，@Grab 只有 SOURCE 保留，因此多次出现不是问题。

  • Grape 的未来版本可能会支持使用 Grapes 注解来提供某种程度的结构化，例如允许 GrabExclude 或 GrabResolver 注解仅应用于 Grab 注解的子集。

3.3. 方法调用

通常，对 grab 的调用会发生在脚本的早期或类的初始化中。这是为了确保在 Groovy 代码依赖于这些库之前，这些库已经对 ClassLoader 可用。几个典型的调用可能如下所示：

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'])

  • 在相同上下文中以相同参数对 grab 进行多次调用应该是幂等的。但是，如果相同的代码以不同的 ClassLoader 上下文调用，则可能会重新运行解析。

  • 如果传递给 grab 调用的 args map 具有属性 noExceptions 且其值为 true，则不会抛出异常。

  • grab 要求指定 RootLoader 或 GroovyClassLoader，或者其位于调用类的 ClassLoader 链中。默认情况下，如果无法获得此类 ClassLoader，将导致模块解析失败并抛出异常。

    • 通过 classLoader: 参数传入的 ClassLoader 及其父 ClassLoader。

    • 作为 referenceObject: 参数传入的对象的 ClassLoader 及其父 ClassLoader。

    • 发出 grab 调用的类的 ClassLoader

3.3.1. grab(HashMap) 参数

  • 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 分类器。

  • conf: - <String>，默认 default' - 要下载的模块的配置或作用域。默认 conf 是 `default:，它映射到 maven 的 runtime 和 master 作用域。

  • force:- <boolean>，默认为 true - 用于指示在冲突情况下必须使用此版本，与

  • 冲突管理器无关

  • changing: - <boolean>，默认为 false - 构件是否可以在其版本标识不改变的情况下改变。

  • transitive: - <boolean>，默认为 true - 是否解析此模块的其他依赖项。

grab 有两个主要变体，一个带单个 Map，另一个带一个 arguments Map 和多个 dependencies map。调用单个 Map 的 grab 等同于用相同的 Map 两次调用 grab，因此 grab 参数和依赖项可以混合在同一个 Map 中，并且 grab 可以作为具有命名参数的单个方法调用。

这些参数有同义词。提交多个将导致运行时异常。

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

  • module:, artifactId:, artifact:

  • version:, revision:, rev:

  • conf:, scope:, configuration:

3.3.2. Arguments Map 参数

  • classLoader: - <GroovyClassLoader> 或 <RootClassLoader> - 用于添加已解析 Jar 的 ClassLoader

  • refObject: - <Object> - 对象的类的最近父 ClassLoader 将被视为通过 classLoader: 传入。

  • validate: - <boolean>，默认 false - 是否应验证 pom 或 ivy 文件 (true)，还是应信任缓存 (false)。

  • noExceptions: - <boolean>，默认 false - 如果 ClassLoader 解析或仓库查询失败，我们应该抛出异常 (false) 还是静默失败 (true)。

3.4. 命令行工具

Grape 添加了一个名为 `grape' 的命令行可执行文件，用于检查和管理本地 grape 缓存。

grape install [-hv] <group> <module> [<version>] [<classifier>]

这将安装指定的 groovy 模块或 maven 构件。如果指定了版本，则将安装该特定版本，否则将使用最新版本（如同传入了 `*'）。

grape list

列出本地安装的模块（在 groovy 模块的情况下，包括其完整的 maven 名称）和版本。

grape resolve [-adhisv] (<groupId> <artifactId> <version>)+

这将返回表示指定模块的构件及其相应传递依赖项的 jar 文件的位置。您可以选择传入 -ant、-dos 或 -shell 以获取适用于 ant 脚本、windows 批处理文件或 unix shell 脚本格式的依赖项。可以传入 -ivy 以查看以 ivy 类似格式表示的依赖项。

grape uninstall [-hv] <group> <module> <version>

这将卸载一个特定的 grape：它非传递性地从 grape 缓存中删除相应的 jar 文件。

3.5. 高级配置

3.5.1. 仓库目录

如果您需要更改 Grape 用于下载库的目录，您可以指定 grape.root 系统属性来更改默认值（默认为 ~/.groovy/grapes）

groovy -Dgrape.root=/repo/grapes yourscript.groovy

3.5.2. 自定义 Ivy 设置

您可以通过创建 ~/.groovy/grapeConfig.xml 文件来自定义 Grape 使用的 Ivy 设置。如果不存在这样的文件，此处是 Grape 使用的默认设置。

有关如何自定义这些设置的更多信息，请参阅 Ivy 文档。

3.6. 更多示例

使用 Apache Commons Collections

// create and use a primitive array list
@Grab(group='commons-primitives', module='commons-primitives', version='1.0')
import org.apache.commons.collections.primitives.ArrayIntList

def createEmptyInts() { new ArrayIntList() }

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

使用 TagSoup

// find the PDF links of the Java specifications
@Grab(group='org.ccil.cowan.tagsoup', module='tagsoup', version='1.2.1')
def getHtml() {
    def parser = new XmlParser(new org.ccil.cowan.tagsoup.Parser())
    parser.parse("https://docs.oracle.com/javase/specs/")
}
html.body.'**'.a.@href.grep(~/.*\.pdf/).each{ println it }

使用 Google Collections

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'

启动 Jetty 服务器以提供 Groovy 模板

@Grab('org.eclipse.jetty.aggregate:jetty-server:8.1.19.v20160209')
@Grab('org.eclipse.jetty.aggregate:jetty-servlet:8.1.19.v20160209')
@Grab('javax.servlet:javax.servlet-api:3.0.1')
import org.eclipse.jetty.server.Server
import org.eclipse.jetty.servlet.ServletContextHandler
import groovy.servlet.TemplateServlet

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)

Grape 将在此脚本首次启动时下载 Jetty 及其依赖项，并将其缓存。我们创建一个新的 Jetty 服务器在 8080 端口，然后将 Groovy 的 TemplateServlet 公开在上下文的根目录——Groovy 自带强大的模板引擎机制。我们启动服务器并让它运行一段时间。每次有人访问 https://:8080/somepage.gsp 时，它都会向用户显示 somepage.gsp 模板——这些模板页面应该位于与此服务器脚本相同的目录中。