1.0.0 stable branch

[pavly-gerges]

This PR marks the final PR after which the stable release process could be initiated.

In this PR, the following is attained:

• [x] Introduced DirectoryPath for external path extraction to avoid nullary arguments.
• [x] Memory logging optimizations for external file streams initializers.
• [x] 1.0.0-zeta pre-release on this branch for testing.

[pavly-gerges]

This PR hopefully removes the hassle of using ZipCompressionType enum; that is obviously an anti-pattern introducing race conditions to the framework, and was captured by the TestMultipleLoads example. And, merge the classpath routine into the file locator API, among other features like merging the validation into the exception handling block.

[pavly-gerges]

Alright, here is another test report from snap-jolt:

/media/pavl-machine/pavl-g/Projects/snap-jolt git:[jsnaploader-1.0.0-stable]
./gradlew run

> Task :run FAILED
OpenJDK 64-Bit Server VM warning: You have loaded library /media/pavl-machine/pavl-g/Projects/snap-jolt/libjoltjni.so which might have disabled stack guard. The VM will try to fix the stack guard now.
It's highly recommended that you fix the library with 'execstack -c <libfile>', or link it with '-z noexecstack'.
Aug 07, 2024 1:43:51 PM electrostatic4j.snaploader.NativeBinaryLoader loadBinary
SEVERE: Cannot load the dynamic library: /media/pavl-machine/pavl-g/Projects/snap-jolt/libjoltjni.so
java.lang.UnsatisfiedLinkError: /media/pavl-machine/pavl-g/Projects/snap-jolt/libjoltjni.so: /media/pavl-machine/pavl-g/Projects/snap-jolt/libjoltjni.so: file too short
        at java.base/java.lang.ClassLoader$NativeLibrary.load0(Native Method)
        at java.base/java.lang.ClassLoader$NativeLibrary.load(ClassLoader.java:2445)
        at java.base/java.lang.ClassLoader$NativeLibrary.loadLibrary(ClassLoader.java:2501)
        at java.base/java.lang.ClassLoader.loadLibrary0(ClassLoader.java:2700)
        at java.base/java.lang.ClassLoader.loadLibrary(ClassLoader.java:2630)
        at java.base/java.lang.Runtime.load0(Runtime.java:768)
        at java.base/java.lang.System.load(System.java:1837)
        at electrostatic4j.snaploader.NativeBinaryLoader.loadBinary(NativeBinaryLoader.java:253)
        at electrostatic4j.snaploader.NativeBinaryLoader.loadLibrary(NativeBinaryLoader.java:158)
        at com.github.stephengold.snapjolt.HelloWorld.main(HelloWorld.java:104)

Aug 07, 2024 1:43:51 PM electrostatic4j.snaploader.library.LibraryExtractor initialize(int)
INFO: File extractor initialized with hash key #584641848
Aug 07, 2024 1:43:51 PM electrostatic4j.snaploader.library.LibraryLocator initialize(int)
INFO: File locator initialized using classpath routine with hash key #1099967463
Aug 07, 2024 1:43:51 PM electrostatic4j.snaploader.NativeBinaryLoader$2 initializeLibraryExtractor
INFO: Locating native libraries has succeeded!
null
sun.net.www.protocol.jar.JarURLConnection$JarURLInputStream@45ff54e6
Aug 07, 2024 1:43:51 PM electrostatic4j.snaploader.NativeBinaryLoader cleanExtractBinary
INFO: File extractor handler initialized!
Aug 07, 2024 1:43:51 PM electrostatic4j.snaploader.NativeBinaryLoader$1 cleanExtractBinary
SEVERE: Extraction has failed!
java.lang.NullPointerException
        at electrostatic4j.snaploader.filesystem.FileExtractor.extract(FileExtractor.java:139)
        at electrostatic4j.snaploader.filesystem.ConcurrentFileExtractor.extract(ConcurrentFileExtractor.java:72)
        at electrostatic4j.snaploader.NativeBinaryLoader.cleanExtractBinary(NativeBinaryLoader.java:339)
        at electrostatic4j.snaploader.NativeBinaryLoader.loadBinary(NativeBinaryLoader.java:267)
        at electrostatic4j.snaploader.NativeBinaryLoader.loadLibrary(NativeBinaryLoader.java:158)
        at com.github.stephengold.snapjolt.HelloWorld.main(HelloWorld.java:104)

Aug 07, 2024 1:43:51 PM electrostatic4j.snaploader.library.LibraryExtractor close
INFO: File extractor #584641848 resources closed!
Exception in thread "main" java.lang.UnsatisfiedLinkError: 'void com.github.stephengold.joltjni.Jolt.registerDefaultAllocator()'
        at com.github.stephengold.joltjni.Jolt.registerDefaultAllocator(Native Method)
        at com.github.stephengold.snapjolt.HelloWorld.main(HelloWorld.java:111)

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':run'.
> Process 'command '/usr/lib/jvm/java-11-openjdk-amd64/bin/java'' finished with non-zero exit value 1

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

BUILD FAILED in 2s
2 actionable tasks: 2 executed
<-------------> 0% WAITING
> IDLE

Interpretation:

The API lifecycle shows that it fails at the extraction phase due to nullary file streams during the buffer allocation phase for the file output stream handlers.

Possible Potential causes:

• [-] Premature closure of file locator stream providers on any stage of the loading lifecycle (EXCLUDED).
• [-] Nullary LibraryLocator#filePath field (SUSPECT).

Analysis code:

LibraryInfo info = new LibraryInfo(new DirectoryPath("linux/x86-64/com/github/stephengold"),
                "joltjni", DirectoryPath.USER_DIR);
  NativeBinaryLoader loader = new NativeBinaryLoader(info);
loader.setLibraryLocalizingListener(new FileLocalizingListener() {
      @Override
      public void onFileLocalizationSuccess(FileLocator locator) {
                try {
                    Field field = FileLocator.class.getDeclaredField("filePath");
                    field.setAccessible(true);
                    String file = (String) field.get(locator);
                    System.out.println(FileLocator.class.getResourceAsStream(file));
                    System.out.println(FileLocator.class.getClassLoader().getResourceAsStream(file));
                } catch (NoSuchFieldException | IllegalAccessException e) {
                    throw new RuntimeException(e);
                }
            }

      @Override
      public void onFileLocalizationFailure(FileLocator locator, Throwable throwable) {

      }
});
...

Analysis Output:

...
null
sun.net.www.protocol.jar.JarURLConnection$JarURLInputStream@45ff54e6
...

Conclusions:

• [x] Using Class.getResourceAsStream(...) has failed with nullary output (first output).
• [x] Using ClassLoader.getResourceAsStream(...) has succeeded giving a Jar File Input Stream Object (second output).
• [x] The Zeta version has erroneously refactored to use the Class.getResourceAsStream(...) during solving the hassle of reverse constructor routines antipatterns.