eclipse justj

JustJ provides fully-functional Java™ runtimes that can be redistributed by Eclipse Projects. The form in which these are made available is intended to make these easily consumable. As such, Java runtimes are available via p2 repositories as well as via direct packaged downloads. The sources of these Java runtimes are any and all versions approved by the Eclipse Foundation for such purposes.

Originally approval was limited to the latest release available via https://jdk.java.net/, but now releases available via https://adoptium.net/ are also approved. This has the major advantage that Long Term Support (LTS) versions are now available.

JustJ provides sample products that illustrate how to use the p2 update sites to build a product that includes an embedded Java runtime.

Building JREs with jlink

Java's modularized architecture supports generating a JRE from a JDK using jlink. For any given JDK installation, the following command will list the full set of modules available in that JDK:

java --list-modules

This list of modules can be boiled down to produce the --add-modules argument need to run jlink.

A minimal JRE with just the java.base module can be produced using jlink as follows:

jlink --add-modules=java.base --output .

The size of this JRE can be reduced using compression:

jlink --compress=2 --add-modules=java.base --output .

The size of this JRE can be further reduced by stripping debug symbols:

jlink --compress=2 --strip-debug --add-modules=java.base --output .

This is the smallest JRE that can be used for running very simple Java applications.

Building JREs for OSGi

To launch an OSGi/Equinox application, the minimal functional JRE must also include the java.xml module, and to avoid deep-reflection warnings should include the jdk.unsupported module:

jlink --add-modules=java.base,java.xml,jdk.unsupported --output .

Automated JRE Generation with

The process for generating a JRE from a JDK has been fully automated via build-jre.sh which is designed to run on any operating system; on Windows, Git Bash or Cygwin is needed. The process of producing a JRE must run natively on each operating system using an operating-system-specific JDK.

The build-jre.sh script is used by a Jenkins pipeline script which in turn is used by the build-jres job to produce the following downloads:

https://download.eclipse.org/justj/jres/14/downloads/latest/

Each download page is generated by the JustJ Tools and, for each JRE, includes detailed information about how the JRE was produced, including the source URL from which it was downloaded, as well as details about the contents and the runtime characteristics. You will see there that a full, compressed JRE, i.e., those JREs with the .jre.full qualifier, are roughly 70MB is size, while an absolutely minimal, compressed, OSGi-capable JRE, i.e., those JREs with the .jre.base qualifier, are roughly 20MB is size. These sizes are significantly (15% to 20%) reduced by stripping debug information, i.e., those JREs with the .stripped qualifier. See the Building Smaller JREs with jdeps section for details about creating JREs with a subset of the available modules.

Automated JRE p2 Generation with .tools

A large portion of Eclipse's ecosystem is based on the Eclipse Platform and uses Equinox p2 for provisioning and updating IDE installations and Rich Client Platform (RCP) applications. For this purpose, there is a strong need for consuming JREs in the form of installable units hosted by a p2 repository. This enables, for example, a product to specify a dependency on a specific JRE version and build it using Tycho to ship an embedded JRE in their product, i.e., one that runs out-of-the-box regardless of what version of Java, if any, is installed on the system.

To build such a p2 repository we naturally do so with a Maven/Tycho build. The basis for this is of course a file system structure with projects for features and plugins, along with all the other scaffolding needed to drive the build. But this is all primarily just boiler-plate scaffolding that will be difficult and error prone to maintain.

To alleviate this long-term burden, and to make the process as flexible and responsive as possible, all the needed scaffolding is generated from a model that concisely captures all the essential information.

The model along with associated tools are maintained in justj.tools and are available at following update site:

https://download.eclipse.org/justj/tools/updates

The tools needed to maintain that update site are part of the JustJ Tools suite, i.e., org.eclipse.justj.p2.

The model.ecore was used to generate the org.eclipse.justj.codegen plugin. That plugin implements the generation process.

An instance of that model, justj.jregen, is maintained in justj. The Jenkins pipeline script used by the build-jres job produces not just the JRE downloads, as described above, but also the corresponding p2 update site for those JREs. The process works as follows:

• Each JRE download page includes a justj.manifest which is essentially just a list of URLs (generally relative URLs) pointing to the set of JRE packages, i.e., all the *.tar.gz files.
• The justj.jregen model is reconciled against a justj.manifest's referenced *.tar.gz files. Each *.tar.gz file contains an org.eclipse.justj.properties file in the archive root and that files contains the key information captured during the generation of the JRE, i.e., precisely the properties displayed on the JRE download page under each JRE. That information is used to flesh out the model with corresponding JVM instances (one per JRE Java version), each of those with corresponding Variant children (one per operating-specific variant of the Java version). The resulting reconciled justj.jregen is available in the build artifacts. The *.tar.gz itself is inspected during the reconciliation process to determine which artifacts require execute permission; that information is used to synthesize the Touchpoint representation in the model.
• The reconciled model then drives the generation process. Specifically it produces the jre-gen folder available in the build artifacts.
• The jre-gen folder's pom.xml then drives a Maven/Tycho build to produce an update site that is published here:

  https://download.eclipse.org/justj/jres/14/updates/nightly/latest

  That update site, like the Tools update site, is maintained by org.eclipse.justj.p2. It contains detailed information about the installable units available in each p2 repository. For traceability, all the information from the original justj.jregen model is captured by the content metadata of the p2 repository, sufficiently so that the justj.jregen instance can be reconstructed from the repository's metadata.

In summary, the entire process of building JREs from JDKs and repackaging them in the form of a p2 update site is fully automated, with only the URLs for the JDKs as input. This process has been validated using URLs from https://adoptopenjdk.net/ in addition to those those from https://jdk.java.net/ and https://adoptium.net/, but we do not currently have Eclipse Foundation approval to redistribute results from that source.

See the Anatomy of jre-gen section for more details.