We have now already learned that the Java plugin adds tasks and source sets to our Gradle project; however, we also get a lot of new properties that we can use. Custom properties of a plugin are set in a Convention object of type org.gradle.api.plugins.Convention. A Convention object is used by a plugin to expose properties and methods that we can use in our project. The Convention object of the plugin is added to the convention property of a project. The convention property of a Gradle project is a container for all the Convention objects from the plugins.

We can access the properties from the plugin's Convention object directly as project properties, or we can specify a complete path to the Convention object of the plugin, to get to a property or invoke a method.

For example, the sourceSets property is a property of the Convention object of the Java plugin. With the following task, showConvention, we see the different ways we have to access that property:

task showConvention << {
    println sourceSets.main.name
    println project.sourceSets.main.name
    println project.convention.plugins.java.sourceSets.main.name
}

To see all the properties available for us, we must invoke the properties task from the command line. The following output shows part of the output from the properties task:

$ gradle properties
...
targetCompatibility: 1.5
test: task ':test'
testClasses: task ':testClasses'
testReportDir: /chapter4/sample/build/reports/tests
testReportDirName: tests
testResultsDir: /chapter4/sample/build/test-results
testResultsDirName: test-results
version: unspecified
...

If we look through the list, we see a lot of properties that we can use to redefine the directories where output files of the compile or test tasks are stored. The following table shows the directory properties:

The Java plugin also adds other properties to our project. These properties can be used to set the source and target compatibility of the Java version for compiling the Java source files, or to set the base filename for the generated JAR files.

The following table shows the convention properties of the Java plugin:

In our example project, we already saw that the generated JAR file was named after the project name, but with the archivesBaseName property, we can change that. We can also change the source compatibility to Java 6 for our project. Finally, we can also change the manifest that is used for the generated JAR file. The following build file reflects all the changes:

apply plugin: 'java'

archivesBaseName = 'gradle-sample'
version = '1.0'

sourceCompatibility = JavaVersion.VERSION_1_6  // Or '1.6' or 6

manifest = manifest {
    attributes(
        'Implementation-Version' : version,
        'Implementation-Title' : 'Gradle Sample'
    )
}

// Need to explicitly set manifest on jar task,
// but should be automatic.
jar.manifest.from manifest
...

If we now invoke the assemble task to create our JAR file and look into the build/libs directory, we can see that the JAR file is now named gradle-sample-1.0.jar:

$ gradle assemble
:compileApiJava
:processApiResources
:apiClasses
:compileJava
:processResources
:classes
:jar
:assemble

BUILD SUCCESSFUL

Total time: 4.022 secs
$ ls build/libs
gradle-sample-1.0.jar

If we run the same task with the command-line option --info to set the info log level, we see in the output that the Java 6 compiler is used:

$ gradle --info cleanCompileJava assemble
...
Compiling with JDK 6 Java compiler API.
...

To see the contents of the generated manifest file, we first extract the file from the JAR file and then look at the contents:

$ jar xvf build/libs/gradle-sample-1.0.jar
  inflated: META-INF/MANIFEST.MF
$ cat META-INF/MANIFEST.MF
Manifest-Version: 1.0
Implementation-Version: 1.0
Implementation-Title: Gradle Sample