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.

How Gradle names and reuses downloaded archives

Gradle names the downloaded archive after the file name the server provides in the Content-Disposition header. Without that header, Gradle uses everything after the last / of the URL, after any redirects, including any query. If the header is present but has no file name, Gradle names the archive after a hash of the full URL instead. If an archive with that name is already in the cache, Gradle reuses it instead of downloading it again.

If the server provides no file name in the Content-Disposition header, the archive name depends on the URL. A URL that changes between requests, such as one with an expiring access token (https://example.com/jdks/temurin-21?token=a1b2c3), makes Gradle download the archive again each time it provisions a toolchain. To avoid repeated downloads, return a stable URL, or have the server send a file name in the Content-Disposition header.

Gradle detects whether the archive is a zip or a tar.gz file from its content, not from its file name.

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.