// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[java_plugin]]
== The Java Plugin

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 Gradle plugins.


[[sec:java_usage]]
=== Usage

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

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="useJavaPlugin" dir="java/quickstart" title="Using the Java plugin">
    <sourcefile file="build.gradle" snippet="use-plugin"/>
</sample>
++++


[[sec:java_project_layout]]
=== 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.

[[javalayout]]
.Java plugin - default project layout
[cols="a,a,a", options="header"]
|===
| Directory
|
| Meaning

include::javaProjectMainLayout.adoc[]
include::javaProjectTestLayout.adoc[]
include::javaProjectGenericLayout.adoc[]
|===


[[sec:changing_java_project_layout]]
==== 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.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="customJavaSourceLayout" dir="java/customizedLayout" title="Custom Java source layout">
    <sourcefile file="build.gradle" snippet="define-main"/>
</sample>
++++

[[sec:java_source_sets]]
=== Source sets

The plugin adds the following <<sec:java_source_sets,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.

[[sec:source_set_properties]]
==== 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 api:org.gradle.api.tasks.SourceSet[].

`(read-only) String name`::
_The name of the source set, used to identify it._ Default value: Not null

`(read-only) api:org.gradle.api.tasks.SourceSetOutput[] output`::
_The output files of the source set, containing its compiled classes and resources._ Default value: Not null

`api:org.gradle.api.file.FileCollection[] output.classesDirs`::
_The directories to generate the classes of this source set into._ Default value: Not null

`File output.resourcesDir`::
_The directory to generate the resources of this source set into._ Default value: `__buildDir__/resources/__name__`

`api:org.gradle.api.file.FileCollection[] compileClasspath`::
_The classpath to use when compiling the source files of this source set._ Default value: `__sourceSet__CompileClasspath` configuration.

`api:org.gradle.api.file.FileCollection[] annotationProcessorPath`::
_The processor path to use when compiling the source files of this source set._ Default value: `__sourceSet__AnnotationProcessor` configuration.

`api:org.gradle.api.file.FileCollection[] runtimeClasspath`::
_The classpath to use when executing the classes of this source set._ Default value: `output` + `__sourceSet__RuntimeClasspath` configuration.

`(read-only) api:org.gradle.api.file.SourceDirectorySet[] java`::
_The Java source files of this source set. Contains only `.java` files found in the Java source directories, and excludes all other files._ Default value: Not null

`Set&lt;File&gt; java.srcDirs`::
_The source directories containing the Java source files of this source set._ Default value: `[__projectDir__/src/__name__/java]`. Can set using anything described in <<sec:specifying_multiple_files>>.

`File java.outputDir`::
_The directory to generate compiled Java sources into._ Default value: `__buildDir__/classes/java/__sourceSetName__`. Can set using anything described in <<sec:locating_files>>.

`(read-only) api:org.gradle.api.file.SourceDirectorySet[] resources`::
_The resources of this source set. Contains only resources, and excludes any `.java` files found in the resource source directories. Other plugins, such as the Groovy plugin, exclude additional types of files from this collection._ Default value: Not null

`Set&lt;File&gt; resources.srcDirs`::
_The source directories containing the resources of this source set._ Default value: `[__projectDir__/src/__name__/resources]`. Can set using anything described in <<sec:specifying_multiple_files>>.

`(read-only) api:org.gradle.api.file.SourceDirectorySet[] allJava`::
_All `.java` files of this source set. Some plugins, such as the Groovy plugin, add additional Java source files to this collection._ Default value: `java`

`(read-only) api:org.gradle.api.file.SourceDirectorySet[] allSource`::
_All source files of this source set. This include all resource files and all Java source files. Some plugins, such as the Groovy plugin, add additional source files to this collection._ Default value: `resources + java`

[[sec:defining_new_source_sets]]
==== Defining new source sets

See the <<sec:configuring_java_integration_tests,integration test example>> in the _Testing in Java & JVM projects_ chapter.

[[sec:some_source_set_examples]]
==== Some other simple source set examples

Adding a JAR containing the classes of a source set:

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="configureSourceSet" dir="userguide/java/sourceSets" title="Assembling a JAR for a source set">
    <sourcefile file="build.gradle" snippet="jar"/>
