《Groovy官方教程》Grape依赖管理器

原文链接 译文链接 译者：JackWang

1 快速入门

1.1添加一个依赖

Grape是一个内嵌在Groovy里的Jar包依赖管理器。Grape让你可以快速添加maven仓库依赖到你的classpath里，使脚本运行更加简单。最简单的一种用法是只需要在你的脚本里添加一个注解：

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

@Grab也支持简洁版：

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

注意，这里我们用到了import，这是推荐的做法。当然你也可以在mvnrepository.com搜索到依赖包然后使用@Grab注解形式加到pom.xml实体里。

1.2特定的仓库

不是所有的依赖都在maven中心仓库里，你可以像下面这样添加新的仓库:

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

1.3Maven分类器

有些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')

（译者注：原文标题是Excluding Transitive Dependencies，译者翻译为过渡依赖。译者理解为那些非稳定版本的依赖，如果读者有更好的理解或翻译请留言，谢谢）

1.5JDBC驱动

你可能需要加载JDBC驱动，因此你需要将JDBC驱动依赖添加到系统类加载器中，示例如下：

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

1.6从Groovy Shell中使用Grape

通过groovysh使用grape需要调用一个变量:

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（比如说将-Dgroovy.grape.report.downloads=true添加JAVA_OPTS或调用它）,Grape将会打印下面的一些系统信息：

• 开始解析依赖
• 开始下载工件(原文为artifact，工件的意思)
• 重新下载工件
• 现在工件的时间和大小

如果要更加详细的日志，可以通过提高日志级别(默认为-1),示例如下：

-Divy.message.logger.level=4

2 详细

Grape（The Groovy Adaptable Packaging Engine or Groovy Advanced Packaging Engine)）是Groovy里内嵌的一个基础组件，通过grab()方法调用，一些类可以使用Ivy来打包成仓库给Groovy用。这就支持开发者通过写一段脚本来实现一些核心库的需求。装载这段脚本，Grape将会在运行时下载并链接所有依赖的库。即便这些库存在于Jcenter，Ibiblio和java.net

Grape遵从Ivy对模块版本标识和命名转换。

• group – 模块属于一个模块组。对应Maven的groupId或者一个Ivy组织。任何匹配/groovy[x][\..*]^/的组都是被保留的，对于Groovy是有特定意义的。
• module – 加载的模块名字，对应Mavne的artifactId或Ivy的artifact
• version – 模块使用的版本号，要么是字符串 ‘1.1-RC3’，要么是Ivy的[2.2.1,）代表2.2.1或更高版本
• classifier – 可选的分类器，比如jdk15

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注解

如果需要在同一个节点使用一个注解多次可以使用@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

3.3 方法调用

一般地grab调用会在一个类或脚本初始化的时候进行。这可以确保groovy代码依赖的库在运行时都被类加载器加载进去。一种典型的调用如下：

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是等价的，但是如果使用不同的类加载器可能需要重新运行
• 如果参数列表传到grab调用有一个noExceptions参数，那么将不会抛出参数
• grab需要一个rootLoader或GroovyClassLoader，也可以是调用类的类加载器链。默认情况下列的情形将会失败并且抛出异常

• 通过classLoader传递的类加载器：参数和它的父类加载器
• 对象的加载器作为引用对象传入，参数和它的父类加载器
• 类的类加载器调用grab

3.3.1 grab(HashMap)参数

• group: – – 模块所属的模块组，对应Maven的groupId，任何匹配/groovy(|\..|x|x\..)/的组都是保留的，在Groovy模块中有特殊用途
• module:– 要加载的模块名，对应Maven的artifactId
• version:-也有可能是-使用的模块版本号，要么是字符串1.1-RC3要么是Ivy Range [2.2.1,)表示2.2.1版本或更高版本
• classifier:–Maven解析的分类器
• conf:-，默认default’ – The configuration or scope of the module to download. The default conf is `default:映射到maven的runtime和master范围
• force-默认是true，用于冲突时的修复，依赖于冲突管理器
• changing：-，默认是false，是否工件可以修改而不管版本的改变
• transitive:-,默认是true，是否解析其他依赖

grab有两个基本变量，一个单个的map一个是带一个map和多个依赖的map。调用单个map的grab和将一个相同的map传入两次调用是一样的，因此grab参数和依赖可以混合在一个map里，grab可以当成一个具有命名好参数的方法调用。
下面的参数每组都是相同的意思，如果传入多余一个将是一个运行时错误

• group:, groupId:, organisation:, organization:, org:
• module:, artifactId:, artifact:
• version:, revision:, rev:
• conf:, scope:, configuration:

3.3.2 参数列表

• classLoader: – 或-解析jar包的类加载器
• refObject:–最近的父类加载器，可以作为加载器参数被传递
• validate:-,默认是false,是否验证poms或ivy文件，或者是否直接信任缓存信息(默认false)
• noExceptions:-,默认是false，如果类加载器或参考查询失败，是否应该抛出异常或吞并异常（默认情况）

3.4 命令行工具

Grape增加了一个命令行来执行grape,可以用来检视和管理本地grape缓存。

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

这条命令会安装特定的groovy模块或maven工件，如果指定了版本，那么将安装特定的的版本，否则安装最新的版本（类似我们传递 * 参数）

grape list

列出本地安装的模块（如果是groovy模块，会显示完整的maven名字）和版本

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

返回安装的模块或工件的文件位置，并且会返回传递依赖模块的位置。你可以传入可选参数-ant,-dos,-shell中来得到ant脚本，windows批处理或unix shell脚本格式文件，-ivy将会得到类ivy格式的依赖

3.5 高级配置

3.5.1 仓库目录

如果你需要改变下载库的grape目录，可以使用grape.root系统属性来改变默认值（默认值是~/.groovy/grape）

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

3.5.2 自定义Ivy设置

你可以自定义ivy的是指，通过创建一个~/.groovy/grapeConfig.xml文件，如果没有这个文件，Grape会使用默认配置，详细参考这里。需要查找更多关于自定义设置的文档，可以参考Ivy文档。

3.6 更多示例

使用Apache Commons集合工具类

// create and use a primitive array list
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

使用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.'**'[e-mail](~/.*\.pdf/).each{ println it }

使用Google集合工具类

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模块

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

第一次启动这个脚本的时候Grape会下载Jetty和它的依赖，并且会缓存它们。我们在8080端口创建了一个Jetty服务，并且将Groovy的TemplateServlet最为根服务。Groovy有自己强大的模板引擎机制。我们启动这个服务并且运行一段时间。每次有人访问http://localhost:8080/somepage.gsp的时候，它会显示somepage.gsp给用户，这些模板页是放在一个相同的目录下座位服务器脚本。