The Java plugin adds Java compilation along with testing and bundling capabilities to a project. It serves as the basis for many of the other JVM language Gradle plugins. You can find a comprehensive introduction and overview to the Java Plugin in the Building Java Projects chapter.

As indicated above, this plugin adds basic building blocks for working with JVM projects. Its feature set has been superseded by other plugins, offering more features based on your project type. Instead of applying it directly to your project, you should look into the java-library or application plugins or one of the supported alternative JVM language.

Usage

To use the Java plugin, include the following in your build script:

Example 1. Using the Java plugin
build.gradle.kts
plugins {
    java
}
build.gradle
plugins {
    id 'java'
}

Tasks

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

compileJava — JavaCompile

Depends on: All tasks which contribute to the compilation classpath, including jar tasks from projects that are on the classpath via project dependencies

Compiles production Java source files using the JDK compiler.

processResources — ProcessResources

Copies production resources into the production resources directory.

classes

Depends on: compileJava, processResources

This is an aggregate task that just depends on other tasks. Other plugins may attach additional compilation tasks to it.

compileTestJava — JavaCompile

Depends on: classes, and all tasks that contribute to the test compilation classpath

Compiles test Java source files using the JDK compiler.

processTestResources — Copy

Copies test resources into the test resources directory.

testClasses

Depends on: compileTestJava, processTestResources

This is an aggregate task that just depends on other tasks. Other plugins may attach additional test compilation tasks to it.

jar — Jar

Depends on: classes

Assembles the production JAR file, based on the classes and resources attached to the main source set.

javadoc — Javadoc

Depends on: classes

Generates API documentation for the production Java source using Javadoc.

test — Test

Depends on: testClasses, and all tasks which produce the test runtime classpath

Runs the unit tests using JUnit or TestNG.

clean — Delete

Deletes the project build directory.

cleanTaskName — Delete

Deletes files created by the specified task. For example, cleanJar will delete the JAR file created by the jar task and cleanTest will delete the test results created by the test task.

SourceSet Tasks

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

compileSourceSetJava — JavaCompile

Depends on: All tasks which contribute to the source set’s compilation classpath

Compiles the given source set’s Java source files using the JDK compiler.

processSourceSetResources — Copy

Copies the given source set’s resources into the resources directory.

sourceSetClasses — Task

Depends on: compileSourceSetJava, processSourceSetResources

Prepares the given source set’s classes and resources for packaging and execution. Some plugins may add additional compilation tasks for the source set.

Lifecycle Tasks

The Java plugin attaches some of its tasks to the lifecycle tasks defined by the Base Plugin — which the Java Plugin applies automatically — and it also adds a few other lifecycle tasks:

assemble

Depends on: jar

Aggregate task that assembles all the archives in the project. This task is added by the Base Plugin.

check

Depends on: test

Aggregate task that performs verification tasks, such as running the tests. Some plugins add their own verification tasks to check. You should also attach any custom Test tasks to this lifecycle task if you want them to execute for a full build. This task is added by the Base Plugin.

build

Depends on: check, assemble

Aggregate tasks that performs a full build of the project. This task is added by the Base Plugin.

buildNeeded

Depends on: build, and buildNeeded tasks in all projects that are dependencies in the testRuntimeClasspath configuration.

Performs a full build of the project and all projects it depends on.

buildDependents

Depends on: build, and buildDependents tasks in all projects that have this project as a dependency in their testRuntimeClasspath configurations

Performs a full build of the project and all projects which depend upon it.

buildConfigName — task rule

Depends on: all tasks that generate the artifacts attached to the named — ConfigName — configuration

Assembles the artifacts for the specified configuration. This rule is added by the Base Plugin.

The following diagram shows the relationships between these tasks.

javaPluginTasks
Figure 1. Java plugin - tasks

Project layout

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

src/main/java

Production Java source.

src/main/resources

Production resources, such as XML and properties files.

src/test/java

Test Java source.

src/test/resources

Test resources.

src/sourceSet/java

Java source for the source set named sourceSet.

src/sourceSet/resources

Resources for the source set named sourceSet.

Changing the project layout

You configure the project layout by configuring the appropriate source set. This is discussed in more detail in the following sections. Here is a brief example which changes the main Java and resource source directories.

Example 2. Custom Java source layout
build.gradle.kts
sourceSets {
    main {
        java {
            setSrcDirs(listOf("src/java"))
        }
        resources {
            setSrcDirs(listOf("src/resources"))
        }
    }
}
build.gradle
sourceSets {
    main {
        java {
            srcDirs = ['src/java']
        }
        resources {
            srcDirs = ['src/resources']
        }
    }
}

Source sets

The plugin adds the following source sets:

main

Contains the production source code of the project, which is compiled and assembled into a JAR.

test

Contains your test source code, which is compiled and executed using JUnit or TestNG. These are typically unit tests, but you can include any test in this source set as long as they all share the same compilation and runtime classpaths.

Source set properties

The following table lists some of the important properties of a source set. You can find more details in the API documentation for SourceSet.