Java build

The Java version the Gradle or Maven build declares, how it declares it, and whether that mechanism makes the build reproducible, for the project and for every Gradle project it includes.


Facts key	`java`
Version	`v1`
Script	`java.py`
Timeout	30 seconds
Collects from	`gradle`, `maven`

Collectors

java doesn't read the build itself. It derives its facts from the collectors below. The CLI runs those first, passes their results to java, then hands the guardrail the facts it asked for.

Collector	Gathers
gradle	The Gradle build in the project directory: its settings and manifest, every included project, the wrapper and the distribution it pins, the version catalog, and every dependency the build files declare or the lock files resolve, with the versions its platforms supply.
maven	The Maven build in the project directory: the root `pom.xml` coordinates, its modules, its properties and every dependency it and its modules declare, with the versions its imported BOMs supply.

Inputs

Input	Description	Default	Environment
`projectDir`	Directory holding the project, relative to the directory the CLI runs in.	`.`	`GUARDRAIL_INPUT_PROJECTDIR`

A guardrail that declares an input of the same name passes it through, so the guardrail's configuration in buildnote.json is what decides these values.

A guardrail asks for these facts by name, and reads them back the same way:

json

{
  "collect": ["java"]
}

python

java = guardrail.facts("java")

Facts

The document java collects. A path carrying [] is an entry of the list before it, and one carrying [path] is a key of the object before it.

Fact	Meaning
`directory`	The `projectDir` input, as the guardrail configured it.
`exists`	Whether the Gradle or Maven build reports that directory is there. Nothing else is collected when it is not, and the collector collects nothing at all when neither of them collected anything.
`sources`	The Gradle and Maven build files that were there to read, Gradle first.
`declared`	Where the Java version is declared, or `null` when nothing declares one and whatever JDK runs the build decides. A Gradle toolchain wins over source compatibility, and Gradle wins over Maven.
`declared.version`	The version declared, as a release number such as `21`. `JavaVersion.VERSION_21`, `1.8` and `21` are all read as the release they name.
`declared.source`	The file declaring it, relative to `projectDir`.
`declared.mechanism`	How it is declared: `toolchain` when a Java toolchain selects the JDK, `compatibility` for `sourceCompatibility` or `targetCompatibility`, `release` for the compiler's `--release`, or `property` for a Maven property.
`declared.reproducible`	Whether the mechanism makes the build reproducible. Only a toolchain is: it provisions the JDK it names, where source compatibility merely asks whichever JDK is on the runner to accept older syntax and still links against that JDK's own classes.
`toolchain`	Whether any build file declares a Java toolchain at all, which is the answer to whether the JDK the build compiles against is chosen by the build rather than by the runner.
`projects`	The root project followed by every project the Gradle settings file includes.
`projects[].path`	Gradle path of the project, `:` for the root.
`projects[].directory`	Directory holding it, relative to `projectDir`.
`projects[].declared`	Where that project declares its own Java version, shaped as above, or `null`.

A collector that cannot finish prints what it had along with an incomplete key saying why, so the facts below the point it stopped are absent. A check that cares reads incomplete before the rest.

Example facts

The example facts collected by java collector:

json

{
  "directory": ".",
  "exists": true,
  "sources": [
    "build.gradle.kts",
    "gradle/libs.versions.toml"
  ],
  "declared": {
    "version": "21",
    "source": "build.gradle.kts",
    "mechanism": "toolchain",
    "reproducible": true
  },
  "toolchain": true,
  "projects": [
    {
      "path": ":",
      "directory": ".",
      "declared": {
        "version": "21",
        "source": "build.gradle.kts",
        "mechanism": "toolchain",
        "reproducible": true
      }
    },
    {
      "path": ":service",
      "directory": "service",
      "declared": {
        "version": "17",
        "source": "build.gradle.kts",
        "mechanism": "compatibility",
        "reproducible": false
      }
    }
  ]
}

Collected for

Guardrail	Category	Inputs
`java/toolchain-declared`	`java`	`projectDir`
`java/version-declared`	`java`	`projectDir`
`java/version-reproducible`	`java`	`projectDir`

All collectors

Java build ​

Collectors ​

Inputs ​

Facts ​