In Gradle version 7.6 and above, Gradle provides a way to define Java toolchain auto-provisioning logic in plugins. This page explains how to author a toolchain resolver plugin. For details on how toolchain auto-provisioning interacts with these plugins, see Toolchains.

Provide a download URI

Toolchain resolver plugins provide logic to map a toolchain request to a download response. They do this via an implementation of JavaToolchainResolver:
public abstract class JavaToolchainResolverImplementation
        implements JavaToolchainResolver { (1)

    public Optional<JavaToolchainDownload> resolve(JavaToolchainRequest request) { (2)
        return Optional.empty(); // custom mapping logic goes here instead
1 This class is abstract because JavaToolchainResolver is a build service. Gradle provides dynamic implementations for certain abstract methods at runtime.
2 The mapping method returns a download response wrapped in an Optional. If the resolver implementation can’t provide a matching toolchain, the enclosing Optional contains an empty value.

Register the resolver in a plugin

Use a settings plugin (Plugin<Settings>) to register the JavaToolchainResolver implementation:
public abstract class JavaToolchainResolverPlugin implements Plugin<Settings> { (1)
    protected abstract JavaToolchainResolverRegistry getToolchainResolverRegistry(); (2)

    public void apply(Settings settings) {
        settings.getPlugins().apply("jvm-toolchain-management"); (3)

        JavaToolchainResolverRegistry registry = getToolchainResolverRegistry();
1 The plugin uses property injection, so it must be abstract and a settings plugin.
2 To register the resolver implementation, use property injection to access the JavaToolchainResolverRegistry Gradle service.
3 Resolver plugins must apply the jvm-toolchain-management base plugin. This dynamically adds the jvm block to toolchainManagement, which makes registered toolchain repositories usable from the build.