Chapter 18. The Java Plugin

The Java plugin introduces the concept of a source set. A source set is a group of source files which are compiled and executed together. These source files may include Java source files and resource files. Other plugins add the ability to include Groovy and Scala source files in a source set. A source set has an associated compile classpath, and runtime classpath.

You might use a source set to define an integration test suite, or for the API classes of your project, or to separate source which needs to be compiled against different Java versions.

The Java plugin defines two standard source sets, called main and test. The main source set contains your production source code, which is compiled and assembled into a JAR file. The test source set contains your unit test source code, which is compiled and executed using JUnit or TestNG.

The Java plugin adds a number of tasks to your project, as shown below.

For each source set you add to the project, the Java plugin adds the following compilation tasks:

The Java plugin also adds a number of tasks which form a lifecycle for the project:

The following diagram shows the relationships between these tasks.

Figure 18.1. Java plugin - tasks

The Java plugin assumes the project layout shown below. None of these directories need exist or have anything in them. The Java plugin will compile whatever it finds, and handles anything which is missing.

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

The Java plugin adds a number of dependency configurations to your project, as shown below. It assigns those configurations to tasks such as compileJava and test. To learn more about configurations see Section 28.3.1, “Configurations” and Section 29.2, “Artifacts and configurations”. Note also that transitive dependencies are disabled by default for the compile configuration. This can be overridden using:

configurations.compile.transitive = true

Figure 18.2. Java plugin - dependency configurations

The Java plugin adds a number of convention properties to the project, shown below. You can use these properties in your build script as though they were properties of the project object (see Section 17.2, “Using the convention object”).

These properties are provided by convention objects of type JavaPluginConvention , BasePluginConvention and ReportingBasePluginConvention .

You can access the source sets of a project using the sourceSets property. This is a container for the project's source sets, of type SourceSetContainer . There is also a sourceSets() method, which you can pass a closure to which configures the source set container. The source set container works pretty much the same way as other containers, such as tasks.

// Various ways to access the main source set
println sourceSets.main.classesDir
println sourceSets['main'].classesDir
sourceSets {
    println main.classesDir
}
sourceSets {
    main {
        println classesDir
    }
}

// Iterate over the source sets
sourceSets.each {SourceSet set ->
    println set.name
}

To configure an existing source set, you simply use one of the above access methods to set the properties of the source set. The properties are described below. Here is an example which configures the main Java and resources directories:

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

To define a new source set, you simply reference it in the sourceSets { } block. When you define a source set, the Java plugin adds a number of tasks which assemble the classes for the source set, as shown in Table 18.2, “Java plugin - source set tasks”. For example, if you add a source set called intTest, the Java plugin adds compileIntTestJava, processIntTestResources and intTestClasses tasks.

sourceSets {
    intTest
}

configurations {
    intTestCompile { extendsFrom compile }
    intTestRuntime { extendsFrom intTestCompile, runtime }
}

sourceSets {
    intTest {
        compileClasspath = sourceSets.main.classes + configurations.intTestCompile
        runtimeClasspath = classes + sourceSets.main.classes + configurations.intTestRuntime
    }
}

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

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

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

The javadoc task is an instance of Javadoc . It supports the core javadoc options and the options of the standard doclet described in the reference documentation of the Javadoc executable. For a complete list of supported Javadoc options consult the API documentation of the following classes: CoreJavadocOptions and StandardJavadocDocletOptions .

The clean task is an instance of Clean . It simply removes the directory denoted by its dir property.

The Java plugin uses the Copy task for resource handling. It adds an instance for each source set in the project. You can find out more about the copy task in Section 14.5, “Copying files”.

The Java plugin adds a Compile instance for each source set in the project. The compile task delegates to Ant's javac task to do the compile. You can set most of the properties of the Ant javac task.

The test task is an instance of Test . It executes all unit tests found in the test source set.

Have a look at Test for its complete API. Right now the test results are always in XML-format. The task has a stopAtFailuresOrErrors property to control the behavior when tests are failing. Test always executes all tests. It stops the build afterwards if stopAtFailuresOrErrors is true and there are failing tests or tests that have thrown an uncaught exception.

Per default the tests are run in a forked JVM and the fork is done per test. You can modify this behavior by setting forking to false or set the forkmode to once.

The Test task detects which classes are test classes by inspecting the compiled test classes. By default it scans all .class files. You can set custom includes / excludes, only those classes will be scanned. Depending on the Test framework used (JUnit / TestNG) the test class detection uses different criteria.