</sample>
++++

Generating Javadoc for a source set:

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="configureSourceSet" dir="userguide/java/sourceSets" title="Generating the Javadoc for a source set">
    <sourcefile file="build.gradle" snippet="javadoc"/>
</sample>
++++

Adding a test suite to run the tests in a source set:

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="configureSourceSet" dir="userguide/java/sourceSets" title="Running tests in a source set">
    <sourcefile file="build.gradle" snippet="test"/>
</sample>
++++

[[sec:java_tasks]]
=== Tasks

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

`compileJava(type: api:org.gradle.api.tasks.compile.JavaCompile[])`::
_Compiles production Java source files using javac._ Depends on all tasks which produce the compile classpath. This includes the `jar` task for project dependencies included in the `compile` configuration.

`processResources(type: api:org.gradle.api.tasks.Copy[])`::
_Copies production resources into the production resources directory._

`classes(type: api:org.gradle.api.Task[])`::
_Assembles the production classes and resources directories._

`compileTestJava(type: api:org.gradle.api.tasks.compile.JavaCompile[])`::
_Compiles test Java source files using javac._ Depends on `compile`, plus all tasks which produce the test compile classpath.

`processTestResources(type: api:org.gradle.api.tasks.Copy[])`::
_Copies test resources into the test resources directory._

`testClasses(type: api:org.gradle.api.Task[])`::
_Assembles the test classes and resources directories._ Depends on `compileTestJava` task and `processTestResources` task. Some plugins add additional test compilation tasks.

`jar(type: api:org.gradle.api.tasks.bundling.Jar[])`::
_Assembles the JAR file._ Depends on `compile`.

`javadoc(type: api:org.gradle.api.tasks.javadoc.Javadoc[])`::
_Generates API documentation for the production Java source, using Javadoc_. Depends on `compile`.

`test(type: api:org.gradle.api.tasks.testing.Test[])`::
_Runs the unit tests using JUnit or TestNG._ Depends on `compile`, `compileTest`, plus all tasks which produce the test runtime classpath.

`uploadArchives(type: api:org.gradle.api.tasks.Upload[])`::
_Uploads artifacts in the `archives` configuration, including the JAR file._ Depends on the tasks which produce the artifacts in the `archives` configuration, including `jar`.

`clean(type: api:org.gradle.api.tasks.Delete[])`::
_Deletes the project build directory._

`clean__TaskName__(type: api:org.gradle.api.tasks.Delete[])`::
_Deletes files created by specified task. `cleanJar` will delete the JAR file created by the `jar` task, and `cleanTest` will delete the test results created by the `test` task._

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

[[java_source_set_tasks]]
==== SourceSet Tasks

`compile__SourceSet__Java(type: api:org.gradle.api.tasks.compile.JavaCompile[])`::
_Compiles the given source set's Java source files using javac._ Depends on all tasks which produce the source set's compile classpath.

`process__SourceSet__Resources(type: api:org.gradle.api.tasks.Copy[])`::
_Copies the given source set's resources into the resources directory._

`__sourceSet__Classes(type: api:org.gradle.api.Task[])`::
_Assembles the given source set's classes and resources directories._ Depends on the `compile__SourceSet__Java` task and the `process__SourceSet__Resources` task. Some plugins add additional compilation tasks for the source set.

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

`assemble(type: api:org.gradle.api.Task[])`::
_Assembles all the archives in the project._ Depends on all archive tasks in the project, including `jar`. Some plugins add additional archive tasks to the project.

`check(type: api:org.gradle.api.Task[])`::
_Performs all verification tasks in the project._ Depends on all verification tasks in the project, including `test`. Some plugins add additional verification tasks to the project.

`build(type: api:org.gradle.api.Task[])`::
_Performs a full build of the project._ Depends on `check` and `assemble`.

`buildNeeded(type: api:org.gradle.api.Task[])`::
_Performs a full build of the project and all projects it depends on._ Depends on `build` and `buildNeeded` tasks in all project lib dependencies of the `testRuntime` configuration.

