Update toolchain auto provisioning related content in manual

subprojects/docs/src/docs/userguide/jvm/toolchains.adoc

@@ -259,21 +259,27 @@ For details on writing plugins for toolchain provisioning, consult the <<toolcha
 When you configure a toolchain repository, Gradle no longer uses the built-in default Adoptium and OpenJDK toolchain respositories.
 ====
 
-Consider two toolchain resolver plugins:
+One example of a toolchain resolver plugin is the https://github.com/gradle/disco-toolchains[Disco Toolchains Plugin], based on the https://github.com/foojayio/discoapi[foojay Disco API].
 
-* One contains a resolver named `AzulResolver`, which downloads toolchains from Azul.
-* The other contains a resolver named `AdoptiumResolver`, which duplicates the built-in AdoptiumJDK toolchain repository by downloading toolchains from AdoptiumJDK.
+Beyond applying toolchain resolver plugins, the toolchain download resolvers provided by them also need to be configured.
+Let's illustrate with an example.
+Consider two toolchain resolver plugins applied by the build:
+
+* One is the Disco plugin mentioned above, which downloads toolchains via the `DiscoToolchainResolver` it provides.
+* The other contains a resolver named `AdoptiumResolver`, which duplicates the legacy toolchain resolver from past Gradle versions.
 
 The following example uses these toolchain resolvers in a build via the `toolchainManagement` block in the settings file:
 
 ====
-include::sample[dir="snippets/java/toolchain-management/groovy/",files="settings.gradle[tags=toolchain-management]"]
 include::sample[dir="snippets/java/toolchain-management/kotlin/",files="settings.gradle.kts[tags=toolchain-management]"]
+include::sample[dir="snippets/java/toolchain-management/groovy/",files="settings.gradle[tags=toolchain-management]"]
 ====
 <1> In the `toolchainManagement` block, the `jvm` block contains configuration for Java toolchains.
-<2> The `javaRepositories` block defines named Java toolchain repository configurations. Use the `resolverClass` property to link these configurations to plugins.
-<3> You can configure toolchain repositories with the same set of <<declaring_repositories.adoc#sec:authentication_schemes,authentication and authorization options>> used for dependency management.
-<4> Toolchain declaration order matters. Gradle downloads from the first repository that provides a match, starting with the first repository in the list.
+<2> The `javaRepositories` block defines named Java toolchain repository configurations.
+Use the `resolverClass` property to link these configurations to plugins.
+<3> Toolchain declaration order matters.
+Gradle downloads from the first repository that provides a match, starting with the first repository in the list.
+<4> You can configure toolchain repositories with the same set of <<declaring_repositories.adoc#sec:authentication_schemes,authentication and authorization options>> used for dependency management.
 
 [WARNING]
 ====

subprojects/docs/src/snippets/java/toolchain-management/groovy/settings.gradle

@@ -1,25 +1,28 @@
+plugins {
+    id 'org.gradle.toolchains.foojay-resolver' version '0.3.0'
+}
+
 import java.util.Optional
 import javax.inject.Inject
 
