Skip to content

foojay.md

Latest commit

 

History

History
157 lines (114 loc) · 10.9 KB

foojay.md

File metadata and controls

157 lines (114 loc) · 10.9 KB
Raw

Querying Foojay

中文 | English

Foojay runs the Disco API, a public index of JDK builds from many vendors (source: foojayio/discoapi). Except on Linux loong64, the plugin gets every list of versions and every download link from it. What vfox search shows is Foojay's data, and Foojay is where to look when a build you expect is missing.

You can ask it yourself in the browser. The Swagger UI of the API has the endpoints, and its spec is foojay-discoapi-3.0.yml. Open GET /disco/v3.0/packages/jdks, press "Try it out", fill in the parameters and press "Execute". The page shows the curl command it ran and the JSON that came back.

What the plugin asks

vfox install java@21.0.8-tem on Linux x64 sends:

https://api.foojay.io/disco/v3.0/packages/jdks
  ?version=21.0.8
  &distribution=temurin
  &architecture=amd64
  &archive_type=tar.gz
  &operating_system=linux
  &lib_c_type=glibc
  &directly_downloadable=true
Parameter Value
distribution the long name, see distributions.md
version empty for vfox search and for a bare major such as 21, else the version part of what you typed. A + is percent-encoded, because Foojay reads a bare one as a space and drops the build. 28.ea.19 becomes 28-ea+19. Always empty for Mandrel and Liberica NIK, and for the GA releases of Oracle GraalVM and GraalVM Community
architecture aarch64 for arm64, x64 on Windows x64, amd64 for x64 elsewhere, and the name vfox reports for other CPUs
operating_system linux, macos or windows
archive_type tar.gz, and zip plus tar.gz on Windows. Elsewhere tar.xz comes in for Red Hat, and zip for OJDKBuild, OpenLogic and Gluon GraalVM
lib_c_type glibc or musl on Linux, empty elsewhere
directly_downloadable always true

For a bare major such as 21 the answer lists every release, and the plugin takes the newest 21.x itself, which is what java@21-tem installs: version=21 would match the 21 GA build only (21+35). Longer versions match as they are. Unreleased: release 0.6.2 asks for version=21&latest=available instead, with which Foojay picks the newest 21.x.

