DynamiteConnector — intelligent loader of native shared libraries
DynamiteConnector
(connector/java/.../DynamiteConnector.java)
is SLeeLa's facility for taking in a native library — a .so on Linux, a
.dll on Windows, or a .dylib on macOS — and loading it or binding its
symbols. It is the native-library counterpart to
SleelaClassLoader: same hardened posture (explicit roots,
allow-listed names, cached, fail-closed), but for raw native code instead of
raw Java classes.
Why SLeeLa needs this
SLeeLa already loads one native library the bare way
(System.loadLibrary("sleela_java28")), but System.loadLibrary only searches
java.library.path and gives no control over which file a logical name maps
to, no allow-list, and no symbol-level access. Driver families such as
eprom-corrado (USB → EPROM via libusb) need to load a backend library from a
known location, across three operating systems, without each caller re-deriving
the per-OS filename. DynamiteConnector is that single, reusable function.
What "intelligent" means
| Property | Behavior |
|---|---|
| Cross-platform naming | A logical name (sleela_java28) maps to the right file per OS: libsleela_java28.so / sleela_java28.dll / libsleela_java28.dylib. Uses the JVM's own System.mapLibraryName plus the common conventions, so both foo and an already-decorated libfoo.so resolve. |
| Explicit roots | addRoot(dir) lists directories to search; no reliance on ambient java.library.path. |
| Allow-listed | A name loads only if allowLibrary(name) permitted it (or allowAny() in a trusted context). Default is fail-closed. |
| Two load modes | load(name) does a JNI-style System.load; lookup(name) opens an FFM SymbolLookup (no JNI) so individual symbols can be found/bound. |
| Cached | Resolutions and symbol lookups are memoised. |
| Fail closed | A disallowed name, a name with path separators / .., or a name that resolves to no file throws rather than guessing. |
Thread-safe; AutoCloseable (closing releases any FFM Arena opened for symbol
lookups).
Usage
try (DynamiteConnector dc = new DynamiteConnector()) { // detects the OS
dc.addRoot(Path.of("build/linux")) // where the libs are
.allowLibrary("sleela_java28"); // allow-list a name
// JNI-style: load so registered natives become callable
dc.load("sleela_java28");
// FFM-style: bind individual symbols without JNI
if (dc.hasSymbol("sleela_java28", "sleela_entry")) {
var addr = dc.find("sleela_java28", "sleela_entry").orElseThrow();
// ... bind with java.lang.foreign.Linker.downcallHandle(addr, ...) ...
}
}
Running an FFM lookup requires --enable-native-access for the module/jar that
owns the connector (e.g. --enable-native-access=ALL-UNNAMED on the classpath).
Errors
DynamiteConnector.LibraryResolutionException— not allow-listed, resolved to no file on any root, or failed to load / open a symbol lookup.IllegalArgumentException— a blank name, a name containing a path separator, or a name containing..(guards against path-traversal input).
Relationship to driver families
A family like eprom-corrado can use
DynamiteConnector to load its backend native library (e.g. a libusb-backed
EPROM driver) from the family's own build output, then reach it either through
JNI (load) or FFM (lookup). The connector handles finding and loading the
library; the family's contract (EpromControl / EpromConnector) handles
using it.
Security
Loading native code runs with full process privilege — there is no sandbox once
a .so/.dll/.dylib is loaded. Treat the allow-list and roots as a trust
boundary: only permit names and directories you control. Do not derive a root or
a library name from untrusted input. This is why the default is fail-closed and
allowAny() must be called explicitly.