This page documents JavaConventions, the class in buildSrc responsible for configuring every Java subproject in the Spring Boot build. It covers Java toolchain requirements, compiler flags, Checkstyle/format integration, Javadoc generation, test execution settings, JAR manifest population, dependency management wiring, prohibited dependency checks, and AOT/Spring factories file validation.
For the parent class that invokes JavaConventions alongside other convention classes, see ConventionsPlugin System. For Kotlin-specific conventions, see Checkstyle and Kotlin Conventions. For Maven publication conventions applied alongside Java conventions, see MavenPublishingConventions.
JavaConventions is instantiated and called from ConventionsPlugin.apply(), passing it a SystemRequirementsExtension reference. It is the largest and most impactful convention class in buildSrc.
Diagram: ConventionsPlugin delegation to JavaConventions
Sources: buildSrc/src/main/java/org/springframework/boot/build/ConventionsPlugin.java42-59 buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java148-163
JavaConventions declares two version constants used throughout the build system:
| Constant | Value | Meaning |
|---|---|---|
BUILD_JAVA_VERSION | 25 | Minimum JDK version required to compile the project |
RUNTIME_JAVA_VERSION | 17 | Java release target for all compiled .class files |
The assertCompatible method runs as a doFirst action on every JavaCompile task and throws a GradleException if the active JDK is older than BUILD_JAVA_VERSION. The compiler --release flag is set to RUNTIME_JAVA_VERSION (17), ensuring that compiled bytecode is compatible with Java 17 runtimes even when built on a newer JDK.
EclipseConventions also reads RUNTIME_JAVA_VERSION to set the Eclipse JDT source/target compatibility.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java138-141 buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java275-287 buildSrc/src/main/java/org/springframework/boot/build/EclipseConventions.java85-88
configureJavaConventions)All JavaCompile tasks in every Java subproject receive the following configuration:
| Setting | Value |
|---|---|
| Encoding | UTF-8 |
--release | 17 (RUNTIME_JAVA_VERSION) |
-parameters | Preserves method parameter names at runtime |
-Werror | Treats all compiler warnings as errors |
-Xlint:unchecked | Warns on unchecked casts |
-Xlint:deprecation | Warns on deprecated API use |
-Xlint:rawtypes | Warns on raw generic type use |
-Xlint:varargs | Warns on unsafe varargs |
Compiler arguments are accumulated into a LinkedHashSet to avoid duplicates and then set back as a list.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java263-273
configureSpringJavaFormat)Diagram: Code quality tool application flow
The method:
SpringJavaFormatPlugin — adds Format and CheckFormat tasks to the project.Format tasks.CheckstylePlugin.checkstyleToolVersion from project properties and sets it on CheckstyleExtension.config/checkstyle/ in the root project.com.puppycrawl.tools:checkstyle and io.spring.javaformat:spring-javaformat-checkstyle to the checkstyle configuration.CheckFormat and Checkstyle tasks. A source is considered generated if its path contains /generated/sources/ or /generated-source/.Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java289-314
configureJavadocConventions)All Javadoc tasks receive:
| Option | Value | Notes |
|---|---|---|
-source | 17 | Matches RUNTIME_JAVA_VERSION |
-encoding | UTF-8 | |
-Xdoclint:none | (valueless) | Suppresses all doclint checks |
-quiet | (valueless) | Reduces output verbosity |
--no-fonts | (valueless) | Applied only when task name does not contain aggregated |
The --no-fonts flag is excluded from aggregated Javadoc tasks (such as the one used for published documentation) to preserve default font rendering.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java246-261
configureTestConventions)Diagram: Test task configuration and ordering
Controlled via the Develocity DevelocityTestConfiguration extension on each test task:
| Environment | maxRetries | failOnPassedAfterRetry |
|---|---|---|
CI=true | 3 | false |
| local | 0 | false |
The isCi() method reads the CI environment variable.
If ENABLE_PREDICTIVE_TEST_SELECTION=true, PredictiveTestSelectionConfiguration.enabled is set to true via convention (not overriding explicit values).
When the JavaPlugin is present, org.junit.platform:junit-platform-launcher is automatically added to testRuntimeOnly. Version is managed by the platform BOM.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java207-244
configureJarManifestConventions)Every Jar task produced in a Java subproject receives legal files and a standardized manifest.
A task named extractLegalResources (type ExtractResources) is registered. It reads LICENSE.txt and NOTICE.txt from the org.springframework.boot.build.legal classpath package inside buildSrc, substitutes the ${version} placeholder in NOTICE.txt, and writes the files to build/legal/. These files are then added under META-INF/ in every Jar task via metaInf { from(extractLegalResources) }.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java165-194 buildSrc/src/main/java/org/springframework/boot/build/ExtractResources.java44-75 buildSrc/src/main/resources/org/springframework/boot/build/legal/NOTICE.txt1-6
| Attribute | Value |
|---|---|
Automatic-Module-Name | Project name with - replaced by . |
Build-Jdk-Spec | systemRequirements.java.version (used by buildpacks) |
Built-By | "Spring" |
Implementation-Title | Project description, or "Source for <name>" / "Javadoc for <name>" for source/javadoc jars |
Implementation-Version | Project version |
Implementation-Title is determined by determineImplementationTitle(), which checks whether the Jar task name appears in the set of known source jar or javadoc jar task names.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java165-205
configureDependencyManagement)Diagram: dependencyManagement configuration wiring
A new dependencyManagement configuration is created with visible=false, canBeConsumed=false, canBeResolved=false. All configurations whose names end in Classpath (excluding any containing dokka) and the annotationProcessor configuration extend from it. The spring-boot-internal-dependencies project is added as an enforcedPlatform, providing managed versions for all dependencies. If OptionalDependenciesPlugin is present, the optional configuration also extends from dependencyManagement.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java316-337
configureToolchain)Applies ToolchainPlugin to the project. The toolchain plugin provides the mechanism to select a specific JDK version at build time using Gradle's Java toolchain support. The toolchainVersion property (set in gradle.properties or on the command line) influences which JDK is selected for compilation.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java339-341
configureProhibitedDependencyChecks)For every source set in the project, two CheckClasspathForProhibitedDependencies tasks are registered — one for the compile classpath and one for the runtime classpath. The tasks are named following the pattern check<ConfigurationName>ForProhibitedDependencies (e.g., checkCompileClasspathForProhibitedDependencies). Each task is wired into the check lifecycle task.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java343-363
configureFactoriesFilesChecks)For the main source set only, two additional check tasks are registered:
| Task | Type | Validates |
|---|---|---|
checkAotFactories | CheckAotFactories | META-INF/spring/aot.factories |
checkSpringFactories | CheckSpringFactories | META-INF/spring.factories |
Both tasks are added as dependencies of the check task. They receive the main source set's resources as their source and the compiled classes directory as their classpath.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java365-385
configureNullability)Applies NullabilityPlugin (from io.spring.gradle.nullability). If the nullAwayVersion and errorProneVersion properties are present in the project (set in gradle.properties), they are forwarded to the NullabilityPluginExtension. This enables NullAway and Error Prone-based null safety analysis during compilation.
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java387-398
Diagram: All tasks and configurations applied by JavaConventions
Sources: buildSrc/src/main/java/org/springframework/boot/build/JavaConventions.java148-163
ConventionsPluginTests in buildSrc/src/test/java/org/springframework/boot/build/ConventionsPluginTests.java uses GradleRunner (Gradle TestKit) to verify the outcomes of JavaConventions configuration. The key test cases are:
| Test | What it verifies |
|---|---|
jarIncludesLegalFiles | META-INF/LICENSE.txt, META-INF/NOTICE.txt present; all five manifest attributes correct |
sourceJarIsBuilt | Sources JAR built with Implementation-Title = "Source for <name>" |
javadocJarIsBuilt | Javadoc JAR built with Implementation-Title = "Javadoc for <name>" |
testRetryIsConfiguredWithThreeRetriesOnCI | maxRetries=3, failOnPassedAfterRetry=false when CI=true |
testRetryIsConfiguredWithZeroRetriesLocally | maxRetries=0 when CI is not true |
Each test creates a minimal project with settings.gradle that includes :platform:spring-boot-internal-dependencies as a sibling, applies the java and org.springframework.boot.conventions plugins, and runs the build via GradleRunner.
Sources: buildSrc/src/test/java/org/springframework/boot/build/ConventionsPluginTests.java47-238
Refresh this wiki