Repository navigation
JPMS OSGi and Zero Dependency
One small jar that needs nothing but the JDK, is a named module on Java 9+ and an OSGi bundle on any Java, starts no thread, and leaves nothing behind when the application that loaded it is undeployed. This page shows how each of the four is arranged and proves it with commands and numbers: jdeps, jlink, Apache Felix, and a harness that redeploys an application 1000 times in a 64 MB metaspace (library 2.1.0, JDK 8, 11, 17, 21 and 25, Intel Core i9-9980HK).
-
Zero dependencies. The jar is 67,926 bytes;
jdepssays it needsjava.baseonly. Its one Maven dependency,spotbugs-annotations, is optional and its annotations areCLASS-retention markers: consumers need it neither to compile nor to run. -
JPMS. The named module
com.github.sftwnd.crayfish_common_crcexports one package. The descriptor is inMETA-INF/versions/9of a multi-release jar, so Java 8 ignores it. Ajlinkimage of an application with the library is 31.7 MiB, the JDK it was cut from 365 MiB. -
OSGi. The bundle has no
Import-Package, so it resolves without any other bundle. In Felix 7.0.5 it installs, resolves and starts in 26–35 ms, and 300 install, start, uninstall and refresh cycles on each of the five JDKs left no class loader behind. - Cleans up. The library starts no thread (the count was the same before and after), builds its lookup tables on the first calculation, and the garbage collector collects them when no model is used. A class loader with the library is collected on every JDK, with a model kept in a static field or not (see Unloading).
$ jdeps --multi-release 25 -s crayfish-common-crc-2.1.0.jar
com.github.sftwnd.crayfish_common_crc -> java.baseWhat that means in practice:
-
Nothing to resolve. No logging facade, no annotations library at run time, no shaded code. The packages the classes use are
java.lang,java.util,java.util.concurrent,java.nio,java.io,java.util.zip,java.lang.refand a few more ofjava.base. -
One optional dependency, for the compiler only. The Maven pom lists
com.github.spotbugs:spotbugs-annotationsasoptional, so it is not passed on to the projects that use the library. The annotations (@NonNull,@Nullable) haveCLASSretention:javap -vonCrcModelfinds 41RuntimeInvisibleAnnotationsand noRuntimeVisibleAnnotations, so the JVM never needs their classes. Every run on this page used the library jar alone on the class path or on the module path. -
No threads. A JVM that calculates CRCs, picks models by name and calls
StandardCrc.matchinghas the same number of threads before and after: 6 → 6 on JDK 25, 4 → 4 on JDK 8. -
Loaded when used. The first CRC-32 of a fresh JVM takes 19 ms on JDK 25 (59 ms on JDK 8) and loads only part of the 24 classes of the jar (18 class-load events with the lambdas, 23 when a model of the JDK is chosen): the classes of the calculation with
java.util.zip.CRC32are not loaded unless a model of the JDK is chosen.StandardCrc.matchingover all 112 algorithms takes 2.2 ms for the first call.
The price of having no dependencies is code that other libraries share: the lookup tables, the pool of the descriptions and the arithmetic of combine are the library's own, in 24 classes, 119 KB uncompressed, 67.9 KB in the jar.
The library is compiled for Java 8. On Java 9+ the jar is a named module because the module descriptor and the class that knows java.util.zip.CRC32C are in META-INF/versions/9:
$ jar --describe-module --file crayfish-common-crc-2.1.0.jar --release 9
com.github.sftwnd.crayfish_common_crc@2.1.0 jar:file:///.../crayfish-common-crc-2.1.0.jar!/META-INF/versions/9/module-info.class
exports com.github.sftwnd.crayfish.common.crc
requires com.github.spotbugs.annotations static
requires java.base mandatedrequires static is the optional annotations module: it is not resolved unless another module asks for it. The same jar has Automatic-Module-Name: com.github.sftwnd.crayfish_common_crc in its manifest, so a tool that builds on Java 8 or reads the jar as an automatic module sees the same name. The name has an underscore, as a module name may not contain a hyphen.
A modular application:
module my.app {
requires com.github.sftwnd.crayfish_common_crc;
}$ javac -d out/my.app --module-path libs src/my.app/module-info.java src/my.app/my/app/Main.java
$ java --module-path out:libs -m my.app/my.app.Main
CRC-32C = e3069283, jdk=true
module com.github.sftwnd.crayfish_common_crc named=true descriptor=false packages=[com.github.sftwnd.crayfish.common.crc]
exports [com.github.sftwnd.crayfish.common.crc]
requires [static com.github.spotbugs.annotations, mandated java.base (@9)]libs held the library jar only: the application started without the annotations module. Everything the application can see is the one exported package; there are no other packages to reach into. Then jlink cuts a runtime that contains exactly the modules the application needs:
$ jlink --module-path out:libs:$JAVA_HOME/jmods --add-modules my.app --output image \
--strip-debug --no-header-files --no-man-pages --compress zip-6
$ image/bin/java --list-modules
com.github.sftwnd.crayfish_common_crc@2.1.0
java.base@25.0.4
my.app
$ du -sk image # 32416 KiB, 31.7 MiB; the JDK 25 it was cut from: 373356 KiB, 365 MiBThe same jar on the class path of every JDK, with the class that is different in META-INF/versions/9:
| JDK | CrcModel.of("CRC-32C", true).isJdk() |
JdkCrcs.class taken from |
|---|---|---|
| 8 | false | the root of the jar (no CRC32C in Java 8: the lookup tables) |
| 11, 17, 21, 25 | true | META-INF/versions/9 |
The CRC is e3069283 on all five. The sources jar has the sources of META-INF/versions/9 at the same place, so a debugger on Java 9+ shows the source of the class it runs. Because the descriptor and the Java 9 classes are compiled on JDK 9+ only, a release is built on JDK 9+; the classes are compiled for Java 8 everywhere.
The manifest of the jar is made by bnd during the build:
Bundle-SymbolicName: com.github.sftwnd.crayfish.common.crc
Bundle-Name: CrayFish :: COMMON :: Crc
Bundle-Version: 2.1.0
Bundle-ManifestVersion: 2
Export-Package: com.github.sftwnd.crayfish.common.crc;version="2.1.0"
Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.8))"
Multi-Release: true
Automatic-Module-Name: com.github.sftwnd.crayfish_common_crc
There is no Import-Package and no Bundle-Activator: the bundle needs a Java 8 runtime and nothing else, and it has no code that runs when it starts or stops. Multi-Release: true makes a framework that supports it take the classes of META-INF/versions/9 on Java 9+ and the root ones on Java 8, as a class loader does. The export is versioned with the version of the bundle, so a consumer pins what it uses:
Import-Package: com.github.sftwnd.crayfish.common.crc;version="[2.1,3)"
Importing the range of the version the code was built against, [2.1,3), lets the framework resolve it with the bundles of that line only.
The check was a small program with Apache Felix 7.0.5: install the library bundle and a consumer bundle whose activator keeps a CrcModel in a static field, resolve, start, read the wiring; then 300 times install both, start, stop, uninstall and refresh, keeping a weak reference to the class loader of each library bundle.
Bundle lib = ctx.installBundle(crcJar.toURI().toString());
Bundle app = ctx.installBundle(consumerJar.toURI().toString()); // Import-Package: ...crc;version="[2.1,3)"
wiring.resolveBundles(Arrays.asList(lib, app)); // true
app.start(); // the activator calculates CRC-32C
// ... app.stop(); app.uninstall(); lib.stop(); lib.uninstall(); wiring.refreshBundles(null, listener);The output on JDK 17, 2.1.0:
resolved=true states crc=RESOLVED consumer=ACTIVE, install+resolve+start 33 ms, CRC-32C of 123456789 = e3069283, CRC-32C by the JDK in the bundle: true
wire com.github.sftwnd.crayfish.common.crc 2.1.0 -> demo.consumer
requirements: [osgi.ee (&(osgi.ee=JavaSE)(version=1.8))]
300 redeployments ok in 3873 ms
class loaders of the bundle still alive: 0 of 300, threads named crayfish: 0
| JDK | Install + resolve + start | 300 redeployments | Class loaders alive afterwards | CRC-32C by the JDK in the bundle |
|---|---|---|---|---|
| 8 | 32 ms | 4.4 s | 0 of 300 | false |
| 11 | 34 ms | 4.5 s | 0 of 300 | true |
| 17 | 33 ms | 3.9 s | 0 of 300 | true |
| 21 | 31 ms | 4.3 s | 0 of 300 | true |
| 25 | 29 ms | 3.9 s | 0 of 300 | true |
The last column shows that the multi-release jar works inside the framework: the bundle took the Java 9 class on 11 to 25 and the root one on 8. A cycle takes about 13 ms.
A class loader is collected only when nothing reachable refers to it, and a running thread is always reachable. A library that starts a thread, even a daemon one, keeps the class loader of the application that loaded it, with every class of the application, until the JVM stops: the metaspace grows with every redeployment, of a web application in a servlet container, of a plugin, of a module in an application server.
The library avoids it by starting no thread. The pool of the descriptions refers to them weakly and polls the queue of its references whenever it is used, on every Java version, so there is no cleaner thread and nothing that refers to the class loader from outside.
The harness loads the library and a small application (CrcModel.of("CRC-32C").value(...), optionally kept in a static field) in a URLClassLoader of their own, drops the loader and asks the garbage collector whether it was collected:
URLClassLoader loader = new URLClassLoader(new URL[] {library, application}, null);
loader.loadClass("leakapp.LeakApp").getMethod("run", boolean.class).invoke(null, keep);
loader.close();
WeakReference<ClassLoader> ref = new WeakReference<>(loader); // loader = null; System.gc() up to 50 times| JDK | Class loader collected | Threads of the library alive |
|---|---|---|
| 8 | yes | none |
| 11 | yes | none |
| 17 | yes | none |
| 21 | yes | none |
| 25 | yes | none |
The result is the same with the model kept in a static field. Then the real test, a redeployment loop: the application is deployed 1000 times with -XX:MaxMetaspaceSize=64m, a new class loader each time, and the metaspace never runs out:
| JDK | 1000 deployments |
|---|---|
| 8 | ok, 7.5 s |
| 11 | ok, 7.4 s |
| 17 | ok, 5.6 s |
| 21 | ok, 6.7 s |
| 25 | ok, 5.7 s (6.3 s with the model kept in a static field) |
So the library can be redeployed as often as the application: there is nothing to stop in contextDestroyed, in BundleActivator.stop or in a shutdown hook, because nothing was started.
The memory is the lookup tables, built on the first calculation and collected when unused:
- There is one
CrcDescriptionper parameter set, shared by all models and CRCs of the parameters, by any name. The pool refers to the descriptions weakly: when no model and no CRC of the parameters is used, the garbage collector collects the description with its tables. Keep the model in a field to keep the tables. - The tables (8 × 256 values) are built on the first calculation with data, not when a model is chosen: 8 KiB for a width up to 32 bits, 16 KiB for a wider CRC. For all 112 algorithms that is 104 × 8 + 8 × 16 = 960 KiB.
Heap in use after a full garbage collection, JDK 25, the delta over the start of the JVM:
| Step | Heap |
|---|---|
| the 112 models chosen, no calculation | +142 KiB |
| the first calculation of each (the tables built) | +1104 KiB |
| the references dropped, garbage collected, the pool used | +106 KiB |
the same with -D...crc.retention=soft
|
+1104 KiB: kept until the memory runs short |
The tables of 112 algorithms are 962 KiB (the step 2 minus the step 1), as the sizes above say. Collected tables are rebuilt on the next calculation: the first call of a model took 41 µs on average over the 112 (16 µs for CRC-32, 25 µs for CRC-16/ARC), the second 1.2 µs. Do not build a model by name for every calculation when it is called thousands of times a second; keep it in a field, or set -Dcom.github.sftwnd.crayfish.common.crc.retention=soft so that an unused description stays until the memory runs short. The property is read once, when the pool is used first. StandardCrc.matching builds the tables of the algorithms the value fits into, about 1 MiB for all of them, and leaves them to the garbage collector.
| You have | What to do |
|---|---|
| a Maven or Gradle project | one dependency, crayfish-common-crc; nothing else is passed on |
| a modular application |
requires com.github.sftwnd.crayfish_common_crc;, and jlink it |
| Java 8 | the same jar: the descriptor and the Java 9 classes are ignored |
| an OSGi runtime | install the jar; import the package with [2.1,3) if you call anything new in 2.1.0 |
| a web application or a plugin that is redeployed | nothing to stop; nothing is left behind |
| a hot path | keep the model in a field |