22、Gradle Java 插件

Java 插件

Java 插件向一个项目添加了 Java 编译、 测试和 bundling 的能力。它是很多其他 Gradle 插件的基础服务。

用法

要使用Java 插件，请在构建脚本中加入：

使用 Java 插件

build.gradle

apply plugin: 'java'  

源集

Java 插件引入了一个源集的概念。一个源集只是一组用于编译并一起执行的源文件。这些源文件可能包括 Java 源代码文件和资源文件。其他有一些插件添加了在源集里包含 Groovy 和 Scala 的源代码文件的能力。一个源集有一个相关联的编译类路径和运行时类路径。

源集的一个用途是，把源文件进行逻辑上的分组，以描述它们的目的。例如，你可能会使用一个源集来定义一个集成测试套件，或者你可能会使用单独的源集来定义你的项目的 API 和实现类。

Java 插件定义了两个标准的源集，分别是 main 和 test。main 源集包含你产品的源代码，它们将被编译并组装成一个 JAR 文件。test 源集包含你的单元测试的源代码，它们将被编译并使用 JUnit 或 TestNG 来执行。

任务

Java 插件向你的项目添加了大量的任务，如下所示。

表23.1. Java 插件-任务

对于每个你添加到该项目中的源集，Java 插件将添加以下的编译任务：

表23.2. Java 插件-源集任务

Java 插件还增加了大量的任务构成该项目的生命周期：

表23.3. Java 插件-生命周期任务

uploadConfigurationName 使用配置 ConfigurationName 上传构件的任务。 Upload 组装并上传指定配置的构件。该任务由 Base 插件添加，并由 Java 插件隐式实现。 下图显示了这些任务之间的关系。

图23、1. Java 插件 – 任务

Java 插件 – 任务

项目布局

Java 插件会假定如下所示的项目布局。这些目录都不需要一定存在，或者是里面有什么内容。Java 插件将会进行编译，不管它发现什么，并处理缺少的任何东西。

表23.4. Java 插件-默认项目布局

更改项目布局

你可以通过配置适当的源集，来配置项目的布局。这一点将在以下各节中详细讨论。这里是如何更改 main Java 和资源源目录的一个简短的例子。

自定义 Java 源代码布局

build.gradle

sourceSets {
    main {
        java {
            srcDir 'src/java'
        }
        resources {
            srcDir 'src/resources'
        }
    }
}  

依赖管理

Java 插件向项目添加了许多依赖配置，如下图所示。它对一些任务指定了这些配置，如 compileJava 和 test。

表23、5. Java插件 – 依赖配置

图23、2. Java 插件 – 依赖配置

Java 插件 – 依赖配置

对于每个你添加到项目中的源集，Java 插件都会添加以下的依赖配置：

表23、6. Java 插件 – 源集依赖配置

常规属性

Java 插件向项目添加了许多常规属性，如下图所示。您可以在构建脚本中使用这些属性，就像它们是 project 对象的属性一样。

表23、7. Java 插件 – 目录属性

表23.8. Java 插件 – 其他属性

这些属性由 JavaPluginConvention， BasePluginConvention 和 ReportingBasePluginConvention 这些类型的常规对象提供。

使用源集

你可以使用 sourceSets 属性访问项目的源集。这是项目的源集的容器，它的类型是 SourceSetContainer。除此之后，还有一个 sourceSets {}的脚本块，可以传入一个闭包来配置源集容器。源集容器的使用方式几乎与其他容器一样，例如 tasks。

访问源集

build.gradle

// Various ways to access the main source set
println sourceSets.main.output.classesDir
println sourceSets['main'].output.classesDir
sourceSets {
    println main.output.classesDir
}
sourceSets {
    main {
        println output.classesDir
    }
}
// Iterate over the source sets
sourceSets.all {
    println name
}  

要配置一个现有的源集，你只需使用上面的其中一种访问方法来设置源集的属性。这些属性将在下文中进行介绍。下面是一个配置 main 的 Java 和资源目录的例子：

配置源集的源代码目录

build.gradle

