Home /Modules/connector/DYNAMITE_CONNECTOR.md

DYNAMITE_CONNECTOR.md

connector/DYNAMITE_CONNECTOR.md · 80 line(s) · markdown

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

PropertyBehavior
Cross-platform namingA 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 rootsaddRoot(dir) lists directories to search; no reliance on ambient java.library.path.
Allow-listedA name loads only if allowLibrary(name) permitted it (or allowAny() in a trusted context). Default is fail-closed.
Two load modesload(name) does a JNI-style System.load; lookup(name) opens an FFM SymbolLookup (no JNI) so individual symbols can be found/bound.
CachedResolutions and symbol lookups are memoised.
Fail closedA 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

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.