Chapter 15. The Java Plugin

The Java plugin adds the tasks shown in Table 15.1, “Java Plugin - Tasks” to a project. These tasks constitute a lifecycle for Java builds.

The Java plugin assumes the project layout shown in Table 15.2, “Java Plugin - Default Project Layout”. This is configurable using the convention properties listed in the next section.

The Java plugin adds a number of configurations to your project, as shown in Section 21.3.9, “Java Plugin and Dependency Management”. To learn more about configurations see Section 21.3.1, “Configurations” and Section 22.2, “Artifacts and Configurations”

The Java plugin adds the convention properties shown in Table 15.3, “Java Plugin - Directory Properties” and Table 15.5, “Java Plugin - Other Properties”. ^[16] Gradle's conventions contain a convention for the directory hierarchy as well as conventions for the element names of the hierarchy. For example the srcDirs are relative to the srcRoot. Therefore srcDirs is a read-only property. If you want to change the name of the source dirs you need to do this via the srcDirNames property. But the paths you specify here are relative to the srcRoot. This has the advantage to make bulk changes easy. If you change srcRoot from src to source, this automatically applies to all directory properties which are relative to srcRoot. As this also introduces an inflexibility, we have additional floating dirs, which are not bound to any hierarchy (see Table 15.4, “Java Plugin - Floating Directory Properties”). For example code generation tool could make use of this, by adding a source dir which is located in the build folder.

The init task has no default action attached to it. It is meant to be a hook. You can add actions to it or associates your custom tasks with it. The Java Plugin executes this task before any other of its tasks get executed (except clean and javadoc which does not depends on init).

The javadoc task has no default association with any other task. It has no prerequisites on the actions of other tasks, as it operates on the source. We support the core javadoc options and the options of the standard doclet described in the reference documentation of the Javadoc executable.

For some of the Javadoc options we provide defaults these defaults are only used when they are not set explicitly. Except for the sourcepath and classpath option for these options you can in addition to setting your custom values also make it so that the defaults get appended to these paths with the (alwaysAppendDefaultSourcepath and alwaysAppendDefaultClasspath toggles).

For a complete list of supported Javadoc options consult the API documentation of the following classes: CoreJavadocOptions and StandardJavadocDocletOptions .

The clean task simply removes the directory denoted by its dir property. This property is mapped to the buildDir property of the project. In future releases there will be more control of what gets deleted. If you need more control now, you can use the Ant delete task.

Gradle uses the Copy task for resource handling. It has two instances, processResources and processTestResources.

The processResources task offers includes and excludes directives as well as filters. Have a look at Copy to learn about the details.

The Compile task has two instances, compile and compileTests.

The classpath of the compile task is derived from two sources. One is the configuration assigned to the task by the Java plugin. The other classpath source is the unmanagedClasspath property: a list of files denoting a jar or a directory. Usually you create your classpath via the configuration. The unmanagedClasspath is used internally by Gradle. This classpath is not shared between projects in a multi-project build. Nor is it part of a dependency descriptor if you choose to upload your library to a repository. See Section 21.3.9, “Java Plugin and Dependency Management” how the Java plugin maps the configurations to the tasks. See also the whole chapter Chapter 21, Dependency Management on dependency management.

Have a look at Compile to learn about the details. The compile task delegates to Ants javac task to do the compile. You can set most of the properties of Ants javac task.

The test task executes the unit tests which have been compiled by the compileTests task.

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

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.

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 22, 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 init
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 init
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 init
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 22, 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 22, Artifact Management.

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