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. At the moment the download response only contains a download URL, but may be extended in the future.

For the download URL only secure protocols like https are accepted. This is required to make sure no one can tamper with the download in flight.

The plugins provide the mapping logic via an implementation of JavaToolchainResolver:

JavaToolchainResolverImplementation.java
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:

JavaToolchainResolverPlugin.java
public abstract class JavaToolchainResolverPlugin implements Plugin<Settings> { (1)
    @Inject
    protected abstract JavaToolchainResolverRegistry getToolchainResolverRegistry(); (2)

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

        JavaToolchainResolverRegistry registry = getToolchainResolverRegistry();
        registry.register(JavaToolchainResolverImplementation.class);
    }
}
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.