When using JUnit, we scan for both JUnit 3 and 4 test classes. If any of the following criteria match, the class is considered to be a JUnit test class. Extend TestCase or GroovyTestCase, Class annotated with RunWith or contain a method annotated with Test (inherited test methods are detected).

When using TestNG, we scan for methods annotated with Test (inherited test methods are detected).

Since 0.6.1 we scan up the inheritance tree into jar files on the test classpath.

In case you don't want to use the test class detection, you can disable it by setting scanForTestClasses to false. This will make the test task only use the includes / excludes to find test classes. If scanForTestClasses is disabled and no include or exclude patterns are specified, the respective defaults are used. For include this is "**/*Tests.class", "**/*Test.class" and the for exclude it is "**/Abstract*.class".

Both JUnit and TestNG are supported through their Ant tasks.

Regarding TestNG reporting, when the test report is disabled the default TestNG listeners are disabled (options.useDefaultListeners is set to false).

The jar task creates a JAR file containing the class files and resources of the project. The JAR file is declared as an artifact in the archives dependency configuration. This means that the JAR is available in the classpath of a dependent project. If you upload your project into a repository, this JAR is declared as part of the dependency descriptor. To learn more about how to work with archives and artifact configurations see Chapter 29, Artifact Management.

If you come from Maven you can have only one library JAR per project. With Gradle you can have as many as you want. You can also add WAR, ZIP and TAR archives to your project. They are all added the same way, so let's look at how you add a ZIP file.

usePlugin 'java'
version = 1.0

task myZip(type: Zip) {
    fileSet(dir: 'somedir')
}

println myZip.archiveName

> gradle -q myZip
zipProject-1.0.zip

This adds a Zip archive task with the name myZip which produces ZIP file zipProject-1.0.zip. It is important to distinguish between the name of the archive task and the name of the archive generated by the archive task. The name of the generated archive file is by default the name of the project with the project version appended. The default name for archives can be changed with the archivesBaseName project property. The name of the archive can also be changed at any time later on.

There are a number of properties which you can set on an archive task. You can, for example, change the name of the archive:

usePlugin 'java'
version = 1.0

task myZip(type: Zip) {
    fileSet(dir: 'somedir')
    baseName = 'customName'
}

println myZip.archiveName

> gradle -q myZip
customName-1.0.zip

You can further customize the archive names:

usePlugin 'java'
archivesBaseName = 'gradle'
version = 1.0

task myZip(type: Zip) {
    appendix = 'wrapper'
    classifier = 'src'
    fileSet(dir: 'somedir')
}

println myZip.archiveName

> gradle -q myZip
gradle-wrapper-1.0-src.zip

Often you will want to publish an archive, so that it is usable from another project. This process is described in Chapter 29, Artifact Management

task zipWithFileSet(type: Zip) {
    fileSet(dir: 'contentDir') {
        include('**/*.txt')
        exclude('**/*.gif')
    }
}

task zipWithFiles(type: Zip) {
    files('path_to_file1', 'path_to_file2')
}

task zipWithZipFileSet(type: Zip) {
    zipFileSet(dir: 'contentDir') {
        include('**/*.txt')
        exclude('**/*.gif')
        prefix = 'myprefix'
    }
}

task tarWithFileSet(type: Tar) {
    tarFileSet(dir: 'contentDir') {
        include('**/*.txt')
        exclude('**/*.gif')
        uid = 'myuid'
    }
}

myZipTask.antDirective {        
   zipgroupfileset(dir: new File(rootDir, 'lib'))    
}

myZipTask.merge('path1/otherArchive1.zip', 'path2/otherArchive.tar.gz')

myZipTask.merge('path1/otherArchive1.zip', 'path2/otherArchive.tar.gz') {
    include('**/*.txt')
    exclude('**/*.gif')
    prefix = 'myprefix'
}

myZipTask.mergeGroup('path_to_dir_with_archives') {
    include('**/*.zip')
    exclude('**/*.tar.gz')
}

manifest.mainAttributes("Implementation-Title": "Gradle", "Implementation-Version": version)

manifest.mainAttributes("Implementation-Title": "Gradle", "Implementation-Version": version)
myZipTask.manifest = new GradleManifest(manifest.createManifest())
myZipTask.manifest.mainAttributes(mykey: "myvalue")

metaInf << new FileSet(someDir)

How to upload your archives is described in Chapter 29, Artifact Management.

Gradle comes with a number of tasks for generating eclipse files for your projects.