`buildDependents(type: api:org.gradle.api.Task[])`::
_Performs a full build of the project and all projects which depend on it._ Depends on `build` and `buildDependents` tasks in all projects with a project lib dependency on this project in a `testRuntime` configuration.

`build__ConfigName__(type: api:org.gradle.api.Task[])`::
_Assembles the artifacts in the specified configuration. The task is added by the Base plugin which is implicitly applied by the Java plugin._ Depends on the tasks which produce the artifacts in configuration __ConfigName__.

`upload__ConfigName__(type: api:org.gradle.api.tasks.Upload[])`::
_Assembles and uploads the artifacts in the specified configuration. The task is added by the Base plugin which is implicitly applied by the Java plugin._ Depends on the tasks which uploads the artifacts in configuration __ConfigName__.

The following diagram shows the relationships between these tasks.

++++
<figure xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Java plugin - tasks</title>
    <imageobject>
        <imagedata fileref="img/javaPluginTasks.png"/>
    </imageobject>
</figure>
++++



[[sec:java_plugin_and_dependency_management]]
=== Dependency management

The Java plugin adds a number of <<managing_dependency_configurations,dependency configurations>> to your project, as shown below. It assigns those configurations to tasks such as `compileJava` and `test`.

[[tab:configurations]]
==== Dependency configurations

[NOTE]
====

To find information on the `api` configuration, please consult the <<java_library_separation, Java Library Plugin>> reference documentation and the <<dependency_management_for_java_projects, Dependency Management Tutorial>>.

====

[.line-through]#`compile`#(Deprecated)::
_Compile time dependencies._ Superseded by `implementation`.

`implementation` extends `compile`::
_Implementation only dependencies._

`compileOnly`::
_Compile time only dependencies, not used at runtime._

`compileClasspath` extends `compile, compileOnly, implementation`::
_Compile classpath, used when compiling source._ Used by task `compileJava`.

`annotationProcessor`::
_Annotation processors used during compilation._

[.line-through]#`runtime`#(Deprecated) extends `compile`::
_Runtime dependencies._ Superseded by `runtimeOnly`.

`runtimeOnly`::
_Runtime only dependencies._

`runtimeClasspath` extends `runtimeOnly, runtime, implementation`::
_Runtime classpath contains elements of the implementation, as well as runtime only elements._

[.line-through]#`testCompile`#(Deprecated) extends `compile`::
_Additional dependencies for compiling tests._ Superseded by `testImplementation`.

`testImplementation` extends `testCompile, implementation`::
_Implementation only dependencies for tests._

`testCompileOnly`::
_Additional dependencies only for compiling tests, not used at runtime._

`testCompileClasspath` extends `testCompile, testCompileOnly, testImplementation`::
_Test compile classpath, used when compiling test sources._ Used by task `compileTestJava`.

[.line-through]#`testRuntime`#(Deprecated) extends `runtime, testCompile`::
_Additional dependencies for running tests only._ Used by task `test`. Superseded by `testRuntimeOnly`.

`testRuntimeOnly` extends `runtimeOnly`::
_Runtime only dependencies for running tests._ Used by task `test`.

`testRuntimeClasspath` extends `testRuntimeOnly, testRuntime, testImplementation`::
_Runtime classpath for running tests._

`archives`::
Artifacts (e.g. jars) produced by this project. Used by tasks `uploadArchives`.

`default` extends `runtime`::
_The default configuration used by a project dependency on this project._ Contains the artifacts and dependencies required by this project at runtime.

++++
<figure xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Java plugin - dependency configurations</title>
    <imageobject>
        <imagedata fileref="img/javaPluginConfigurations.png"/>
    </imageobject>
</figure>
++++

For each source set you add to the project, the Java plugins adds the following dependency configurations:

[[java_source_set_configurations]]
==== SourceSet dependency configurations

[.line-through]#`__sourceSet__Compile`#(Deprecated)::
_Compile time dependencies for the given source set._ Superseded by `__sourceSet__Implementation`.

`__sourceSet__Implementation` extends `__sourceSet__Compile`::
_Compile time dependencies for the given source set._ Used by `__sourceSet__CompileClasspath, __sourceSet__RuntimeClasspath`.

