Chapter 70. Building Java Libraries

The JVM component plugins rely on a software model which describes how an application is built and how components of the model relate to each other. The software model is organized around key concepts:

Additionaly, the software model allows us to better identify concepts that are traditionally merged together:

We avoid the use of the term implementation because it is too vague: both API classes and Non-API classes can have an implementation. For example, an API class can be an interface, but also a concrete class. Implementation is an overloaded term in the Java ecosystem, and often refers to a class implementing an interface. This is not the case here: a concrete class can be member of an API, but to compile against an API, you don't need the implementation of the class: all you need is the signatures.

To use the JVM component plugins, include the following in your build script:

plugins {
    id 'jvm-component'
    id 'java-lang'
}

A library is created by declaring a JvmLibrarySpec under the components element of the model:

model {
    components {
        main(JvmLibrarySpec)
    }
}

> gradle build
:compileMainJarMainJava
:processMainJarMainResources
:createMainJar
:createMainApiJar
:mainJar
:assemble
:check UP-TO-DATE
:build

BUILD SUCCESSFUL

This example creates a library named main, which will implicitly create a JavaSourceSet named java. The conventions of the legacy Java plugin are observed, where Java sources are expected to be found in src/main/java, while resources are expected to be found in src/main/resources.

Source sets represent logical groupings of source files in a library. A library can define multiple source sets and all sources will be compiled and included in the resulting binaries. When a library is added to a build, the following source sets are added by default.

It is possible to configure an existing source set through the sources container:

components {
    main {
        sources {
            java {
                // configure the "java" source set
            }
        }
    }
}

It is also possible to create an additional source set, using the JavaSourceSet type:

components {
    main {
        sources {
            mySourceSet(JavaSourceSet) {
                // configure the "mySourceSet" source set
            }
        }
    }
}

By default, when the plugins above are applied, no new tasks are added to the build. However, when libraries are defined, conventional tasks are added which build and package each binary of the library.

For each binary of a library, a single lifecycle task is created which executes all tasks associated with building the binary. To build all binaries, the standard build lifecycle task can be used.

For each source set added to a library, tasks are added to compile or process the source files for each binary.

For each binary in a library, a packaging task is added to create the jar for that binary.

Gradle provides a report that you can run from the command-line that shows details about the components and binaries that your project produces. To use this report, just run gradle components. Below is an example of running this report for one of the sample projects:

> gradle components
:components

------------------------------------------------------------
Root project
------------------------------------------------------------

JVM library 'main'
------------------

Source sets
    Java source 'main:java'
        srcDir: src/main/java
    Java source 'main:mySourceSet'
        srcDir: src/main/mySourceSet
    JVM resources 'main:resources'
        srcDir: src/main/resources

Binaries
    Jar 'mainJar'
        build using task: :mainJar
        targetPlatform: java7
        tool chain: JDK 7 (1.7)
        Jar file: build/jars/mainJar/main.jar

Note: currently not all plugins register their components, so some components may not be visible here.

BUILD SUCCESSFUL

Total time: 1 secs

The JVM component plugins support API dependencies between components. Having an API dependency means that if A depends on B, then the API of B is required to compile A. Gradle will then make sure that the dependency is built before the dependent component, and that the dependency appears on the compile classpath. API dependencies are (by nature) not transitive. Runtime (transitive) dependency management is not implemented yet.

Currently the plugin supports two kinds of dependencies:

Dependencies onto external components are not yet supported.

Dependencies are declared on a SourceSet:

model {
    components {
        core(JvmLibrarySpec)

        server(JvmLibrarySpec) {
            sources {
                java {
                    dependencies {
                        library 'core'
                    }
                }
            }
        }
    }
}

> gradle serverJar
:compileCoreJarCoreJava
:processCoreJarCoreResources
:createCoreJar
:createCoreApiJar
:coreJar
:compileServerJarServerJava
:createServerJar
:createServerApiJar
:serverJar

BUILD SUCCESSFUL

This example declares an API dependency for the java source set of the server library onto the core library of the same project. However, it is possible to create a dependency on a library in a different project as well:

client(JvmLibrarySpec) {
     sources {
         java {
             dependencies {
                 project ':util' library 'main'
             }
         }
     }
 }

> gradle clientJar
:util:compileMainJarMainJava
:util:createMainJar
:util:createMainApiJar
:util:mainJar
:compileClientJarClientJava
:createClientJar
:createClientApiJar
:clientJar

BUILD SUCCESSFUL

When the target project only defines a single library, the library selector can be omitted altogether:

dependencies {
    project ':util'
}

The DependencySpecContainer class provides a complete reference of the dependencies DSL.

The Java plugin, in addition to the target platform resolution, supports resolution of custom variants. Custom variants can be defined on custom binary types, as long as they extend JarBinarySpec. Users interested in testing this incubating feature can check out the documentation of the Variant annotation.

Often a library will contain many types that—despite having public visibility—are intended for internal use only within that library. JDK 9 will introduce Jigsaw, the reference implementation of the Java Module System, which will provide both compile-time and run-time enforcement of strong encapsulation at the library (aka: module) level. This means that packages not intended for public consumption can remain private to the library, regardless whether the types within those packages have public visibility.

Gradle anticipates the arrival of JDK 9 and the Java Module System with an approach to specifying and enforcing strong encapsulation at compile-time. However, users need not wait for the arrival of JDK 9 to use it; this feature can be used on any version of the Java platform that Gradle supports.

model {
    components {
        main(JvmLibrarySpec) {
            api {
                exports 'com.example.p1'
                exports 'com.example.p2'
            }
        }
    }
}

When gradle assemble is run, both an api jar and implementation jar will be generated.