provisioning library

Getting a package's Java libraries onto the machine, and finding them.

Kept out of package:java_interop/java_interop.dart: the binding itself does not need it, and a program that gets its jars another way never imports it. Like the binding, it depends on nothing beyond the Dart SDK.

The model: a package describes its Java runtime as a JavaRuntimeSpec — a POM it ships, a runtime id, the classes that must (and must not) be in the jars. At build time, runProvisioningCli (or provisionJavaRuntime) has Maven resolve the jars once into a versioned cache directory and verifyJars checks them. At runtime, resolveClassPath finds them for Jvm.startOrAttach:

final classPath = resolveClassPath(reportsRuntime);
final jvm = Jvm.startOrAttach(
  classPath: classPath.entries,
  vmOptions: const JvmOptions().build(),
);

Classes

JarFile

The entries of a jar (a zip file), read with dart:io alone.

JarVerification

What verifyJars found.

JavaRuntimeSpec

A package's Java runtime: the jars it needs, where they are cached, and how to check that a set of jars is the right one.

ProvisionResult

What provisionJavaRuntime did.

ResolvedClassPath

A class path resolveClassPath found.

Enums

ClassPathSource

Where a ResolvedClassPath came from.

Functions

locateMaven({String? explicit, Map<String, String>? environment}) → Future<String>

The mvn to run: explicit and nothing else when given; otherwise $MAVEN_HOME/$M2_HOME, the usual install locations, then the PATH. Throws MavenNotFound.

provisionJavaRuntime(JavaRuntimeSpec spec, {String? cacheDir, String? maven, bool offline = false, bool force = false, void log(String line)?, Map<String, String>? environment}) → Future<ProvisionResult>

Resolves spec's jars with Maven into its runtime directory, writes classpath.txt and manifest.json, and verifies the result.

readPackagePom(JavaRuntimeSpec spec) → Future<String>

spec's POM, read from its package (JavaRuntimeSpec.pomPackageFile under the package root), or from the current directory when the package cannot be resolved — running from the package's own checkout.

readRuntimeClassPath(JavaRuntimeSpec spec, Directory dir) → List<String>?

The class path recorded in the runtime directory dir, absolute; null when there is none, it belongs to another runtime id, its provisioning failed verification ("verified": false in the manifest), or an entry is missing.

resolveClassPath(JavaRuntimeSpec spec, {List<String>? explicit, String? cacheDirOverride, Map<String, String>? environment, String? projectDir}) → ResolvedClassPath

Finds spec's class path.

runProvisioningCli(JavaRuntimeSpec spec, List<String> args, {IOSink? out, IOSink? err, Map<String, String>? environment}) → Future<int>

A complete setup_jars command for spec, returning the exit code: 0 ok, 1 usage, 2 Maven not found or not runnable, 3 the runtime could not be provisioned (Maven failed, the cache is not writable) or, for --verify-only and --print-classpath, is not there, 4 verification failed. Output is flushed before it returns.

verifyJars(JavaRuntimeSpec spec, List<String> classPath) → JarVerification

Checks classPath — jars and class directories — against spec's required, forbidden and content rules, without starting a JVM.

Exceptions / Errors

JavaRuntimeNotProvisioned

The Java runtime a package needs is not where it should be.

MavenFailed

Maven ran and failed.

MavenNotFound

Maven is not installed, or not where it was said to be.