`__sourceSet__CompileOnly`::
_Compile time only dependencies for the given source set, not used at runtime._

`__sourceSet__CompileClasspath` extends `compile__SourceSet__Java`::
_Compile classpath, used when compiling source._ Used by `__sourceSet__Compile, __sourceSet__CompileOnly, __sourceSet__Implementation`.

`__sourceSet__AnnotationProcessor`::
_Annotation processors used during compilation of this source set._

[.line-through]#`__sourceSet__Runtime`#(Deprecated)::
_Runtime dependencies for the given source set._ Used by `__sourceSet__Compile`. Superseded by `__sourceSet__RuntimeOnly`.

`__sourceSet__RuntimeOnly`::
_Runtime only dependencies for the given source set._

`__sourceSet__RuntimeClasspath` extends `__sourceSet__RuntimeOnly, __sourceSet__Runtime, __sourceSet__Implementation`::
_Runtime classpath contains elements of the implementation, as well as runtime only elements._

[[sec:java_convention_properties]]
=== Convention properties

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.

==== Directory properties

`String reporting.baseDir`::
_The name of the directory to generate reports into, relative to the build directory._ Default value: `reports`

`(read-only) File reportsDir`::
_The directory to generate reports into._ Default value: `__buildDir__/__reporting.baseDir__`

`String testResultsDirName`::
_The name of the directory to generate test result .xml files into, relative to the build directory._ Default value: `test-results`

`(read-only) File testResultsDir`::
_The directory to generate test result .xml files into._ Default value: `__buildDir__/__testResultsDirName__`

`String testReportDirName`::
_The name of the directory to generate the test report into, relative to the reports directory._ Default value: `tests`

`(read-only) File testReportDir`::
_The directory to generate the test report into._ Default value: `__reportsDir__/testReportDirName`

`String libsDirName`::
_The name of the directory to generate libraries into, relative to the build directory._ Default value: `libs`

`(read-only) File libsDir`::
_The directory to generate libraries into._ Default value: `__buildDir__/__libsDirName__`

`String distsDirName`::
_The name of the directory to generate distributions into, relative to the build directory._ Default value: `distributions`

`(read-only) File distsDir`::
_The directory to generate distributions into._ Default value: `__buildDir__/__distsDirName__`

`String docsDirName`:
:_The name of the directory to generate documentation into, relative to the build directory._ Default value: `docs`

`(read-only) File docsDir`::
_The directory to generate documentation into._ Default value: `__buildDir__/__docsDirName__`

`String dependencyCacheDirName`::
_The name of the directory to use to cache source dependency information, relative to the build directory._ Default value: `dependency-cache`

==== Other convention properties

`(read-only) api:org.gradle.api.tasks.SourceSetContainer[] sourceSets`::
_Contains the project's source sets._ Default value: Not null api:org.gradle.api.tasks.SourceSetContainer[]

`api:org.gradle.api.JavaVersion[] sourceCompatibility`::
_Java version compatibility to use when compiling Java source._ Default value: version of the current JVM in use api:org.gradle.api.JavaVersion[]. Can also set using a String or a Number, e.g. `'1.5'` or `1.5`.

`api:org.gradle.api.JavaVersion[] targetCompatibility`::
_Java version to generate classes for._ Default value: `__sourceCompatibility__`. Can also set using a String or Number, e.g. `'1.5'` or `1.5`.

`String archivesBaseName`::
_The basename to use for archives, such as JAR or ZIP files._ Default value: `__projectName__`

`api:org.gradle.api.java.archives.Manifest[] manifest`::
_The manifest to include in all JAR files._ Default value: an empty manifest.

These properties are provided by convention objects of type api:org.gradle.api.plugins.JavaPluginConvention[], and api:org.gradle.api.plugins.BasePluginConvention[].




[[sec:javadoc]]
=== Javadoc

The `javadoc` task is an instance of api:org.gradle.api.tasks.javadoc.Javadoc[]. It supports the core Javadoc options and the options of the standard doclet described in the http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html[reference documentation] of the Javadoc executable. For a complete list of supported Javadoc options consult the API documentation of the following classes: api:org.gradle.external.javadoc.CoreJavadocOptions[] and api:org.gradle.external.javadoc.StandardJavadocDocletOptions[].

