<img src="https://github.com/Software-Hardware-Codesign/jSnapLoader/assets/60224159/85ac90d0-7d10-4d7c-a57e-390246ac5dee" width=60 height=60/> jSnapLoader

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

Software Specification:

| Item | Description | Predicate Calculus | |---------------------------------|-------------|--------------------| | Problem Definition | The main problem that entailed building this project had been to have something similar to the JME's NativeLibraryLoader, but for a better version with more capabilities (such as: loading libraries from external Jars and having a generic file extraction interface). | Sample = $P = [\cup_{n = 0}^N P_n]$ - Formula (Mapping relations in the form antecedents to descendants) = $\forall{P}\exists{S}\ F(P, S)$ | | Generalized Approach | The generalized approach was deemed insufficient; as it will not add on the JME's NativeLibraryLoader, and thus the project will be insignificant. The generalized approach entails building something that directly encapsulates concrete buffered byte stream calls to ZipFileSystem interfaces for the native libraries only within the same classpath, and that actually is a bad practice to build APIs on concretions, instead as the Ontology entails, abstractions and using levels of indirections should play the most part in developing a new system. | Sample = $S = [\cup_{n = 0}^N S_n]$ - Formula (Mapping relations in the form descendants to antecedents) = $\forall{S}\exists{P}\ F(S, P)$ | | jSnapLoader-specific Approach | The jSnapLoader-specific approach is quite genuine, nevertheless it's not unique. The essential design entails the basic use of the System-Entity-Structure (SES) Framework; which essentially decomposes the the bulky actions of the library, first from the perspective of behavior into deterministic finite-states, and then from the structural perspective into the components that execute these states; the net result is having a freely-floating decomposed components. The next step was regrouping those components (using common properties from predicate calculus) and finding abstractions for them, and finally capturing relations between those components and similar systems (i.e., FileSystem APIs). This structural way of thinking has resulted in the production of beneficial compilation units that could serve other purposes and not entailed specifically to serve native library extraction and loading. | $\forall{P_{loader}}\ \exists{S_{loader}}\ F(P_{loader}, S_{loader})$ | | Framework Decomposition | The decomposition had been successfully inducted into a FileLocator interface with a validation strategy, a FileExtractor interface with the full ability to control native IO resources, and a LibraryLoader interface with the ability to build and register platform predicates to support any new unsupported systems. | $$F = \cup_{n = 0}^N \ (P_{loader}, S_{loader})_{n}$$ $$= [(P_{file-locator}, S_{file-locator}), (P_{file-extractor}, S_{file-extractor}),$$ $$(P_{library-locator}, S'_{file-locator}), (P_{library-extractor}, S'_{file-extractor}), (P_{library-loader}, S_{library-loader})]$$ ;where $S'{clazz}$ S prime represents a solution of class 'clazz'. | | Common problems, robustness, and re-usability of solutions | To extend the robustness (rigidity) of the solution, multiple similar problems could utilize classes of solutions from the same kind; for instance, the problem library-locator could use a solution of the class file-locator; thus this could be explained by a uniqueness formula as regard to the formal language. | $$\forall{p}\ \in{P},\ \exists{s} \in{S},\ \forall{s'} \in{S} [(p{loader}, s_{loader}) \land\ (p_{loader}, s'_{loader})\ \implies\ [s_{loader} = s'_{loader}]$$ | | Framework Enhancements | The PlatformPredicate interface wasn't planned from the start; it has been added as an enhancement for the library to accomodate the changes and the addition of new platforms robustly without changing the internal API. In fact, I give credits to Jolt-jni for implicitly opening the vision to add them. Furthermore, the addition of the FileLocalizingListener, the FileExtractionListener, and the NativeLibraryLoadingListener binds the user API to the framework API giving jSnapLoader a more added robustness value overtime. | $$E = \cup_{n = 0}^N \ (E_{loader}, S_{loader})_{n}$$ $$= [(E_{system-detection-listeners}, S_{system-detection-listeners}), (E_{locator-listeners}, S_{locator-listeners}), (E_{extractor-listeners}, S_{extractor-listeners}),$$ $$(E_{loader-listeners}, S_{loader-listeners}), (E_{system-exception}, S_{system-exception})]$$ | | Credits for other systems | Credits should go for the jSnapLoader's users, Serial4j, Jolt-jni, and Electrostatic4j. Those implicitly and continously have pushed the API over to become better. | --- |

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.1.1-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:

The most straightforward way: https://github.com/Electrostat-Lab/jSnapLoader/blob/ac841ca914c1aba82c3bea0dfb3176a094712c7e/snaploader-examples/src/main/java/electrostatic4j/snaploader/examples/TestCrossPlatformClassPathLoading.java#L44-L72

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.

A Superior control: https://github.com/Electrostat-Lab/jSnapLoader/blob/ac841ca914c1aba82c3bea0dfb3176a094712c7e/snaploader-examples/src/main/java/electrostatic4j/snaploader/examples/TestBasicFeatures2.java#L48-L82

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.

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

Extract and load libraries with user-defined fallback routines for anti-loading failure:

Introduced in 1.1.1-stable.

https://github.com/Electrostat-Lab/jSnapLoader/blob/39613458ff2abd1ecb34a0f909ed70ec4ced4983/snaploader-examples/src/main/java/electrostatic4j/snaploader/examples/api/NativeDllLoader.java#L52-L302

Load libraries supporting specific CPU features by testing for those ISA Extensions using NativeVariant.Cpu.hasExtensions(...):

Introduced in 1.1.0-stable.

https://github.com/Electrostat-Lab/jSnapLoader/blob/a13f2ee12116f5538ec51b3eae8aaa0c3df634a0/snaploader-examples/src/main/java/electrostatic4j/snaploader/examples/TestCpuFeatures.java#L43-L90

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

JSnapLoader

Install / Use

README