sourceSets {
    main {
        java {
            srcDir 'src/java'
        }
        resources {
            srcDir 'src/resources'
        }
    }
}  

源集属性

下表列出了一些重要的源集属性。你可以在 SourceSet 的 API 文档中查看更多的详细信息。

表23.9. Java 插件 – 源集属性

定义新的源集

要定义一个新的源集，你只需在 sourceSets {}块中引用它。下面是一个示例：

定义一个源集

build.gradle

sourceSets {
    intTest
}  

当您定义一个新的源集时，Java 插件会为该源集添加一些依赖配置，如表 23.6，“Java 插件 – 源集依赖项配置”所示。你可以使用这些配置来定义源集的编译和运行时的依赖。

定义源集依赖

build.gradle

sourceSets {
    intTest
}
dependencies {
    intTestCompile 'junit:junit:4.11'
    intTestRuntime 'org.ow2.asm:asm-all:4.0'
}  

Java 插件还添加了大量的任务，用于组装源集的类，如表 23.2，“Java 插件 – 源设置任务”所示。例如，对于一个被叫做 intTest 的源集，你可以运行 gradle intTestClasses 来编译 int 测试类。

编译源集

gradle intTestClasses的输出结果

> gradle intTestClasses
:compileIntTestJava
:processIntTestResources
:intTestClasses
BUILD SUCCESSFUL
Total time: 1 secs  

一些源集的范例

添加一个包含了源集的类的 JAR 包

示例 23.8. 为一个源集装配一个JAR文件

build.gradle

task intTestJar(type: Jar) {
    from sourceSets.intTest.output
}  

为一个源集生成 Javadoc：

示例 23.9. 为一个源集生成 Javadoc：

build.gradle

task intTestJavadoc(type: Javadoc) {
    source sourceSets.intTest.allJava
}  

添加一个测试套件以运行一个源集里的测试

示例 23.10. 运行源集里的测试

build.gradle

task intTest(type: Test) {
    testClassesDir = sourceSets.intTest.output.classesDir
    classpath = sourceSets.intTest.runtimeClasspath
}  

Javadoc

Javadoc 任务是 Javadoc 的一个实例。它支持核心的 javadoc 参数选项，以及在 Javadoc 可执行文件的参考文档中描述的标准 doclet 参数选项。对于支持的 Javadoc 参数选项的完整列表，请参考下面的类的 API 文档： CoreJavadocOptions 和StandardJavadocDocletOptions。

表23.10. Java 插件 – Javadoc 属性

清理

clean 任务是 Delete 的一个实例。它只是删除由其 dir 属性表示的目录。

表23.11. Java 插件 – Clean 性能

资源

Java 插件使用 Copy 任务进行资源的处理。它为该 project 里的每个源集添加一个实例。你可以在16.6章节，“复制文件”中找到关于 copy 任务的更多信息。

表23.12. Java 插件-ProcessResources 属性

CompileJava

Java 插件为该 project 里的每个源集添加一个 JavaCompile 实例。一些最常见的配置选项如下所示。

表23.13. Java 插件- Compile 属性

compile 任务委派了 Ant 的 javac 任务。将 options.useAnt 设置为 false 将绕过 Ant 任务，而激活 Gradle 的直接编译器集成。在未来的 Gradle 版本中，将把它作为默认设置。

默认情况下，Java 编译器在 Gradle 过程中运行。将 options.fork 设置为 true 将会使编译出现在一个单独的进程中。在 Ant javac 任务中，这意味着将会为每一个 compile 任务fork 一个新的进程，而这将会使编译变慢。相反，Gradle 的直接编译器集成 （见上文） 将尽可能多地重用相同的编译器进程。在这两种情况下，使用 options.forkOptions 指定的所有fork 选项都将得到重视。

Test

test 任务是 Test 的一个实例。它会自动检测和执行 test 源集中的所有单元测试。测试执行完成后，它还会生成一份报告。同时支持 JUnit 和 TestNG。可以看一看Test的完整的 API。

测试执行