A bare major asks what searching asks so that installing sees the builds vfox search lists. Foojay's answers are cached per question, and two questions can get answers of different ages: half an hour after Oracle GraalVM 25.0.5 reached Foojay on 2026-10-20, GitHub's runners got it from a lookup with distribution_version=25 but not from a search, and vfox install java@25-graal took a build that vfox search java graal did not list (#113).

The answer is a list of packages. The plugin names a release after java_version (Mandrel and Liberica NIK after distribution_version, Oracle GraalVM and GraalVM Community after GraalVM's own version), adds -fx where javafx_bundled is true, marks it LTS where term_of_support is lts, and prefers a zip over a tar.gz of the same version on Windows. It leaves out the JREs, installer bundles and RHEL 6 builds that Foojay lists among OJDKBuild's Windows JDKs, and the JDK 11 builds of Gluon GraalVM's 22.x releases, see distributions.md. For the install it then fetches the package's links.pkg_info_uri and downloads its direct_download_uri, which is a vendor's own server (GitHub Releases for Temurin). That record also holds a checksum. The plugin does not pass it on, so vfox prints WARNING: Checksum is not provided, skip verify... and does not verify the download. Unreleased: a download from GitHub can go through a mirror, see mirror.md.

vfox search differs from the raw list in a few ways. It lists a name once where Foojay has two records for it, and it leaves the LTS note off GraalVM's feature releases (see distributions.md). It only lists GA releases.

Mandrel and Liberica NIK

Foojay gives the GraalVM version these two carry as distribution_version, and the Java version as java_version, for Mandrel the major only (2026-10-20):

curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=mandrel&distribution_version=23.1.12&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \
  | jq -r '.result[] | [.java_version, .distribution_version, .filename] | @tsv'
21	23.1.12.1	mandrel-java21-linux-amd64-23.1.12.1-Final.tar.gz
21	23.1.12	mandrel-java21-linux-amd64-23.1.12.0-Final.tar.gz

So the plugin asks for every package of these two, as vfox search does, and picks the release by distribution_version itself: the one named, or for a bare major the newest of the major. Foojay's own matching does neither: distribution_version=23.1.12 lists 23.1.12.1 as well, as above, and with distribution_version=23, latest=available answered with 23.1.8 and two builds of 23.0.1.2, although 23.1.12.1 was out. Where a release comes for several Java versions the plugin takes the build for the newest, and of two Liberica NIK builds for the same Java the later one, which only the file name tells apart (...-25.0.3+2-linux-amd64.tar.gz). Searching sorts them by distribution_version, newest first.

Which distributions have a build for my platform

latest=per_distro returns the newest package of every distribution that has one. Do not combine it with version, which it ignores.

# Windows on ARM64
curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?architecture=aarch64&operating_system=windows&archive_type=zip&archive_type=tar.gz&directly_downloadable=true&latest=per_distro' \
  | jq -r '.result[].distribution' | sort -u
jetbrains
liberica
microsoft
temurin
zulu

For another platform change the three parameters that name it. Linux needs lib_c_type=glibc or musl as well:

Platform Parameters
Linux arm64 architecture=aarch64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz
Alpine x64 architecture=amd64&operating_system=linux&lib_c_type=musl&archive_type=tar.gz
macOS Apple silicon architecture=aarch64&operating_system=macos&archive_type=tar.gz
macOS Intel architecture=amd64&operating_system=macos&archive_type=tar.gz
Windows x64 architecture=x64&operating_system=windows&archive_type=zip&archive_type=tar.gz

The names in the answer are the long names in distributions.md, except oracle_open_jdk, which the plugin calls openjdk (open). With archive_type=tar.gz alone the answer misses Red Hat and OJDKBuild on Linux, and OpenLogic on macOS, which ship tar.xz or zip there. The plugin asks for those types for them, see the table above.

Which distributions have a release for my platform

# Java 27 on Intel Macs
curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?version=27&latest=available&architecture=amd64&operating_system=macos&archive_type=tar.gz&directly_downloadable=true' \
  | jq -r '.result[].distribution' | sort -u

On 2026-10-18 this printed corretto liberica oracle semeru zulu. Temurin and OpenJDK were not among them: they stopped at 26 there. Use latest=available for a bare major, as the plugin does, and leave it out for a longer version.

The versions of one distribution

This is what vfox search java tem shows, for the machine you run it on:

curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&architecture=aarch64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \
  | jq -r '.result[].java_version'
27+35
26.0.2.1+1
26.0.2+10
...

Add version=21.0.8 for one release, and javafx_bundled=true for the JavaFX builds only. A record looks like this:

curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=temurin&version=21.0.8&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \
  | jq -c '.result[] | {java_version, distribution_version, term_of_support, javafx_bundled, archive_type, filename}'
{"java_version":"21.0.8+9","distribution_version":"21.0.8","term_of_support":"lts","javafx_bundled":false,"archive_type":"tar.gz","filename":"OpenJDK21U-jdk_x64_linux_hotspot_21.0.8_9.tar.gz"}

java_version is Java's version and the one the plugin uses. distribution_version is the vendor's own (Zulu's 27.28.101 for Java 27+35), which the plugin uses for Mandrel and Liberica NIK, see above, and for Oracle GraalVM and GraalVM Community.

For Oracle GraalVM and GraalVM Community, since October 2026, distribution_version is GraalVM's own version and java_version the JDK's, which a monthly feature release shares with a build of the 25.0 line:

curl -s 'https://api.foojay.io/disco/v3.0/packages/jdks?distribution=graalvm&version=25.0.4.1&architecture=amd64&operating_system=linux&lib_c_type=glibc&archive_type=tar.gz&directly_downloadable=true' \
  | jq -r '.result[] | [.java_version, .distribution_version, .filename] | join(" ")'
25.0.4.1 25.4.4.1.1 graalvm-jdk-25i4-25.0.4.1.1_linux-x64_bin.tar.gz
25.0.4.1 25.3.4.1 graalvm-jdk-25i3-25.0.4.1_linux-x64_bin.tar.gz
25.0.4.1 25.0.4.1.1 graalvm-jdk-25.0.4.1.1_linux-x64_bin.tar.gz
25.0.4.1 25.0.4.1 graalvm-jdk-25.0.4.1_linux-x64_bin.tar.gz

version cannot tell those apart, and distribution_version matches whole leading components (25.0.4.1 also lists 25.0.4.1.1). So the plugin asks for every package, as vfox search does, picks the release itself, and names it after GraalVM's version: the newer of a package's java_version and distribution_version, as GraalVM Community's feature releases are also listed the old way round, with GraalVM's version as java_version. vfox search lists them newest first by that version, and a file that Foojay lists under two versions once.

Releases and support terms

curl -s 'https://api.foojay.io/disco/v3.0/major_versions?ea=false&ga=true&maintained=true' \
  | jq -r '.result[] | [.major_version, .term_of_support] | @tsv'

lists the feature releases that are still maintained and whether each is LTS or STS. Early-access builds need release_status=ea or an explicit version such as version=28-ea.

Notes

  • Some HTTP clients get 403 from Foojay with their default User-Agent. Python's urllib does. curl does not, and neither does vfox.
  • The examples use jq, which you may have to install. Any JSON tool will do.
  • vfox keeps the result of vfox search for 12 hours, so a change in Foojay may take that long to show up.
  • Data problems, such as a missing or wrongly marked build, belong to Foojay: foojayio/discoapi. Problems with how this plugin reads the data belong in this repository.