Fix UnSatisfiedLinkError when trying to load non-existent libraries

[pavly-gerges]

This PR introduces LibraryNotFoundException as a guard against directly loading non-existent file regardless of whether they are actual binaries or corrupted files.

Furthermore, the PR introduces a way to antagonize the effect of initializing a FileOutputStream by the FileExtractor API that by default creates a blank file (or opaque file); bypassing the formerly mentioned "LibraryNotFoundException".

In addition, it also introduces an example that shows how to deal with broken features using FileExtractionListener interface.

[codacy-production]

Not up to standards ⛔

🔴 Issues 2 minor

Alerts:
⚠ 2 issues (≤ 0 issues of at least minor severity)

Results:
2 new issues

Category	Results
Documentation	2 minor

View in Codacy

🟢 Metrics 140 complexity · 4 duplication

Metric	Results
Complexity	140
Duplication	4

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[pavly-gerges]

@stephengold You shouldn't catch exceptions anymore, the standard way to deal with exceptions and errors thrown from the API is to use both NativeBinaryLoadingListener and the FileExtractionListener instead. This removes the burden of trying to identify which exception or error is thrown.

EDIT:
Diagnostics could be built upon examining the causative error/exception and the calling stack from these listeners. FileExtractionListener deals with the part that is responsible for locating and extracting the binary from the compression. (NB: there exists FileLocalizingListener; it appears that it is redundant at the NativeBinaryLoader level and its instance is subjected for removal).

Btw, it appears that the techdemos that demonstrate the library features using jolt-jni are broken. Will you please consider submitting a fix for them after this PR?

[stephengold]

it appears that the techdemos that demonstrate the library features using jolt-jni are broken. Will you please consider submitting a fix for them after this PR?

Of course. I have many projects that use jSnapLoader. Can you be specific about which projects are broken and how they are broken?

[pavly-gerges]

it appears that the techdemos that demonstrate the library features using jolt-jni are broken. Will you please consider submitting a fix for them after this PR?

Of course. I have many projects that use jSnapLoader. Can you be specific about which projects are broken and how they are broken?

Please consider checking the output of the TestCpuFeatures example here on this GitHub runner workflow.

[stephengold]

I reproduced the failure seen in the "Build and Test jSnapLoader" workflow on ubuntu-latest-19 on my local machine.
I stepped through the code in a debugger.

loadBinary() throws LibraryNotFoundException at NativeBinaryLoader.java:343 because exists() returns false because jarPath is null in NativeDynamicLibrary.java:150 .

jSnapLoader/snaploader/src/main/java/electrostatic4j/snaploader/NativeBinaryLoader.java

Lines 340 to 345 in 7856370

	protected void loadBinary(NativeDynamicLibrary library, LoadingCriterion loadingCriterion) throws Exception {
	try {
	if (!nativeDynamicLibrary.exists()) {
	throw new LibraryNotFoundException("Library " + nativeDynamicLibrary.getExtractedLibrary() + " not found!");
	}
	System.load(library.getExtractedLibrary());

jSnapLoader/snaploader/src/main/java/electrostatic4j/snaploader/platform/NativeDynamicLibrary.java

Lines 149 to 154 in 7856370

	public boolean exists() {
	if (jarPath == null || libraryFile == null || directoryPath == null) {
	return false;
	}
	return new File(getExtractedLibrary()).exists();
	}

I don't yet understand jSnapLoader well enough to submit a fix.

[pavly-gerges]

I reproduced the failure seen in the "Build and Test jSnapLoader" workflow on ubuntu-latest-19 on my local machine.
I stepped through the code in a debugger.

loadBinary() throws LibraryNotFoundException at NativeBinaryLoader.java:343 because exists() returns false because jarPath is null in NativeDynamicLibrary.java:150 .

Sorry, I forgot that someone may try to load from a classpath. The jarPath has to be excluded from that validation.

[pavly-gerges]

@stephengold You shouldn't catch exceptions anymore, the standard way to deal with exceptions and errors thrown from the API is to use both NativeBinaryLoadingListener and the FileExtractionListener instead. This removes the burden of trying to identify which exception or error is thrown.

EDIT: Diagnostics could be built upon examining the causative error/exception and the calling stack from these listeners. FileExtractionListener deals with the part that is responsible for locating and extracting the binary from the compression. (NB: there exists FileLocalizingListener; it appears that it is redundant at the NativeBinaryLoader level and its instance is subjected for removal).

I re-examined the API, and decided to keep the exceptions and remove the failure functions; as the exceptions could create rate limiting or application end-points which terminate the process at a particular failure point detectable by the debuggers and JRE, unlike failure functions which are mute unless implemented...

Conclusion: the primary way to deal with errors is to catch the thrown exceptions. The only left-over failure function is the NativeBinaryLoadingListener#onLoadingFailure which is useful to extend anti-failure routines. However, not mandatory to implement.

[pavly-gerges]

@stephengold I appreciate your contributions. Expect a release very soon.

[stephengold]

Thanks. Prioer to the release, may I suggest a few other changes?

[pavly-gerges]

Thanks. Prioer to the release, may I suggest a few other changes?

Sure. You may open new issues and let's discuss them.