测试在单独的 JVM 中执行，与 main 构建进程隔离。Test 任务的 API 可以让你控制什么时候开始。

有大量的属性用于控制测试进程的启动。这包括系统属性、 JVM 参数和使用的 Java 可执行文件。

你可以指定是否要并行运行你的测试。Gradle 通过同时运行多个测试进程来提供并行测试的执行。每个测试进程会依次执行一个单一的测试，所以你一般不需要对你的测试做任何的配置来利用这一点。 MaxParallelForks 属性指定在给定的时间可以运行的测试进程的最大数。它的默认值是 1，也就是说，不并行执行测试。

测试进程程会为其将 org.gradle.test.worker 系统属性设置为一个唯一标识符，这个标识符可以用于文件名称或其他资源标识符。

你可以指定在执行了一定数量的测试类之后，重启那个测试进程。这是一个很有用的替代方案，让你的测试进程可以有很大的堆内存。forkEvery 属性指定了要在测试进程中执行的测试类的最大数。默认是每个测试进程中执行的测试数量不限。

该任务有一个 ignoreFailures 属性，用以控制测试失败时的行为。test 会始终执行它检测到的每一个测试。如果 ignoreFailures 为 false，并且有测试不通过，那它会停止继续构建。IgnoreFailures 的默认值为 false。

testLogging 属性可以配置哪些测试事件需要记录，并且使用什么样的日志级别。默认情况下，对于每个失败的测试都只会打印一个简洁的消息。请参阅 TestLoggingContainer，查看如何把你的测试日志打印调整为你的偏好设置。

调试

test 任务提供了一个 Test.getDebug()属性，可以设置为启动，使 JVM 在执行测试之前，等待一个 debugger 连接到它的 5005 端口上。

这也可以在调用时通过–debug-vm task 选项进行启用。

测试过滤

从Gradle 1.10 开始，可以根据测试的名称模式，只包含指定的测试。过滤，相对于测试类的包含或排除，是一个不同的机制。它将在接下来的段落中进行描述（-Dtest.single， test.include 和 friends）。后者基于文件，比如测试实现类的物理位置。file-level 的测试选择不支持的很多有趣的情况，都可以用 test-level 过滤来做到。以下这些场景中，有一些 Gradle 现在就可以处理，而有一些则将在未来得到实现：

• 在指定的测试的方法级别上进行过滤；执行单个测试方法
• 基于自定义注解（以后实现）进行过滤
• 基于测试层次结构进行过滤 ；执行所有继承了某一基类（以后实现） 的测试
• 基于一些自定义的运行时的规则进行过滤，例如某个系统属性或一些静态的特定值（以后实现）

测试过滤功能具有以下的特征：

• 支持完整的限定类名称或完整的限定的方法名称，例如“org.gradle.SomeTest”、“org.gradle.SomeTest.someMethod”
• 通配符 “*” 支付匹配任何字符
• 提供了“–tests”的命令行选项，以方便地设置测试过滤器。这对“单一测试方法的执行”的经典用例特别有用。当使用该命令行选项选项时，在构建脚本中声明的列入过滤器的测试将会被忽略。
• Gradle 尽最大努力对有着特定的测试框架 API 的局限的测试进行过滤。一些高级的、 综合的测试可能不完全符合过滤条件。然而，绝大多数的测试和用例都会被很好地处理。
• 测试过滤将会取代基于文件的测试选择。后者可能在将来会被完全地取代掉。我们将会继续改进测试过滤的 API，并添加更多种类的过滤器。

在构建脚本中过滤测试

build.gradle

test {
    filter {
        //include specific method in any of the tests
        includeTestsMatching "*UiCheck"
        //include all tests from package
        includeTestsMatching "org.gradle.internal.*"
        //include all integration tests
        includeTestsMatching "*IntegTest"
    }
}  

有关更多的详细信息和示例，请参阅 TestFilter 的文档。

使用命令行选项的一些示例：

