Oubliette

Oubliette provides a convenient way to launch a new JVM instance by specifying the classpath, main method and arguments to be invoked. Classes may be pre-loaded, providing near-instantaneous JVM startup time. This provides similar functionality to invoking a main method through a classloader, but with significantly better isolation from the initiating JVM.

Features

launch JVM instances by specifying command-line parameters
achieve near-instantaneous startup times by preloading classes
automatically download Adoptium JDKs before launching

Availability

Oubliette has not yet been published as a binary, though work is ongoing to fix this.

Getting Started

Oubliette can launch a new JVM, represented by an instance of Jvm, from a particular installed version of a JDK, represented by an instance of Jdk. This can either be done in a single command, Jdk#launch, or through a series of steps, which may make the final invocation step faster in some cases.

The simplest invocation is,

val jvm: Jvm = jdk.launch(classpath, main, args)

where classpath is a List of paths, main is the name of the main class to launch, and args is a List of arguments. The paths may be specified in any type for which a GenericPathReader instanceexists, as defined in Anticipation, such as java.io.File.

From a Jvm instance, methods such as Jvm#stdout, Jvm#stderr and Jvm#stdin provide access to the JVM's input and output streams, through a LazyList[IArray[Byte]] interface. Additionally, Jvm#pid will give the running JVM's process ID, and Jvm#abort will abort execution.

But a JVM can be created without having it start execution. We can launch a new JVM with,

val jvm = jdk.init()

and provide it with the details it needs to run in steps, with:

Jvm#addClasspath to add a path to the classpath,
Jvm#addArg to add a single Text argument to the main method,
Jvm#setMain to specify the main method, and,
Jvm#preload to load the named classes early

Preloading classes offers the opportunity to prime the JVM instance to be as ready as possible to invoke the specified main method when the time comes. This results in near-instantaneous startup times, provided the classes can be loaded long enough before the main method is invoked.

Specifying a JDK

A Jdk instance can be created by specifying its version number, e.g. 17, and a path (in any path format) to its home directory, that is, the directory which contains the bin directory in which the java executable resides. For example:

val jdk = Jdk(14, java.io.File("/usr/lib/jdk"))

Using Adoptium JVMs

Adoptium provides prebuild OpenJDK binaries for download, and Oubliette can automatically download and use them. This is as simple as installing the Adoptium script to the filesystem with, Adoptium.install(), and calling get() on the result, to fetch the most recent version.

Other options (all with default values) for the get method include,

version, the JDK version
jre, should be true if a JRE is preferred over a full JDK
early, should be true if early-access binaries should be considered
force, to force download again, even if an existing installation exists

If an appropriate JDK can be found, then get will return a Jdk instance, from which a Jvm can be launched.

Related Projects

The following Scala One libraries are dependencies of Oubliette:

No other Scala One libraries are dependents of Oubliette.

Status

Oubliette is classified as embryonic. For reference, Scala One projects are categorized into one of the following five stability levels:

embryonic: for experimental or demonstrative purposes only, without any guarantees of longevity
fledgling: of proven utility, seeking contributions, but liable to significant redesigns
maturescent: major design decisions broady settled, seeking probatory adoption and refinement
dependable: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version 1.0 or later
adamantine: proven, reliable and production-ready, with no further breaking changes ever anticipated

Projects at any stability level, even embryonic projects, are still ready to be used, but caution should be taken if there is a mismatch between the project's stability level and the importance of your own project.

Oubliette is designed to be small. Its entire source code currently consists of 107 lines of code.

Building

Oubliette can be built on Linux or Mac OS with Fury, however the approach to building is currently in a state of flux, and is likely to change.

Contributing

Contributors to Oubliette are welcome and encouraged. New contributors may like to look for issues marked beginner.

We suggest that all contributors read the Contributing Guide to make the process of contributing to Oubliette easier.

Please do not contact project maintainers privately with questions unless there is a good reason to keep them private. While it can be tempting to repsond to such questions, private answers cannot be shared with a wider audience, and it can result in duplication of effort.

Author

Oubliette was designed and developed by Jon Pretty, and commercial support and training is available from Propensive OÜ.

Name

An oubliette is a dungeon into which a prisonner could be condemned for a lifetime, no longer interacting with the outside world; metaphorically, a separate JVM instance.

propensive / oubliette