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 works out its facts from the collectors below. The CLI runs those first, passes their results to java, and then gives 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`

When a guardrail declares an input with the same name, it passes its value through. That means you set these values in the guardrail's configuration in buildnote.json.

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

json

{
  "collect": ["java"]
}

python

java = guardrail.facts("java")

Facts

These are the fields of the document java collects. In a path, [] means each entry of the list before it, and [path] means a key of the object before it.

Fact	Meaning
`directory`	The project directory set by the guardrail's `projectDir` input, relative to the directory the CLI runs in. Every other path this collector reports is also relative to the directory the CLI runs in, so it resolves from where you invoked the CLI, not from wherever the collector happened to run.
`exists`	Whether the Gradle or Maven build reports that the directory exists. When it doesn't, nothing else is collected, and when neither build collected anything, this collector collects nothing at all.
`sources`	The Gradle and Maven build files that were present 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, from the directory the CLI runs in.
`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 does: it provisions the JDK it names. Source compatibility only asks whichever JDK is on the runner to accept older syntax, and the build still links against that JDK's own classes.
`toolchain`	Whether any build file declares a Java toolchain at all. This tells you whether the build, not the runner, chooses the JDK it compiles against.
`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, from the directory the CLI runs in.
`projects[].declared`	Where that project declares its own Java version, shaped as above, or `null`.

If a collector can't finish, it prints what it gathered so far along with an incomplete key that says why. Facts after the point where it stopped are missing, so a check that depends on them should read incomplete first.

Example facts

Here are the facts the java collector gathers from an example project:

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": "service/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 ​