jSnapLoader

[]() []()

A high-performance cross-platform dynamic library loader API for JVM Applications, with highly modifiable system-specific registration using platform predicates.

Software Specification:

Software Architectural Paradigm:

Quick Building and running examples:

┌─[pavl-machine@pavl-machine]─[/home/twisted/GradleProjects/jSnapLoader]
└──╼ $./gradlew clean && \
      ./gradlew build && \
      ./gradlew :snaploader-examples:run

BUILD SUCCESSFUL in 943ms
2 actionable tasks: 2 executed

BUILD SUCCESSFUL in 1s
7 actionable tasks: 7 executed

BUILD SUCCESSFUL in 1s
4 actionable tasks: 1 executed, 3 up-to-date

Run specific example by name:

┌─[pavl-machine@pavl-machine]─[/home/twisted/GradleProjects/jSnapLoader]
└──╼ $./gradlew :snaploader-examples:TestZipExtractor \
                :snaploader-examples:run

BUILD SUCCESSFUL in 1s
4 actionable tasks: 2 executed, 2 up-to-date

Plug-and-play usage:

Project build files:

[build.gradle]

dependencies {
    implementation "io.github.electrostat-lab:snaploader:1.0.0-stable"
}

[settings.gradle]

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
...
// project Gradle modules includes

Library Implementation:

1) The most straightforward way:

final LibraryInfo info = new LibraryInfo(new DirectoryPath("lib/independent"), "basename", DirectoryPath.USER_DIR);
// or
// final LibraryInfo info = new LibraryInfo(DirectoryPath.CLASS_PATH,
//      new DirectoryPath("lib/independent"), "basename", DirectoryPath.USER_DIR);
final NativeBinaryLoader loader = new NativeBinaryLoader(info);
final NativeDynamicLibrary[] libraries = new NativeDynamicLibrary[] {
      new NativeDynamicLibrary("lib/linux/x86-64", PlatformPredicate.LINUX_X86_64),
      new NativeDynamicLibrary("lib/macos/arm-64", PlatformPredicate.MACOS_ARM_64),
      new NativeDynamicLibrary("lib/macos/x86-64", PlatformPredicate.MACOS_X86_64),
      new NativeDynamicLibrary("lib/win/x86-64", PlatformPredicate.WIN_X86_64)
      ...
};
loader.registerNativeLibraries(libraries).initPlatformLibrary();
loader.setLoggingEnabled(true);
loader.setRetryWithCleanExtraction(true);
try {
      loader.loadLibrary(LoadingCriterion.INCREMENTAL_LOADING);
} catch (IOException e) {
      Logger.getLogger(NativeBinaryLoader.class.getName()
            .log(Level.SEVERE, "Native loader has failed!", e);
}

• This way utilizes the classpath on the stock Jar archive to locate, extract and load the native binaries.
• It first defines a library info object with a pointer to the classpath (aka. wrapped null string path), and a default path that will be used in case the platform path for the selected platform predicate is not assigned, then a basename for the library to be operated, and finally the current working directory as an extraction path.

2) A Superior control:

import java.nio.file.Path;
import java.nio.file.Paths;
...
// compatible with Java 8, Since 1.7
final Path compression = Paths.get(PropertiesProvider.USER_DIR.getSystemProperty(), "libs", "electrostatic4j.jar");
// create extraction path directory if not exists
final Path extractionPath = Files.createDirectories(Paths.get(PropertiesProvider.USER_DIR.getSystemProperty(), "libs", "natives"));
final LibraryInfo info = new LibraryInfo(new DirectoryPath(compression.toString()), new DirectoryPath("lib/independent"), "electrostatic4j", new DirectoryPath(extractionPath.toString()));
final NativeBinaryLoader loader = new NativeBinaryLoader(info);
final NativeDynamicLibrary[] libraries = new NativeDynamicLibrary[] {
      new NativeDynamicLibrary("lib/linux/x86-64", PlatformPredicate.LINUX_X86_64),
      new NativeDynamicLibrary("lib/macos/arm-64", PlatformPredicate.MACOS_ARM_64),
      new NativeDynamicLibrary("lib/macos/x86-64", PlatformPredicate.MACOS_X86_64),
      new NativeDynamicLibrary("lib/win/x86-64", PlatformPredicate.WIN_X86_64)
      ...
};
loader.registerNativeLibraries(libraries).initPlatformLibrary();
loader.setLoggingEnabled(true);
loader.setRetryWithCleanExtraction(true);
try {
      loader.loadLibrary(LoadingCriterion.INCREMENTAL_LOADING);
} catch (IOException e) {
      Logger.getLogger(NativeBinaryLoader.class.getName()
            .log(Level.SEVERE, "Native loader has failed!", e);
}

• This way utilizes the java.nio.file.Paths and java.nio.file.Path APIs to build platform-independent directory paths, and it's deemed the most superior way, especially for vague systems; thus it's considered the most robust way, and the best cross-platform strategy; because it depends on the Java implementation for this specific runtime.

3) Full control (external Jar localizing, platform predicates, and platform-independent extraction paths):

• Serial4j's Implementation - NativeImageLoader
• Electrostatic4j's Implementation - essentially the same

Appendix:

Features:

• [x] Platform-specific dynamic libraries' registration.
• [x] Platform-specific dynamic libraries building using platform-specific predicates (NEW).
• [x] Locate and load external dynamic libraries directly.
• [x] File Locator and extractor routines (classpath - external jar).
• [x] Extract native libraries from the stock jar library (classpath).
• [x] Locate external jars and extract native libraries from them.
• [x] Define an extract directory.
• [x] Retry Criterion with clean extraction (NEW).
• [x] Exposed the platform-dependent library NativeDynamicLibrary (NEW).
• [x] Exposed the NativeVariant providing system properties.
• [x] EventDispatchers: Extraction Listeners, Loading Listeners, and System Detection Listeners.
• [x] Filesystem Failure Throwable Exceptions: binds the user API to the jSnapLoader lifecycle.
• [x] Tight handling of memory leaks; as a result of file locator and/or file extractor failures.
• [x] Memory logging of the stream providers' handlers using the object hash keys.
• [ ] Extract automatically based on the application name and version.

Documentation-list:

• [x] Architecture paradigm.
• [x] API documentation.
• [ ] Java-Doc page.

Credits:

Projects:

Those projects had contributed implicitly and/or explicitly and must be recognized:

• Serial4j: was the initial trigger for this project.
• Jolt-jni: was and still the drive to continue this project.
• snap-jolt: provides an extensive testing environment for the API on a professional basis (including Linux-Arm); that is to extract and load Jolt-Jni, a Java binding library for Jolt-Physics framework.
• Electrostatic4j: will be the future supporter for this project.

People:

I owe these people a cup of coffee for their gracious contributions, when we eventually meet:

• Stephen Gold aka. sgold

Pure Science:

• Discrete mathematics and Ontology.
• The System-Entity-Structure (SES) Framework for System-design.
• The Tricotyledeon theory of system design by W.A.Wymore (T3SD).
• The Finite-automata theory.