Toolchain Resolver Plugins
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:
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:
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. |