==== Javadoc properties

`api:org.gradle.api.file.FileCollection[] classpath`::
Default value: `sourceSets.main.output` + `sourceSets.main.compileClasspath`

`api:org.gradle.api.file.FileTree[] source`::
Default value: `sourceSets.main.allJava`. Can set using anything described in <<sec:specifying_multiple_files>>.

`File destinationDir`::
Default value: `__docsDir__/javadoc`

`String title`::
Default value: The name and version of the project

[[sec:clean]]
=== Clean

The `clean` task is an instance of api:org.gradle.api.tasks.Delete[]. It simply removes the directory denoted by its `dir` property.

==== Clean properties

`File dir`::
Default value: `__buildDir__`


[[sec:java_resources]]
=== Resources

The Java plugin uses the api:org.gradle.api.tasks.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 <<sec:copying_files>>.

==== ProcessResources properties

`Object srcDirs`::
Default value: `__sourceSet__.resources`. Can set using anything described in <<sec:specifying_multiple_files>>.

`File destinationDir`::
Default value: `__sourceSet__.output.resourcesDir`. Can set using anything described in <<sec:locating_files>>.


[[sec:compile]]
=== CompileJava

The Java plugin adds a api:org.gradle.api.tasks.compile.JavaCompile[] instance for each source set in the project. Some of the most common configuration options are shown below.

==== Compile properties

`api:org.gradle.api.file.FileCollection[] classpath`::
Default value: `__sourceSet__.compileClasspath`

`api:org.gradle.api.file.FileTree[] source`::
Default value: `__sourceSet__.java`. Can set using anything described in <<sec:specifying_multiple_files>>.

`File destinationDir`::
Default value: `__sourceSet__.java.outputDir`

By default, the Java compiler runs in the Gradle process. Setting `options.fork` to `true` causes compilation to occur in a separate process. In the case of the Ant javac task, this means that a new process will be forked for each compile task, which can slow down compilation. Conversely, Gradle's direct compiler integration (see above) will reuse the same compiler process as much as possible. In both cases, all fork options specified with `options.forkOptions` will be honored.

[[sec:incremental_compile]]
==== Incremental Java compilation

Starting with Gradle 2.1, it is possible to compile Java incrementally. See the api:org.gradle.api.tasks.compile.JavaCompile[] task for information on how to enable it.

The main goals for incremental compilation are:

* Make incremental builds much faster.
* Change as few output classes as possible. Classes that don't need to be recompiled remain unchanged in the output directory. An example scenario when this is really useful is using JRebel - the fewer output classes are changed the quicker the JVM can use refreshed classes.

To help you understand how incremental compilation works, the following provides a high-level overview:

* Gradle will recompile all classes _affected_ by a change.
* A class is _affected_ if it has been changed or if it depends on another affected class.
    This works no matter if the other class is defined in the same project, another project or even an external library.
* A class's dependencies are determined from type references in its bytecode.
* Since constants can be inlined, any change to a constant will result in Gradle recompiling all source files.
    For that reason, you should try to minimize the use of constants in your source code and replace them with static methods where possible.
* Since source-retention annotations are not visible in bytecode, changes to a source-retention annotation will result in full recompilation.
* You can improve incremental compilation performance by applying good software desing principles like loose coupling.
    For instance, if you put an interface between a concrete class and its dependents, the dependent classes are only recompiled when the interface changes, but not when the implementation changes.
* The class analysis is cached in the project directory, so the first build after a clean checkout can be slower. Consider turning off the incremental compiler on your build server.

[[sec:incremental_compilation_known_issues]]
===== Known issues

* If a compile task fails due to a compile error, it will do a full compilation again the next time it is invoked.

[[sec:incremental_annotation_processing]]
==== Incremental annotation processing

Starting with Gradle 4.7, the incremental compiler also supports incremental annotation processing.
Annotation processors need to opt in to this feature, otherwise they will trigger a full recompilation.