• gradle test –tests org.gradle.SomeTest.someSpecificFeature
• gradle test –tests *SomeTest.someSpecificFeature
• gradle test –tests *SomeSpecificTest
• gradle test –tests all.in.specific.package*
• gradle test –tests *IntegTest
• gradle test –tests IntegTestui*
• gradle someTestTask –tests UiTest someOtherTestTask –tests WebTest*ui

通过系统属性执行单一的测试

这种机制已经被上述的“测试过滤”所取代。 设置一个 taskName.single = testNamePattern 的系统属性将会只执行匹配 testNamePattern 的那些测试。这个 taskName 可以是一个完整的多项目路径，比如“sub1:sub2:test”，或者仅是一个任务名称。testNamePattern 将用于形成一个“*/testNamePattern.class” 的包含模式。如果这个模式无法找到任何测试，那么将会抛出一个异常。这是为了使你不会误以为测试通过。如果执行了一个以上的子项目的测试，该模式会被应用于每一个子项目中。如果在一个特定的子项目中，找不到测试用例，那么将会抛出异常。在这种情况下你可以使用路径标记法的模式，这样该模式就会只应用于特定的子项目的测试任务中。或者你可以指定要执行的任务的完整限定名称。你还可以指定多个模式。示例：

• gradle -Dtest.single=ThisUniquelyNamedTest test
• gradle -Dtest.single=a/b/ test
• gradle -DintegTest.single=*IntegrationTest integTest
• gradle -Dtest.single=:proj1:test:Customer build
• gradle -DintegTest.single=c/d/ :proj1:integTest

测试检测

Test 任务通过检查编译过的测试类来检测哪些类是测试类。默认情况下它会扫描所有的.class 文件。您可以设置自定义的 includes 或 excludes，这样就只有这些类才会被扫描。根据所使用的测试框架 （JUnit 或 TestNG），会使用不同的标准进行测试类的检测。

当使用JUnit 时，我们扫描 JUnit 3 和 4 的测试类。如果满足以下的任何一个条件，这个类就被认为是一个 JUnit 测试类：

• 类或超类继承自 TestCase 或 GroovyTestCase
• 类或超类使用了 @RunWith 进行注解
• 类或超类含有一个带 @Test 注解的方法

当使用TestNG 时，我们扫描所有带有 @Test 注解的方法。

请注意，抽象类不会被执行。Gradle 还将扫描测试类路径中的 jar 文件里的继承树。

如果你不想要使用测试类检测，可以通过设置 scanForTestClasses 为 false 来禁用它。这将使test任务只使用 includes / excludes 来找到测试类。如果 scanForTestClasses 为disabled，并且没有指定 include 或 exclude 模式，则使用各自的默认值。对于 include 的默认值是 “/*Tests.class”， “**/*Test.class”，而对于exclude它的默认值是 “/Abstract*.class”。

测试分组

JUnit 和 TestNG 可以对测试方法进行复杂的分组。

为对Junit 测试类和方法进行分组，JUnit 4.8 引入了类别的概念。test 任务可以实现一个规范，让你 include 和 exclude 想要的 JUnit 类别。

JUnit 类别

build.gradle

test {
    useJUnit {
        includeCategories 'org.gradle.junit.CategoryA'
        excludeCategories 'org.gradle.junit.CategoryB'
    }
}  

TestNG 框架有一个非常相似的概念。在 TestNG 中你可以指定不同的测试组。应从测试执行中 include 或 exclude 的测试组，可以在 test 任务中配置。

对TestNG 测试分组

build.gradle

test {
    useTestNG {
        excludeGroups 'integrationTests'
        includeGroups 'unitTests'
    }
}  

测试报告

test 任务默认情况下会生成以下结果。

• 一个 HTML 测试报告。
• 与 Ant Junit report 任务兼容的 XML 格式的结果。这种格式可以被许多工具所支持，比如CI服务器。
• 有效二进制格式的结果。这个任务会从这些二进制结果生成其他的结果。

您可以使用 Test.setTestReport()方法来禁用 HTML 测试报告。目前不能禁用其他的结果。