-apply plugin: AzulPlugin
 apply plugin: AdoptiumPlugin
 
 // tag::toolchain-management[]
 toolchainManagement {
     jvm { // <1>
         javaRepositories {
-            repository('azul') { // <2>
-                resolverClass = AzulResolver
+            repository('foojay') { // <2>
+                resolverClass = org.gradle.toolchains.foojay.FoojayToolchainResolver
+            }
+            repository('adoptium') { // <3>
+                resolverClass = AdoptiumResolver
                 credentials {
                     username "user"
                     password "password"
                 }
                 authentication {
                     digest(BasicAuthentication)
-                } // <3>
-            }
-            repository('adoptium') { // <4>
-                resolverClass = AdoptiumResolver
+                } // <4>
             }
         }
     }
@@ -28,49 +31,22 @@ toolchainManagement {
 
 rootProject.name = 'toolchain-management'
 
-abstract class AzulPlugin extends DummyPlugin {
-
-    AzulPlugin() {
-        super(AzulResolver.class)
-    }
-}
-
-abstract class AdoptiumPlugin extends DummyPlugin {
-
-    AdoptiumPlugin() {
-        super(AdoptiumResolver.class)
-    }
-}
-
-abstract class DummyPlugin implements Plugin<Settings> {
-
-    private final Class<JavaToolchainResolver> resolverClass;
+abstract class AdoptiumPlugin implements Plugin<Settings> {
 
     @Inject
     protected abstract JavaToolchainResolverRegistry getToolchainResolverRegistry();
 
-    DummyPlugin(Class<JavaToolchainResolver> resolverClass) {
-        this.resolverClass = resolverClass
-    }
-
     void apply(Settings settings) {
-        settings.getPlugins().apply("jvm-toolchain-management");
+        settings.getPlugins().apply("jvm-toolchain-management")
 
-        JavaToolchainResolverRegistry registry = getToolchainResolverRegistry();
-        registry.register(resolverClass)
-    }
-}
-
-abstract class AzulResolver implements JavaToolchainResolver {
-    @Override
-    Optional<JavaToolchainDownload> resolve(JavaToolchainRequest request) {
-        return Optional.empty();
+        JavaToolchainResolverRegistry registry = getToolchainResolverRegistry()
+        registry.register(AdoptiumResolver.class)
     }
 }
 
 abstract class AdoptiumResolver implements JavaToolchainResolver {
     @Override
     Optional<JavaToolchainDownload> resolve(JavaToolchainRequest request) {
-        return Optional.empty();
+        return Optional.empty()
     }
 }

subprojects/docs/src/snippets/java/toolchain-management/kotlin/settings.gradle.kts

@@ -1,3 +1,7 @@
+plugins {
+    id("org.gradle.toolchains.foojay-resolver") version("0.3.0")
+}
+
 import org.gradle.api.Plugin
 import org.gradle.api.initialization.Settings
 import org.gradle.jvm.toolchain.JavaToolchainResolver
@@ -6,25 +10,24 @@ import java.net.URI
 import java.util.Optional
 import javax.inject.Inject
 
-apply<AzulPlugin>()
 apply<AdoptiumPlugin>()
 
 // tag::toolchain-management[]
 toolchainManagement {
     jvm { // <1>
         javaRepositories {
-            repository("azul") { // <2>
-                resolverClass.set(AzulResolver::class.java)
+            repository("foojay") { // <2>
+                resolverClass.set(org.gradle.toolchains.foojay.FoojayToolchainResolver::class.java)
+            }
+            repository("adoptium") { // <3>
+                resolverClass.set(AdoptiumResolver::class.java)
                 credentials {
                     username = "user"
                     password = "password"
                 }
                 authentication {
                     create<DigestAuthentication>("digest")
-                } // <3>
-            }
-            repository("adoptium") { // <4>
-                resolverClass.set(AdoptiumResolver::class.java)
+                } // <4>
             }
         }
     }
@@ -33,11 +36,7 @@ toolchainManagement {
 
 rootProject.name = "toolchain-management"
 
-abstract class AzulPlugin: DummyPlugin(AzulResolver::class)
-
-abstract class AdoptiumPlugin: DummyPlugin(AdoptiumResolver::class)
-
-abstract class DummyPlugin(val resolverClass: kotlin.reflect.KClass<out JavaToolchainResolver>): Plugin<Settings> {
+abstract class AdoptiumPlugin: Plugin<Settings> {
 
     @get:Inject
     protected abstract val toolchainResolverRegistry: JavaToolchainResolverRegistry
@@ -46,7 +45,7 @@ abstract class DummyPlugin(val resolverClass: kotlin.reflect.KClass<out JavaTool
         settings.plugins.apply("jvm-toolchain-management")
 
         val registry: JavaToolchainResolverRegistry = toolchainResolverRegistry
-        registry.register(resolverClass.java)
+        registry.register(AdoptiumResolver::class.java)
     }
 
 }
@@ -55,10 +54,4 @@ abstract class AdoptiumResolver: JavaToolchainResolver {
     override fun resolve(request: JavaToolchainRequest): Optional<JavaToolchainDownload> {
         return Optional.empty()
     }
-}
-
-abstract class AzulResolver: JavaToolchainResolver {
-    override fun resolve(request: JavaToolchainRequest): Optional<JavaToolchainDownload> {
-        return Optional.empty()
-    }
 }