As a user you can see which annotation processors are triggering full recompilations in the `--info` log.
Incremental annotation processing will be deactivated if a custom `executable` or `javaHome` is configured on the compile task.

===== Making an annotation processor incremental

Please first have a look at <<sec:incremental_compile>>, as incremental annotation processing builds on top of it.

Gradle supports incremental compilation for two common categories of annotation processors: "isolating" and "aggregating".
Please consult the information below to decide which category fits your processor.

You can then register your processor for incremental compilation using a file in the processor's META-INF directory.
The format is one line per processor, with the fully qualified name of the processor class and its category separated by a comma.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="incrementalAnnotationProcessorRegistration" dir="java/incrementalAnnotationProcessing" title="Registering incremental annotation processors">
     <sourcefile file="processor/src/main/resources/META-INF/gradle/incremental.annotation.processors" snippet="registering-incremental-annotation-processors"/>
</sample>
++++


If your processor can only decide at runtime whether it is incremental or not, you can declare it as "dynamic" in the META-INF descriptor
and return its true type at runtime using the https://docs.oracle.com/javase/10/docs/api/javax/annotation/processing/Processor.html#getSupportedOptions()[Processor#getSupportedOptions()] method.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="dynamicAnnotationProcessorRegistration" dir="java/incrementalAnnotationProcessing" title="Registering incremental annotation processors dynamically">
     <sourcefile file="processor/src/main/java/ServiceRegistryProcessor.java" snippet="options-of-dynamic-processor"/>
</sample>
++++

Both categories have the following limitations:

* They must generate their files using the https://docs.oracle.com/javase/10/docs/api/javax/annotation/processing/Filer.html[Filer API].
    Writing files any other way will result in silent failures later on, as these files won't be cleaned up correctly.
    If your processor does this, it cannot be incremental.
* They must not depend on compiler-specific APIs like https://docs.oracle.com/javase/8/docs/jdk/api/javac/tree/com/sun/source/util/Trees.html[com.sun.source.util.Trees].
    Gradle wraps the processing APIs, so attempts to cast to compiler-specific types will fail.
    If your processor does this, it cannot be incremental, unless you have some fallback mechanism.
* If they use https://docs.oracle.com/javase/10/docs/api/javax/annotation/processing/Filer.html#getResource(javax.tools.JavaFileManager.Location,java.lang.CharSequence,java.lang.CharSequence)[Filer#getResource], Gradle will recompile all source files.
    See https://github.com/gradle/gradle/issues/4701[gradle/issues/4701]
* If they use https://docs.oracle.com/javase/10/docs/api/javax/annotation/processing/Filer.html#createResource(javax.tools.JavaFileManager.Location,java.lang.CharSequence,java.lang.CharSequence,javax.lang.model.element.Element...)[Filer#createResource], Gradle will recompile all source files.
    See https://github.com/gradle/gradle/issues/4702[gradle/issues/4702]

====== "Isolating" annotation processors
The fastest category, these look at each annotated element in isolation, creating generated files or validation messages for it.
For instance an `EntityProcessor` could create a `<TypeName>Repository` for each type annotated  with `@Entity`.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="isolatingAnnotationProcessor" dir="java/incrementalAnnotationProcessing" title="An isolated annotation processor">
     <sourcefile file="processor/src/main/java/EntityProcessor.java" snippet="isolating-annotation-processor"/>
</sample>
++++

"Isolating" processors have the following limitations:

* They must make all decisions (code generation, validation messages) for an annotated type based on information reachable from its AST.
    This means you can analyze the types' super-class, method return types, annotations etc., even transitively.
    But you cannot make decisions based on unrelated elements in the RoundEnvironment.
    Doing so will result in silent failures because too few files will be recompiled later.
    If your processor needs to make decisions based on a combination of otherwise unrelated elements, mark it as "aggregating" instead.
* They must provide exactly one originating element for each file generated with the `Filer` API.
    If zero or many originating elements are provided, Gradle will recompile all source files.


When a source file is recompiled, Gradle will recompile all files generated from it.
When a source file is deleted, the files generated from it are deleted.