这里还有一个独立的 TestReport 任务类型，它可以从一个或多个 Test 任务实例生成的二进制结果中生成 HTML 测试报告。要使用这个任务类型，你需要定义一个 destinationDir 和要包含到报告的测试结果。这里是一个范例，从子项目的单元测试中生成一个联合报告：

为多个子项目创建一个单元测试报告

build.gradle

subprojects {
    apply plugin: 'java'

    // Disable the test report for the individual test task
    test {
        reports.html.enabled = false
    }
}
task testReport(type: TestReport) {
    destinationDir = file("$buildDir/reports/allTests")
    // Include the results from the test task in all subprojects
    reportOn subprojects*.test
}  

你应该注意到，TestReport 类型组合了多个测试任务的结果，并且需要聚合各个测试类的结果。这意味着，如果一个给定的测试类被多个 test 任务所执行，那么测试报告将包括那个类的所有执行结果，但它难以区分那个类的每次执行和它们的输出。

TestNG 参数化方法和报告

TestNG 支持参数化测试方法，允许一个特定的测试方法使用不同的输入执行多次。Gradle 会在这个方法的执行报告中包含进它的参数值。

给定一个带有两个参数，名为 aParameterizedTestMethod 参数化测试方法，它将使用名称这个名称进行报告 ：aParameterizedTestMethod(toStringValueOfParam1, toStringValueOfParam2)。这使得在特定的迭代过程，很容易确定参数值。

常规值

表23.14. Java 插件 – test 属性

Jar

Jar任务创建一个包含类文件和项目资源的 JAR 文件。JAR 文件在 archives 依赖配置中被声明为一个构件。这意味着这个 JAR 文件被包含在一个依赖它的项目的类路径中。如果你把你的项目上传到仓库，这个 JAR 文件会被声明为依赖描述符的一部分。你可以在第16.8节，“创建档案”和第51章， 发布 artifact 中了解如何使用 archives 和配置 artifact。

Manifest

每个jar 或 war 对象都有一个单独的 Manifest 实例的 manifest 属性。当生成 archive 时，相应的 MANIFEST.MF 文件也会被写入进去。

自定义的 MANIFEST.MF

build.gradle

jar {
    manifest {
        attributes("Implementation-Title": "Gradle", "Implementation-Version": version)
    }
}  

您可以创建一个单独的 Manifest 实例。它可以用于共享两个 jar 包的 manifest 信息。

创建一个 manifest 对象。

build.gradle

ext.sharedManifest = manifest {
    attributes("Implementation-Title": "Gradle", "Implementation-Version": version)
}
task fooJar(type: Jar) {
    manifest = project.manifest {
        from sharedManifest
    }
}  

你可以把其他的 manifest 合并到任何一个 Manifest 对象中。其他的 manifest 可能使用文件路径来描述，像上面的例子，使用对另一个 Manifest 对象的引用。

指定 archive 的单独 MANIFEST.MF

build.gradle

task barJar(type: Jar) {
    manifest {
        attributes key1: 'value1'
        from sharedManifest, 'src/config/basemanifest.txt'
        from('src/config/javabasemanifest.txt', 'src/config/libbasemanifest.txt') {
            eachEntry { details ->
                if (details.baseValue != details.mergeValue) {
                    details.value = baseValue
                }
                if (details.key == 'foo') {
                    details.exclude()
                }
            }
        }
    }
}  

Manifest 会根据在 from 语句中所声明的顺序进行合并。如果基本的 manifest 和要合并的 manifest 都定义了同一个 key 的值，那么默认情况下会采用要合并的 manifest 的值。你可以通过添加 eachEntry action 来完全自定义合并行为，它可以让你对每一项生成的 manifest 访问它的一个 ManifestMergeDetails 实例。这个合并操作不会在 from 语句中就马上被触发。它是懒执行的，不管是对于生成一个 jar 包，还是调用了 writeTo 或者 effectiveManifest

你可以很轻松地把一个 manifest 写入磁盘中。

指定 archive 的单独 MANIFEST.MF

build.gradle

jar.manifest.writeTo("$buildDir/mymanifest.mf")