Introduce Toolchain plugin

Nullability support requires us to compile with Java 23 or later. We
still need to be able to test against earlier versions down to our
Java 17 baseline.

This commit introduces a Toolchain plugin that is apply by convention
to all Java project. When the toolchainVersion property is
configured, the plugin configures test tasks to use that Java version.

Author: wilkinsona

gradle/plugins/conventions/build.gradle

@@ -17,6 +17,7 @@ gradlePlugin {
 }
 
 dependencies {
+	implementation(project(":toolchain"))
 	implementation("io.spring.javaformat:spring-javaformat-gradle-plugin:$javaFormatVersion")
 	implementation("io.spring.nohttp:nohttp-gradle:0.0.11")
 }

gradle/plugins/conventions/src/main/java/org/springframework/restdocs/build/conventions/JavaBasePluginConventions.java

@@ -34,6 +34,8 @@
 import org.gradle.api.tasks.compile.JavaCompile;
 import org.gradle.api.tasks.testing.Test;
 
+import org.springframework.restdocs.build.toolchain.ToolchainPlugin;
+
 /**
  * Conventions for the {@link JavaBasePlugin}.
  *
@@ -47,6 +49,7 @@ class JavaBasePluginConventions extends Conventions<JavaBasePlugin> {
 
 	@Override
 	void apply(JavaBasePlugin plugin) {
+		configureToolchains();
 		configureCheckstyle();
 		configureJavaFormat();
 		configureSourceAndTargetCompatibility();
@@ -55,6 +58,10 @@ void apply(JavaBasePlugin plugin) {
 		configureDependencyManagement();
 	}
 
+	private void configureToolchains() {
+		getProject().getPlugins().apply(ToolchainPlugin.class);
+	}
+
 	private void configureDependencyManagement() {
 		Configuration internal = getProject().getConfigurations().create("internal", (configuration) -> {
 			configuration.setCanBeConsumed(false);
@@ -91,6 +98,7 @@ private void configureJavaCompileTasks() {
 			options.setCompilerArgs(List.of("-Werror", "-Xlint:unchecked", "-Xlint:deprecation", "-Xlint:rawtypes",
 					"-Xlint:varargs", "-Xlint:options"));
 			options.setEncoding("UTF-8");
+			options.getRelease().set(17);
 		});
 	}
 

gradle/plugins/conventions/src/main/java/org/springframework/restdocs/build/conventions/MavenPublishPluginConventions.java

@@ -83,8 +83,9 @@ private void configureContents(MavenPublication maven) {
 						"https://jakarta.ee/specifications/bean-validation/3.1/apidocs/");
 			});
 		});
-		getProject().getPlugins().withType(JavaPlatformPlugin.class).configureEach((javaPlatformPlugin) ->
-			maven.from(getProject().getComponents().getByName("javaPlatform")));
+		getProject().getPlugins()
+			.withType(JavaPlatformPlugin.class)
+			.configureEach((javaPlatformPlugin) -> maven.from(getProject().getComponents().getByName("javaPlatform")));
 	}
 
 	private void configureDeploymentRepository(PublishingExtension publishing) {

gradle/plugins/settings.gradle

@@ -15,3 +15,4 @@ pluginManagement {
 
 include "conventions"
 include "optional-dependencies"
+include "toolchain"

gradle/plugins/toolchain/build.gradle

@@ -0,0 +1,12 @@
+plugins {
+	id "java-gradle-plugin"
+}
+
+gradlePlugin {
+	plugins {
+		optionalDependencies {
+			id = "org.springframework.restdocs.toolchain"
+			implementationClass = "org.springframework.restdocs.build.toolchain.ToolchainPlugin"
+		}
+	}
+}

gradle/plugins/toolchain/src/main/java/org/springframework/restdocs/build/toolchain/ToolchainPlugin.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2014-present 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
+ *
+ *      https://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.
+ */
+
+package org.springframework.restdocs.build.toolchain;
+
+import org.gradle.api.Plugin;
+import org.gradle.api.Project;
+import org.gradle.api.tasks.testing.Test;
+import org.gradle.jvm.toolchain.JavaLanguageVersion;
+import org.gradle.jvm.toolchain.JavaToolchainService;
+
+public class ToolchainPlugin implements Plugin<Project> {
+
+	@Override
+	public void apply(Project project) {
+		String toolchainVersion = (String) project.findProperty("toolchainVersion");
+		if (toolchainVersion != null) {
+			JavaToolchainService toolchainService = project.getExtensions().getByType(JavaToolchainService.class);
+			project.getTasks()
+				.withType(Test.class)
+				.configureEach((test) -> test.getJavaLauncher()
+					.set(toolchainService.launcherFor(
+							(spec) -> spec.getLanguageVersion().set(JavaLanguageVersion.of(toolchainVersion)))));
+		}
+	}
+
+}

gradle/plugins/toolchain/src/main/java/org/springframework/restdocs/build/toolchain/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2014-present 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
+ *
+ *      https://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.
+ */
+
+/**
+ * Toolchain plugin.
+ */
+package org.springframework.restdocs.build.toolchain;