====== "Aggregating" annotation processors
These can aggregate several source files into one ore more output files or validation messages.
For instance, a `ServiceRegistryProcessor` could create a single `ServiceRegistry` with one method for each type annotated with `@Service`

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="aggregatingAnnotationProcessor" dir="java/incrementalAnnotationProcessing" title="An aggregating annotation processor">
     <sourcefile file="processor/src/main/java/ServiceRegistryProcessor.java" snippet="aggregating-annotation-processor"/>
</sample>
++++

"Aggregating" processors have the following limitations:

* They can only read `CLASS` or `RUNTIME` retention annotations
* They can only read parameter names if the user passes the `-parameters` compiler argument.

Gradle will always reprocess (but not recompile) all annotated files that the processor was registered for.
Gradle will always recompile any files the processor generates.

[[sec:java_compile_avoidance]]
==== Compile avoidance

If a dependent project has changed in an https://en.wikipedia.org/wiki/Application_binary_interface[ABI]-compatible way (only its private API has changed), then Java compilation tasks will be up-to-date. This means that if project `A` depends on project `B` and a class in `B` is changed in an ABI-compatible way (typically, changing only the body of a method), then Gradle won't recompile `A`.

Some of the types of changes that do not affect the public API and are ignored:

* Changing a method body
* Changing a comment
* Adding, removing or changing private methods, fields, or inner classes
* Adding, removing or changing a resource
* Changing the name of jars or directories in the classpath
* Renaming a parameter


Compile-avoidance is deactivated if annotation processors are found on the compile classpath, because for annotation processors the implementation details matter. Annotation processors should be declared on the annotation processor path instead. Gradle 5.0 will ignore processors on the compile classpath.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="annotationProcessing" dir="java/apt" title="Declaring annotation processors">
    <sourcefile file="build.gradle" snippet="annotation-processing"/>
</sample>
++++


[[sec:java_test]]
=== Test

The `test` task is an instance of api:org.gradle.api.tasks.testing.Test[]. It automatically detects and executes all unit tests in the `test` source set. It also generates a report once test execution is complete. JUnit and TestNG are both supported. Have a look at api:org.gradle.api.tasks.testing.Test[] for the complete API.

See the _<<java_testing,Testing in Java & JVM projects>>_ chapter for more details.


[[sec:jar]]
=== Jar

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. You can learn more about how to work with archives in <<sec:archives>> and artifact configurations in <<artifact_management>>.


[[sub:manifest]]
==== Manifest

Each jar or war object has a `manifest` property with a separate instance of api:org.gradle.api.java.archives.Manifest[]. When the archive is generated, a corresponding `MANIFEST.MF` file is written into the archive.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="manifest" dir="userguide/tutorial/manifest" title="Customization of MANIFEST.MF">
    <sourcefile file="build.gradle" snippet="add-to-manifest"/>
</sample>
++++

You can create stand-alone instances of a `Manifest`. You can use that for example, to share manifest information between jars.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="manifest" dir="userguide/tutorial/manifest" title="Creating a manifest object.">
    <sourcefile file="build.gradle" snippet="custom-manifest"/>
</sample>
++++

You can merge other manifests into any `Manifest` object. The other manifests might be either described by a file path or, like in the example above, by a reference to another `Manifest` object.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="manifest" dir="userguide/tutorial/manifest" title="Separate MANIFEST.MF for a particular archive">
    <sourcefile file="build.gradle" snippet="merge"/>
</sample>
++++

Manifests are merged in the order they are declared by the `from` statement. If the base manifest and the merged manifest both define values for the same key, the merged manifest wins by default. You can fully customize the merge behavior by adding `eachEntry` actions in which you have access to a api:org.gradle.api.java.archives.ManifestMergeDetails[] instance for each entry of the resulting manifest. The merge is not immediately triggered by the from statement. It is done lazily, either when generating the jar, or by calling `writeTo` or `effectiveManifest`

You can easily write a manifest to disk.

++++
<sample xmlns:xi="http://www.w3.org/2001/XInclude" id="manifest" dir="userguide/tutorial/manifest" title="Saving a MANIFEST.MF to disk">
    <sourcefile file="build.gradle" snippet="write"/>
</sample>
++++

