skip to content

How do you point the Javadoc task at a specific JDK's javadoc tool, and what fields can you set in the toolchain spec passed to javadocToolFor/launcherFor besides languageVersion?

level: middleimportance: nice to knowfreq 22%

answer

  1. Javadoc.javadocTool ← javadocToolFor
  2. shared JavaToolchainSpec across factories
  3. spec: languageVersion, vendor, implementation
  4. JvmVendorSpec (ADOPTIUM/AZUL/...) / matching()
  5. JvmImplementation.J9 for OpenJ9

basics

~10 s

Set the Javadoc task's javadocTool to javaToolchains.javadocToolFor { languageVersion = ... }. In the spec you can also set vendor (e.g. JvmVendorSpec.ADOPTIUM) and nativeImageCapable/implementation to constrain which JDK matches.

solid answer

~30 s

The `Javadoc` task exposes `javadocTool: Property<JavadocTool>`, populated from `javaToolchains.javadocToolFor { }`. The spec lambda is a `JavaToolchainSpec`, shared by all three factories (`launcherFor`, `compilerFor`, `javadocToolFor`). Besides `languageVersion`, you can set `vendor` (a `JvmVendorSpec`, e.g. `JvmVendorSpec.ADOPTIUM`, `AZUL`, `GRAAL_VM`, or `matching("...")`) to require a specific distribution, and `implementation` (`JvmImplementation.J9` or `VENDOR_SPECIFIC`) to require, e.g., an OpenJ9 VM. These constraints participate in toolchain *matching*: Gradle picks an installed (or auto-provisioned) JDK satisfying all of them, or fails if none match. Example: ```kotlin tasks.named<Javadoc>("javadoc") { javadocTool = javaToolchains.javadocToolFor { languageVersion = JavaLanguageVersion.of(21) vendor = JvmVendorSpec.ADOPTIUM } } ```

code

kotlin · 7 lines
kotlin
tasks.named<Javadoc>("javadoc") {
    javadocTool = javaToolchains.javadocToolFor {
        languageVersion = JavaLanguageVersion.of(21)
        vendor = JvmVendorSpec.ADOPTIUM
        implementation = JvmImplementation.VENDOR_SPECIFIC
    }
}

go deeper

for a junior

Know the Javadoc task uses javadocTool and that languageVersion is the main spec field.

for a middle

Add vendor and implementation as additional spec constraints and that the spec is shared across factories.

for a senior

Explain matching semantics, over-constraining pitfalls, and when distribution-specific constraints are justified.

for a principal

Frame vendor/implementation choices as org policy (licensing, support, GraalVM/J9) balanced against provisioning availability.

## The Javadoc per-task tool Gradle's `Javadoc` task runs the JDK's `javadoc` program. Its tool is selectable per task via `javadocTool: Property<JavadocTool>`: ```kotlin tasks.named<Javadoc>("javadoc") { javadocTool = javaToolchains.javadocToolFor { languageVersion = JavaLanguageVersion.of(21) } } ``` ## The shared JavaToolchainSpec All three factory lambdas configure the same `JavaToolchainSpec`. Its key properties: - **`languageVersion`** — a `JavaLanguageVersion` (e.g. `JavaLanguageVersion.of(21)`). The major Java feature version. Required to make a meaningful spec. - **`vendor`** — a `JvmVendorSpec` constraining the JDK distribution: `ADOPTIUM`, `AZUL`, `AMAZON`, `BELLSOFT`, `GRAAL_VM`, `IBM`, `MICROSOFT`, `ORACLE`, `SAP_MACHINE`, or `JvmVendorSpec.matching("...")`. Use it when a specific vendor's behaviour or licence matters. - **`implementation`** — a `JvmImplementation`: `VENDOR_SPECIFIC` (default) or `J9` to require an Eclipse OpenJ9 VM. ```kotlin javaToolchains.javadocToolFor { languageVersion = JavaLanguageVersion.of(21) vendor = JvmVendorSpec.AZUL implementation = JvmImplementation.VENDOR_SPECIFIC } ``` ## How matching works These fields form a *request*. Gradle searches detected JDK installations for one satisfying **all** constraints. If none match and auto-provisioning is enabled with a resolver, Gradle tries to download a matching JDK; otherwise the task fails with a clear toolchain-not-found error. The same matching applies whether you set the spec at the project level (`java.toolchain`) or per task — per task just scopes it to that task. ## Practical note For per-task overrides you usually only need `languageVersion`; `vendor`/`implementation` matter when a distribution-specific feature (e.g. a particular GC, OpenJ9, or GraalVM) is required, or when org policy mandates a vendor. Over-constraining can cause avoidable auto-provisioning or build failures if that exact JDK isn't available.

  • What happens if you over-constrain the spec (e.g. a vendor/version combo not installed)?
    Gradle tries to match an installed JDK; if none fits and auto-provisioning can't supply it, the task fails with a toolchain-not-found error. Over-constraining risks avoidable failures or downloads.
  • Is the spec different between launcherFor, compilerFor, and javadocToolFor?
    No — all three configure the same JavaToolchainSpec (languageVersion, vendor, implementation). Only the tool type produced differs.

saying these in an interview costs you the question

  • Thinking each factory has its own distinct spec type — it's the shared JavaToolchainSpec.
  • Setting vendor/implementation unnecessarily and causing match failures.
  • Confusing the Javadoc tool property name (it's javadocTool, not javadocLauncher).

context

resolving links…