registeredLibraries, final LibraryInfo libraryInfo) {
+ super(registeredLibraries, libraryInfo);
}
@Override
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/LibraryInfo.java b/snaploader/src/main/java/electrostatic/snaploader/LibraryInfo.java
similarity index 61%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/LibraryInfo.java
rename to snaploader/src/main/java/electrostatic/snaploader/LibraryInfo.java
index a5893f3..a1c30ff 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/LibraryInfo.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/LibraryInfo.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,13 +29,32 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader;
-import com.avrsandbox.snaploader.platform.NativeDynamicLibrary;
+package electrostatic.snaploader;
+
+import electrostatic.snaploader.platform.NativeDynamicLibrary;
/**
- * Provides a library placeholder with an adjustable baseName {@link LibraryInfo#baseName}.
- *
+ * Provides a platform-independent library placeholder with an adjustable baseName {@link LibraryInfo#baseName}
+ * grouping the common components among all platforms.
+ *
+ * Understand the API vision:
+ * The native dynamic API is composed of {@link NativeDynamicLibrary} which represents the
+ * platform-dependent entity and the {@link LibraryInfo} which represents the abstract
+ * platform-independent entity; the common components among them represent a backup
+ * on the LibraryInfo side that the API will fall back to in case the platform directory
+ * path is invalid.
+ *
+ *
+ * - ------------------------------
+ *
- (2).Abstract: LibraryInfo (Grouping common components among all platforms; thus platform-independent).
+ *
- ------------------------------
+ *
- (1).Concrete: NativeDynamicLibrary (Grouping platform-dependent components).
+ *
- ------------------------------
+ *
+ *
+ * where (1).(2) designates the runtime order.
+ *
* @author pavl_g
*/
public final class LibraryInfo {
@@ -45,13 +64,28 @@ public final class LibraryInfo {
private String baseName;
private String extractionDir;
+ /**
+ * Instantiates a library info data structure pointing to a library in the classpath.
+ *
+ * @param directory the platform-independent directory inside the compression used for locating the native dynamic library,
+ * this is used as a backup directory path
+ * in case the {@link NativeDynamicLibrary#getPlatformDirectory()} is not valid.
+ * @param baseName the library basename, for example, 'lib-basename.so'.
+ * @param extractionDir the extraction destination in absolute string format, "null" if the current [user.dir] is
+ * specified as the extraction directory
+ */
+ public LibraryInfo(String directory, String baseName, String extractionDir) {
+ this(null, directory, baseName, extractionDir);
+ }
+
/**
* Instantiates a library info data structure pointing to a library in an external jar with jarPath.
*
* @param jarPath a path to an external jar to locate the library inside, "null" to use the project jar (classpath).
- * @param directory the directory inside the compression used for locating the native dynamic library, "null" to use
- * the default directory defined by {@link NativeDynamicLibrary}.
- * @param baseName the library basename, for example: 'lib-basename.so'.
+ * @param directory the platform-independent directory inside the compression used for locating the native dynamic library,
+ * this is used as a backup directory path
+ * in case the {@link NativeDynamicLibrary#getPlatformDirectory()} is not valid.
+ * @param baseName the library basename, for example, 'lib-basename.so'.
* @param extractionDir the extraction destination in absolute string format, "null" if the current [user.dir] is
* specified as the extraction directory
*/
@@ -72,10 +106,10 @@ public String getBaseName() {
}
/**
- * Retrieves the jar file path, the jar is the compression used to locate the native dynamic library to
+ * Retrieves the jar filesystem path, the jar is the compression used to locate the native dynamic library to
* be extracted and loaded by {@link NativeBinaryLoader}.
*
- * @return the jar absolute file path in a string format, "null" if the classpath is specified instead of
+ * @return the jar absolute filesystem path in a string format, "null" if the classpath is specified instead of
* an external jar compression
*/
public String getJarPath() {
@@ -85,7 +119,7 @@ public String getJarPath() {
/**
* Retrieves the directory inside the compression used for locating the native dynamic library.
*
- * @return the path to the dynamic library file inside the compression, "null" if the
+ * @return the path to the dynamic library filesystem inside the compression, "null" if the
* default variant-based directories are set to be used
*/
public String getDirectory() {
@@ -103,10 +137,10 @@ public String getExtractionDir() {
}
/**
- * Sets the absolute path to the jar file to locate the native dynamic library to be
- * extracted and loaded, "null" to use the "classpath (the stock jar)"" to load the library file.
+ * Sets the absolute path to the jar filesystem to locate the native dynamic library to be
+ * extracted and loaded, "null" to use the "classpath (the stock jar)"" to load the library filesystem.
*
- * @param jarPath the absolute path to the jar file to locate the library to be extracted, "null" to
+ * @param jarPath the absolute path to the jar filesystem to locate the library to be extracted, "null" to
* use the "classpath" (aka. the stock jar)
*/
public void setJarPath(String jarPath) {
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/LoadingCriterion.java b/snaploader/src/main/java/electrostatic/snaploader/LoadingCriterion.java
similarity index 89%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/LoadingCriterion.java
rename to snaploader/src/main/java/electrostatic/snaploader/LoadingCriterion.java
index 76c272e..88b9a41 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/LoadingCriterion.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/LoadingCriterion.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,7 +29,8 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader;
+
+package electrostatic.snaploader;
/**
* Represents an extraction/loading criterion type.
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/NativeBinaryLoader.java b/snaploader/src/main/java/electrostatic/snaploader/NativeBinaryLoader.java
similarity index 55%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/NativeBinaryLoader.java
rename to snaploader/src/main/java/electrostatic/snaploader/NativeBinaryLoader.java
index acdacec..dc053ec 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/NativeBinaryLoader.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/NativeBinaryLoader.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,16 +29,21 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader;
+
+package electrostatic.snaploader;
import java.io.IOException;
+import java.util.Arrays;
+import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.lang.UnsatisfiedLinkError;
-import com.avrsandbox.snaploader.file.FileExtractor;
-import com.avrsandbox.snaploader.library.LibraryExtractor;
-import com.avrsandbox.snaploader.platform.NativeDynamicLibrary;
-import com.avrsandbox.snaploader.platform.NativeVariant;
+import electrostatic.snaploader.filesystem.ExtractionListener;
+import electrostatic.snaploader.filesystem.FileExtractor;
+import electrostatic.snaploader.filesystem.FileLocator;
+import electrostatic.snaploader.library.LibraryExtractor;
+import electrostatic.snaploader.platform.NativeDynamicLibrary;
+import electrostatic.snaploader.platform.util.NativeVariant;
/**
* A cross-platform utility for extracting and loading native binaries based on
@@ -52,11 +57,14 @@ public class NativeBinaryLoader {
* NativeBinaryLoader logger object.
*/
protected static final Logger logger = Logger.getLogger(NativeBinaryLoader.class.getName());
-
- /**
- * A data structure that wraps the general platform independent dynamic library info.
- */
- protected LibraryInfo libraryInfo;
+
+ protected final LibraryInfo libraryInfo;
+
+ protected List registeredLibraries;
+
+ protected NativeBinaryLoadingListener nativeBinaryLoadingListener;
+
+ protected SystemDetectionListener systemDetectionListener;
/**
* An Output stream concrete provider for library extraction.
@@ -79,43 +87,75 @@ public class NativeBinaryLoader {
protected boolean retryWithCleanExtraction;
/**
- * Instantiates a native dynamic library loader to extract and load a system specific native dynamic library.
- *
- * @param libraryInfo a data structure object representing the basic dynamic library info
+ * Instantiates a native dynamic library loader to extract and load a system-specific native dynamic library.
*/
- public NativeBinaryLoader(LibraryInfo libraryInfo) {
+ public NativeBinaryLoader(final LibraryInfo libraryInfo) {
this.libraryInfo = libraryInfo;
}
/**
- * Initializes the platform dependent native dynamic library.
+ * Instantiates a native dynamic library loader to extract and load a system-specific native dynamic library.
+ */
+ public NativeBinaryLoader(final List registeredLibraries, final LibraryInfo libraryInfo) {
+ this(libraryInfo);
+ this.registeredLibraries = registeredLibraries;
+ }
+
+ public NativeBinaryLoader registerNativeLibraries(NativeDynamicLibrary[] nativeDynamicLibraries) {
+ this.registeredLibraries = Arrays.asList(nativeDynamicLibraries);
+ return this;
+ }
+
+ /**
+ * Initializes the platform-dependent native dynamic library.
*
* @return this instance for chained invocations
* @throws UnSupportedSystemError if the OS is not supported by jSnapLoader
*/
public NativeBinaryLoader initPlatformLibrary() throws UnSupportedSystemError {
- NativeDynamicLibrary.initWithLibraryInfo(libraryInfo);
- if (NativeVariant.isLinux()) {
- setupLinuxBinary();
- } else if (NativeVariant.isWindows()) {
- setupWindowsBinary();
- } else if (NativeVariant.isMac()) {
- setupMacBinary();
+ final boolean[] isSystemFound = new boolean[] {false};
+ // search for the compatible library using the predefined predicate
+ // a predicate is a conditional statement composed of multiple propositions
+ // representing the complete system variant (OS + ARCH + VM).
+ registeredLibraries.forEach(nativeDynamicLibrary -> {
+ if (isSystemFound[0]) {
+ return;
+ }
+ // re-evaluate the library info part
+ if (libraryInfo != null) {
+ nativeDynamicLibrary.initWithLibraryInfo(libraryInfo);
+ }
+ if (nativeDynamicLibrary.getPlatformPredicate().evaluatePredicate()) {
+ this.nativeDynamicLibrary = nativeDynamicLibrary;
+ isSystemFound[0] = true;
+ }
+ });
+
+ // execute a system found listeners
+ if (isSystemFound[0]) {
+ if (systemDetectionListener != null) {
+ systemDetectionListener.onSystemFound(this, nativeDynamicLibrary);
+ }
} else {
- throw new UnSupportedSystemError(NativeVariant.NAME.getProperty(), NativeVariant.ARCH.getProperty());
+ if (systemDetectionListener != null) {
+ systemDetectionListener.onSystemNotFound(this);
+ }
+ throw new UnSupportedSystemError(NativeVariant.OS_NAME.getProperty(),
+ NativeVariant.OS_ARCH.getProperty());
}
+
return this;
}
/**
- * Extracts and loads the system and the architecture specific library from the output jar to the [user.dir]
+ * Extracts and load the system and the architecture-specific library from the output jar to the [user.dir]
* according to a loading criterion (incremental-load or clean-extract).
*
- * @param criterion the loading criterion, either {@link LoadingCriterion#INCREMENTAL_LOADING} or {@link LoadingCriterion#CLEAN_EXTRACTION}
+ * @param criterion the initial loading criterion, either {@link LoadingCriterion#INCREMENTAL_LOADING} or {@link LoadingCriterion#CLEAN_EXTRACTION}
* @return this instance for chained invocations
- * @throws IOException if the library to extract is not present in the jar file
+ * @throws IOException if the library to extract is not present in the jar filesystem
*/
- public NativeBinaryLoader loadLibrary(LoadingCriterion criterion) throws IOException {
+ public NativeBinaryLoader loadLibrary(LoadingCriterion criterion) throws IOException {
if (criterion == LoadingCriterion.INCREMENTAL_LOADING && nativeDynamicLibrary.isExtracted()) {
loadBinary(nativeDynamicLibrary);
return this;
@@ -169,46 +209,24 @@ public boolean isRetryWithCleanExtraction() {
return retryWithCleanExtraction;
}
- /**
- * Sets-up the architecture specific library {@link NativeBinaryLoader#getNativeDynamicLibrary()} for linux systems.
- *
- * @see NativeDynamicLibrary#LINUX_x86
- * @see NativeDynamicLibrary#LINUX_x86_64
- */
- protected void setupLinuxBinary() {
- if (!NativeVariant.isX86()) {
- this.nativeDynamicLibrary = NativeDynamicLibrary.LINUX_x86_64;
- } else {
- this.nativeDynamicLibrary = NativeDynamicLibrary.LINUX_x86;
- }
+ public List getRegisteredLibraries() {
+ return registeredLibraries;
}
- /**
- * Sets-up the architecture specific library {@link NativeBinaryLoader#getNativeDynamicLibrary()} for windows systems.
- *
- * @see NativeDynamicLibrary#WIN_x86
- * @see NativeDynamicLibrary#WIN_x86_64
- */
- protected void setupWindowsBinary() {
- if (!NativeVariant.isX86()) {
- this.nativeDynamicLibrary = NativeDynamicLibrary.WIN_x86_64;
- } else {
- this.nativeDynamicLibrary = NativeDynamicLibrary.WIN_x86;
- }
+ public void setNativeBinaryLoadingListener(NativeBinaryLoadingListener nativeBinaryLoadingListener) {
+ this.nativeBinaryLoadingListener = nativeBinaryLoadingListener;
}
- /**
- * Sets-up the architecture specific library {@link NativeBinaryLoader#getNativeDynamicLibrary()} for mac systems.
- *
- * @see NativeDynamicLibrary#MAC_x86
- * @see NativeDynamicLibrary#MAC_x86_64
- */
- protected void setupMacBinary() {
- if (!NativeVariant.isX86()) {
- this.nativeDynamicLibrary = NativeDynamicLibrary.MAC_x86_64;
- } else {
- this.nativeDynamicLibrary = NativeDynamicLibrary.MAC_x86;
- }
+ public NativeBinaryLoadingListener getNativeBinaryLoadingListener() {
+ return nativeBinaryLoadingListener;
+ }
+
+ public void setSystemFoundListener(SystemDetectionListener systemDetectionListener) {
+ this.systemDetectionListener = systemDetectionListener;
+ }
+
+ public SystemDetectionListener getSystemFoundListener() {
+ return systemDetectionListener;
}
/**
@@ -221,17 +239,26 @@ protected void setupMacBinary() {
protected void loadBinary(NativeDynamicLibrary library) throws IOException {
try {
/* sanity check for android java vm (the dalvik) */
- if (NativeVariant.isAndroid()) {
+ if (NativeVariant.Os.isAndroid()) {
System.loadLibrary(libraryInfo.getBaseName());
return;
}
System.load(library.getExtractedLibrary());
log(Level.INFO, "loadBinary", "Successfully loaded library: " + library.getExtractedLibrary(), null);
+ if (nativeBinaryLoadingListener != null) {
+ nativeBinaryLoadingListener.onLoadingSuccess(this);
+ }
} catch (final UnsatisfiedLinkError error) {
log(Level.SEVERE, "loadBinary", "Cannot load the dynamic library: " + library.getExtractedLibrary(), error);
+ if (nativeBinaryLoadingListener != null) {
+ nativeBinaryLoadingListener.onLoadingFailure(this);
+ }
/* Retry with clean extract */
if (isRetryWithCleanExtraction()) {
cleanExtractBinary(library);
+ if (nativeBinaryLoadingListener != null) {
+ nativeBinaryLoadingListener.onRetryCriterionExecution(this);
+ }
}
}
}
@@ -246,26 +273,50 @@ protected void loadBinary(NativeDynamicLibrary library) throws IOException {
protected void cleanExtractBinary(NativeDynamicLibrary library) throws IOException {
libraryExtractor = initializeLibraryExtractor(library);
/* CLEAR RESOURCES AND RESET OBJECTS ON-EXTRACTION */
- libraryExtractor.setExtractionListener(() -> {
- try{
- libraryExtractor.getFileLocator().close();
- libraryExtractor.close();
- libraryExtractor = null;
- log(Level.INFO, "cleanExtractBinary", "Extracted successfully to " + library.getExtractedLibrary(), null);
- loadBinary(library);
- } catch (Exception e) {
- log(Level.SEVERE, "cleanExtractBinary", "Error while closing the resources!", e);
+ libraryExtractor.setExtractionListener(new ExtractionListener() {
+ @Override
+ public void onExtractionCompleted(FileExtractor fileExtractor) {
+ try {
+ libraryExtractor.getFileLocator().close();
+ libraryExtractor.close();
+ libraryExtractor = null;
+ log(Level.INFO, "cleanExtractBinary", "Extracted successfully to " + library.getExtractedLibrary(), null);
+ loadBinary(library);
+ } catch (Exception e) {
+ log(Level.SEVERE, "cleanExtractBinary", "Error while loading the binary!", e);
+ }
+ }
+
+ @Override
+ public void onExtractionFailure(FileExtractor fileExtractor, Throwable throwable) {
+ log(Level.SEVERE, "cleanExtractBinary", "Extraction has failed!", throwable);
+ }
+
+ @Override
+ public void onExtractionFinalization(FileExtractor fileExtractor, FileLocator fileLocator) {
+ try {
+ if (fileLocator != null &&
+ fileLocator.getFileInputStream() != null) {
+ fileLocator.close();
+ }
+ if (fileExtractor != null &&
+ fileExtractor.getFileOutputStream() != null) {
+ fileExtractor.close();
+ }
+ } catch (IOException e) {
+ log(Level.SEVERE, "cleanExtractBinary", "Error while closing the resources!", e);
+ }
}
});
libraryExtractor.extract();
}
/**
- * Initializes a file extrator object if the file extractor object associated with this loader isnot defined.
+ * Initializes a filesystem extrator object if the filesystem extractor object associated with this loader isnot defined.
*
* @param library the native dynamic library to load
* @return a new FileExtractor object that represents an output stream provider
- * @throws IOException if the jar file to be located is not found, or if the extraction destination is not found
+ * @throws IOException if the jar filesystem to be located is not found, or if the extraction destination is not found
*/
protected FileExtractor initializeLibraryExtractor(NativeDynamicLibrary library) throws IOException {
if (library.getJarPath() != null) {
diff --git a/snaploader/src/main/java/electrostatic/snaploader/NativeBinaryLoadingListener.java b/snaploader/src/main/java/electrostatic/snaploader/NativeBinaryLoadingListener.java
new file mode 100644
index 0000000..992c995
--- /dev/null
+++ b/snaploader/src/main/java/electrostatic/snaploader/NativeBinaryLoadingListener.java
@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package electrostatic.snaploader;
+
+import electrostatic.snaploader.platform.NativeDynamicLibrary;
+
+/**
+ * Provides executable functions binding the user applications to
+ * the loading lifecycle.
+ *
+ * Note: All the functions on this interface are dispatched
+ * by the {@link NativeBinaryLoader#loadBinary(NativeDynamicLibrary)}.
+ *
+ * @author pavl_g
+ */
+public interface NativeBinaryLoadingListener {
+
+ /**
+ * Dispatched when loading the system-specific binary has succeeded.
+ *
+ * @param nativeBinaryLoader the dispatching loader
+ */
+ void onLoadingSuccess(NativeBinaryLoader nativeBinaryLoader);
+
+ /**
+ * Dispatched when loading the system-specific binary has failed.
+ *
+ * @param nativeBinaryLoader the dispatching loader
+ */
+ void onLoadingFailure(NativeBinaryLoader nativeBinaryLoader);
+
+ /**
+ * Dispatched when loading the system-specific binary has failed,
+ * and the retry criterion has been executed.
+ *
+ * Note: this dispatching function could be overridden to add
+ * your own anti-failure mechanisms (i.e., Retry Criterion).
+ *
+ * @param nativeBinaryLoader the dispatching loader
+ */
+ void onRetryCriterionExecution(NativeBinaryLoader nativeBinaryLoader);
+}
diff --git a/snaploader/src/main/java/electrostatic/snaploader/SystemDetectionListener.java b/snaploader/src/main/java/electrostatic/snaploader/SystemDetectionListener.java
new file mode 100644
index 0000000..95d64bf
--- /dev/null
+++ b/snaploader/src/main/java/electrostatic/snaploader/SystemDetectionListener.java
@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package electrostatic.snaploader;
+
+import electrostatic.snaploader.platform.NativeDynamicLibrary;
+
+/**
+ * Provides executable functions binding the user applications to
+ * the system detection lifecycle.
+ *
+ * Note: All the functions on this interface are dispatched
+ * by the {@link NativeBinaryLoader#loadLibrary(LoadingCriterion)}.
+ *
+ * @author pavl_g
+ */
+public interface SystemDetectionListener {
+
+ /**
+ * Dispatched when a system predicate is evaluated as true against the
+ * system in this runtime.
+ *
+ * @param nativeBinaryLoader the dispatching loader.
+ * @param nativeDynamicLibrary the native library object with an evaluated predicate.
+ */
+ void onSystemFound(NativeBinaryLoader nativeBinaryLoader, NativeDynamicLibrary nativeDynamicLibrary);
+
+ /**
+ * Dispatched when all the registered system predicates are evaluated as false
+ * against the current system in this runtime. In this case, a {@link UnSupportedSystemError}
+ * is also thrown on the user application environment.
+ *
+ * @param nativeBinaryLoader the dispatching loader
+ */
+ void onSystemNotFound(NativeBinaryLoader nativeBinaryLoader);
+}
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/UnSupportedSystemError.java b/snaploader/src/main/java/electrostatic/snaploader/UnSupportedSystemError.java
similarity index 74%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/UnSupportedSystemError.java
rename to snaploader/src/main/java/electrostatic/snaploader/UnSupportedSystemError.java
index 83e9a60..4bccc5b 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/UnSupportedSystemError.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/UnSupportedSystemError.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,31 +29,25 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader;
+
+package electrostatic.snaploader;
/**
- * A business error of type {@link UnsatisfiedLinkError} to indicate an un-supported system.
- *
+ * A business error of type {@link UnsatisfiedLinkError} to indicate an unsupported system.
*
- * This error is thrown when the user tries to run the library on another operating system rather than the supported systems:
- *
- * - Linux - x86 - x86_64
- * - Windows - x86 - x86_64
- * - Mac - x86 - x86_64
- * - Android - intel32 - intel64 - arm32 - arm64
- *
- *
+ * This error is thrown when all the user-defined platform predicates are not met!
+ *
* @author pavl_g
*/
public class UnSupportedSystemError extends UnsatisfiedLinkError {
/**
- * Thrown if the system detects an un-supported system binaries of the current OS.
+ * Thrown if the system detects an unsupported system binaries of the current OS.
*
* @param os the current operating system (os) name
* @param arch the current operating system (os) processor architecture
*/
public UnSupportedSystemError(final String os, final String arch) {
- super("System " + os + "_" + arch + " isn't supported yet !");
+ super("Platform of OS(" + os + ") and ARCH(" + arch + ") isn't supported yet!");
}
}
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/file/ConcurrentFileExtractor.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/ConcurrentFileExtractor.java
similarity index 77%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/file/ConcurrentFileExtractor.java
rename to snaploader/src/main/java/electrostatic/snaploader/filesystem/ConcurrentFileExtractor.java
index c84e661..846eb02 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/file/ConcurrentFileExtractor.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/ConcurrentFileExtractor.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,14 +29,15 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.file;
+
+package electrostatic.snaploader.filesystem;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.concurrent.locks.ReentrantLock;
/**
- * A thread-safe implementation of the file extractor API.
+ * A thread-safe implementation of the filesystem extractor API.
*
* @author pavl_g
*/
@@ -48,18 +49,18 @@ public class ConcurrentFileExtractor extends FileExtractor {
protected final ReentrantLock lock = new ReentrantLock();
/**
- * Instantiates a thread-safe file extractor instance.
+ * Instantiates a thread-safe filesystem extractor instance.
*
- * @param fileLocator locates a file inside a zip compression
- * @param destination an absolute file path representing the extraction destination file
- * @throws FileNotFoundException if the destination file path is not found
+ * @param fileLocator locates a filesystem inside a zip compression
+ * @param destination an absolute filesystem path representing the extraction destination filesystem
+ * @throws FileNotFoundException if the destination filesystem path is not found
*/
public ConcurrentFileExtractor(FileLocator fileLocator, String destination) throws FileNotFoundException {
super(fileLocator, destination);
}
/**
- * Instantiates an empty file extractor instance.
+ * Instantiates an empty filesystem extractor instance.
*/
protected ConcurrentFileExtractor() {
super();
diff --git a/snaploader/src/main/java/electrostatic/snaploader/filesystem/ExtractionListener.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/ExtractionListener.java
new file mode 100644
index 0000000..d72c477
--- /dev/null
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/ExtractionListener.java
@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package electrostatic.snaploader.filesystem;
+
+/**
+ * Provides executable functions ensuring tight binding the user applications to
+ * the extraction lifecycle.
+ *
+ * Note: All the functions on this interface are dispatched
+ * by the {@link FileExtractor#extract()}.
+ *
+ * Warning: this listener interface is an essential component of
+ * developing custom system loaders; as it requires freeing the native stream resources
+ * manually through the {@link ExtractionListener#onExtractionFinalization(FileExtractor, FileLocator)}.
+ * If not freeing the resources with this interface was attained, then a try-with resources could be used.
+ *
+ * @author pavl_g
+ */
+public interface ExtractionListener {
+
+ /**
+ * Dispatched when the extraction process is completed.
+ *
+ * @param fileExtractor the extractor in-command.
+ */
+ void onExtractionCompleted(FileExtractor fileExtractor);
+
+ /**
+ * Dispatched when the extraction process has failed with a throwable
+ * component.
+ *
+ * @param fileExtractor the extractor in-command.
+ * @param throwable the throwable captured from the FileExtractor API.
+ */
+ void onExtractionFailure(FileExtractor fileExtractor, Throwable throwable);
+
+ /**
+ * Dispatched when the extraction process is finalized, at this point, manually
+ * freeing active resources should be attained.
+ *
+ * @param fileExtractor the extractor in-command.
+ * @param fileLocator the file locator used by the extractor to locate files inside compressions.
+ */
+ void onExtractionFinalization(FileExtractor fileExtractor, FileLocator fileLocator);
+}
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/file/FileExtractor.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/FileExtractor.java
similarity index 54%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/file/FileExtractor.java
rename to snaploader/src/main/java/electrostatic/snaploader/filesystem/FileExtractor.java
index f1a07dd..9b41737 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/file/FileExtractor.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/FileExtractor.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,7 +29,8 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.file;
+
+package electrostatic.snaploader.filesystem;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
@@ -38,14 +39,14 @@
import java.io.OutputStream;
/**
- * Extracts a file from a zip compression to a destination file.
+ * Extracts a filesystem from a zip compression to a destination filesystem.
*
* @author pavl_g
*/
public class FileExtractor implements OutputStreamProvider {
/**
- * Locates a file inside a zip compression.
+ * Locates a filesystem inside a zip compression.
*/
protected FileLocator fileLocator;
@@ -60,17 +61,18 @@ public class FileExtractor implements OutputStreamProvider {
protected ExtractionListener extractionListener;
/**
- * An absolute path for the destination file of the extraction process.
+ * An absolute path for the destination filesystem of the extraction process.
*/
protected String destination;
- private static final int EOF = -1; /* End-of-file */
+
+ private static final int EOF = -1; /* End-of-filesystem */
/**
- * Instantiates a file extractor object with a file locator and a destination file.
+ * Instantiates a filesystem extractor object with a filesystem locator and a destination filesystem.
*
- * @param fileLocator locates a file inside a zip compression
- * @param destination an absolute file path representing the extraction destination file
- * @throws FileNotFoundException if the destination file path is not found
+ * @param fileLocator locates a filesystem inside a zip compression
+ * @param destination an absolute filesystem path representing the extraction destination filesystem
+ * @throws FileNotFoundException if the destination filesystem path is not found
*/
public FileExtractor(FileLocator fileLocator, String destination) throws FileNotFoundException {
this.fileLocator = fileLocator;
@@ -78,28 +80,55 @@ public FileExtractor(FileLocator fileLocator, String destination) throws FileNot
}
/**
- * Instantiates an empty file extractor.
+ * Instantiates an empty filesystem extractor.
*/
protected FileExtractor() {
}
/**
- * Commands and Extracts the specified file to the specified destination file.
- *
- * @throws IOException if the input/output streams has failed or an interrupted I/O operation has occured
+ * Commands and Extract the specified filesystem to the specified destination filesystem.
+ *
+ * Warning: this function leaks buffered streams; this vision was attained for freedom of use,
+ * but the user application must keep in mind that stream closure and resources release must be
+ * attained either through the extraction completed and failure listeners, or through a try-with
+ * resources.
+ *
+ * @throws IOException if the input/output streams has failed or an interrupted I/O operation has occurred.
+ * @throws FileNotFoundException if the file locator has failed to locate the file inside the compression
+ * for the extraction process.
*/
- public void extract() throws IOException {
+ public void extract() throws IOException, FileNotFoundException {
try {
- InputStream libraryStream = fileLocator.getFileInputStream();
+ /* uses buffered streams */
+ /* buffered byte streams provide a constant memory allocation
+ * according to the file size in bytes,
+ * this constant memory allocation is then treated
+ * as a pipe; either a unidirectional (simplex) or a bidirectional (duplex)
+ * unlike the unbuffered streams, which polls byte streams from an online
+ * pipe, and allocate memory according to the active bytes manipulated
+ * by the pipeline. */
+ fileLocator.validateFileLocalization();
+ InputStream fileStream = fileLocator.getFileInputStream();
+
/* Extracts the shipped native files */
- final byte[] buffer = new byte[libraryStream.available()];
- for (int bytes = 0; bytes != EOF; bytes = libraryStream.read(buffer)) {
+ /* Allocate a byte buffer for the buffered streams */
+ final byte[] buffer = new byte[fileStream.available()];
+
+ for (int bytes = 0; bytes != EOF; bytes = fileStream.read(buffer)) {
/* use the bytes as the buffer length to write valid data */
fileOutputStream.write(buffer, 0, bytes);
}
+ if (extractionListener != null) {
+ extractionListener.onExtractionCompleted(this);
+ }
+ } catch (Exception e) {
+ if (extractionListener != null) {
+ extractionListener.onExtractionFailure(this, e);
+ }
+ // release the native resources anyway!
} finally {
if (extractionListener != null) {
- extractionListener.onExtractionCompleted();
+ extractionListener.onExtractionFinalization(this, fileLocator);
}
}
}
@@ -121,7 +150,7 @@ public InputStreamProvider getFileLocator() {
}
/**
- * Sets the extraction listener action to dispatch the {@link ExtractionListener#onExtractionCompleted()}
+ * Sets the extraction listener action to dispatch the {@link ExtractionListener#onExtractionCompleted(FileExtractor)}
* when the extraction task is completed.
*
* @param extractionListener an implementation object of the extraction listener dispatched when the
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/file/ExtractionListener.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/FileLocalizingListener.java
similarity index 55%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/file/ExtractionListener.java
rename to snaploader/src/main/java/electrostatic/snaploader/filesystem/FileLocalizingListener.java
index c2f7256..2f13bc8 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/file/ExtractionListener.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/FileLocalizingListener.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,18 +29,35 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.file;
+
+package electrostatic.snaploader.filesystem;
/**
- * A thread safe listener for the extraction process.
- *
- * @see FileExtractor#extract()
+ * Provides executable functions by the {@link FileLocator#validateFileLocalization()}
+ * to enable the binding of user applications with the file locator interface.
+ *
* @author pavl_g
+ * @see FileLocator#validateFileLocalization()
+ * @see FileExtractor#extract()
*/
-public interface ExtractionListener {
+public interface FileLocalizingListener {
+
+ /**
+ * Dispatched whenever the file input stream is valid, hence the specified
+ * file can be localized.
+ *
+ * @param locator the associated file locator object.
+ * @see FileLocator#validateFileLocalization()
+ */
+ void onFileLocalizationSuccess(FileLocator locator);
/**
- * Dispatched by the {@link FileExtractor#extract()} when the extraction process is completed.
+ * Dispatched whenever the file input stream is invalid, hence the specified
+ * file cannot be localized for the extraction process.
+ *
+ * @param locator the associated file locator object.
+ * @param throwable the throwable object, typically indicating a failure
+ * to locate the file inside the compression.
*/
- void onExtractionCompleted();
+ void onFileLocalizationFailure(FileLocator locator, Throwable throwable);
}
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/file/FileLocator.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/FileLocator.java
similarity index 53%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/file/FileLocator.java
rename to snaploader/src/main/java/electrostatic/snaploader/filesystem/FileLocator.java
index ff30418..dd45372 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/file/FileLocator.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/FileLocator.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,34 +29,43 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.file;
+package electrostatic.snaploader.filesystem;
+
+import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;
/**
- * An Input Stream Provider that locates a file inside a zip compression and provides an
- * input stream object for the located file entry.
+ * An Input Stream Provider that locates a filesystem inside a zip compression and provides an
+ * input stream object for the located filesystem entry.
*
* @author pavl_g
*/
public class FileLocator implements InputStreamProvider {
/**
- * The input stream associated with the located file.
+ * The input stream associated with the located filesystem.
*/
protected InputStream fileInputStream;
/**
- * Locates a file inside an external zip compression, the zip file is defined as a {@link ZipFile} object and
- * the locatable file is defined as a {@link ZipEntry} object.
- *
- * This object leaks an input stream.
+ * An interface object to provide the file-localizing process with a command-state pattern;
+ * binding the user application interface with the file localizing lifecycle.
+ */
+ protected FileLocalizingListener fileLocalizingListener;
+
+ /**
+ * Locates a filesystem inside an external zip compression, the zip filesystem is defined as a {@link ZipFile} object and
+ * the locatable filesystem is defined as a {@link ZipEntry} object.
+ *
+ * Warning: This object leaks a buffered stream, either use try-with-resources, or handle your
+ * memory manually!
*
- * @param directory the absolute path for the external jar file
- * @param filePath the path to the file to be extracted
+ * @param directory the absolute path for the external jar filesystem
+ * @param filePath the path to the filesystem to be extracted
* @param compressionType the type of the zip compression, ZIP or JAR
*
* @throws IOException if the jar to be located is not found or an interrupted I/O exception has occured
@@ -68,11 +77,33 @@ public FileLocator(String directory, String filePath, ZipCompressionType compres
}
/**
- * Instantiates an empty file locator object.
+ * Instantiates an empty filesystem locator object.
*/
protected FileLocator() {
}
+ /**
+ * Validates the file localization process inside the compression.
+ *
+ * @throws FileNotFoundException if the localization of the file inside
+ * the specified compression has failed.
+ */
+ public void validateFileLocalization() throws FileNotFoundException {
+ if (fileInputStream != null) {
+ if (fileLocalizingListener != null) {
+ fileLocalizingListener.onFileLocalizationSuccess(this);
+ }
+ } else {
+ final FileNotFoundException fileNotFoundException =
+ new FileNotFoundException("File locator has failed to locate the file inside the compression!");
+
+ if (fileLocalizingListener != null) {
+ fileLocalizingListener.onFileLocalizationFailure(this, fileNotFoundException);
+ }
+ throw fileNotFoundException;
+ }
+ }
+
@Override
public InputStream getFileInputStream() {
return fileInputStream;
@@ -83,4 +114,9 @@ public void close() throws IOException {
fileInputStream.close();
fileInputStream = null;
}
+
+ @Override
+ public void setFileLocalizingListener(FileLocalizingListener fileLocalizingListener) {
+ this.fileLocalizingListener = fileLocalizingListener;
+ }
}
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/file/InputStreamProvider.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/InputStreamProvider.java
similarity index 73%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/file/InputStreamProvider.java
rename to snaploader/src/main/java/electrostatic/snaploader/filesystem/InputStreamProvider.java
index 313f192..e5dcd78 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/file/InputStreamProvider.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/InputStreamProvider.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,12 +29,13 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.file;
+
+package electrostatic.snaploader.filesystem;
import java.io.InputStream;
/**
- * Defines an interface for an input stream provider that locates a file and provides
+ * Defines an interface for an input stream provider that locates a filesystem and provides
* an {@link InputStream} object.
*
* @author pavl_g
@@ -42,9 +43,17 @@
public interface InputStreamProvider extends AutoCloseable {
/**
- * Retrieves the input stream object associated with this file entry.
+ * Retrieves the input stream object associated with this filesystem entry.
*
- * @return an input stream object for this located file
+ * @return an input stream object for this located filesystem
*/
InputStream getFileInputStream();
+
+ /**
+ * Sets the file localizing listener interface object to bind the user application
+ * to the file localizing lifecycle.
+ *
+ * @param fileLocalizingListener an implementation object of the file localizing listener
+ */
+ void setFileLocalizingListener(FileLocalizingListener fileLocalizingListener);
}
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/file/OutputStreamProvider.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/OutputStreamProvider.java
similarity index 79%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/file/OutputStreamProvider.java
rename to snaploader/src/main/java/electrostatic/snaploader/filesystem/OutputStreamProvider.java
index b291150..40441d2 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/file/OutputStreamProvider.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/OutputStreamProvider.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,30 +29,30 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.file;
+
+package electrostatic.snaploader.filesystem;
import java.io.OutputStream;
/**
- * Defines an interface for an output stream provider to locate and extract a file from a zip compression,
- * the output stream provider object is associated with an input stream provider object that locates this file.
+ * Defines an interface for an output stream provider to locate and extract a filesystem from a zip compression;
+ * the output stream provider object is associated with an input stream provider object that locates this filesystem.
*
* @author pavl_g
*/
public interface OutputStreamProvider extends AutoCloseable {
/**
- * Retrieves the input stream provider object (the file locator object).
+ * Retrieves the input stream provider object (the filesystem locator object).
*
- * @return an input stream provider object that is the file locator object
+ * @return an input stream provider object that is the filesystem locator object
*/
InputStreamProvider getFileLocator();
/**
- * Retrieves the output stream object associated with this provider, the output stream is
- * associated with the
+ * Retrieves the output stream object associated with this provider.
*
- * @return an output stream provider object to extract the file
+ * @return an output stream provider object to extract the filesystem
*/
OutputStream getFileOutputStream();
-}
+}
\ No newline at end of file
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/file/ZipCompressionType.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/ZipCompressionType.java
similarity index 90%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/file/ZipCompressionType.java
rename to snaploader/src/main/java/electrostatic/snaploader/filesystem/ZipCompressionType.java
index 1162538..8ad422d 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/file/ZipCompressionType.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/ZipCompressionType.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,7 +29,8 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.file;
+
+package electrostatic.snaploader.filesystem;
import java.io.IOException;
import java.util.jar.JarFile;
@@ -71,9 +72,9 @@ public enum ZipCompressionType {
/**
* Creates a new zip compression object by its path based on the compression symbol.
*
- * @param directory the zip-file absolute path
+ * @param directory the zip-filesystem absolute path
* @return a new zip compression object based on the compression type specified by the compression symbol
- * @throws IOException if the zip file is not found, or an interrupted I/O operation has occured
+ * @throws IOException if the zip filesystem is not found, or an interrupted I/O operation has occured
*/
protected ZipFile createNewCompressionObject(String directory) throws IOException {
if (compressionObject == null) {
diff --git a/snaploader/src/main/java/electrostatic/snaploader/filesystem/package-info.java b/snaploader/src/main/java/electrostatic/snaploader/filesystem/package-info.java
new file mode 100644
index 0000000..c3301e0
--- /dev/null
+++ b/snaploader/src/main/java/electrostatic/snaploader/filesystem/package-info.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * Provides I/O stream provider interfaces for {@link electrostatic.snaploader.library.LibraryLocator} and {@link electrostatic.snaploader.library.LibraryExtractor}.
+ */
+package electrostatic.snaploader.filesystem;
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/library/LibraryExtractor.java b/snaploader/src/main/java/electrostatic/snaploader/library/LibraryExtractor.java
similarity index 68%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/library/LibraryExtractor.java
rename to snaploader/src/main/java/electrostatic/snaploader/library/LibraryExtractor.java
index 0360fcb..88f24e9 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/library/LibraryExtractor.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/library/LibraryExtractor.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,11 +29,12 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.library;
+
+package electrostatic.snaploader.library;
import java.io.IOException;
-import com.avrsandbox.snaploader.file.ConcurrentFileExtractor;
-import com.avrsandbox.snaploader.file.FileExtractor;
+import electrostatic.snaploader.filesystem.ConcurrentFileExtractor;
+import electrostatic.snaploader.filesystem.FileExtractor;
/**
* Represents a thread-safe dynamic library (.so, .dll, .dylib) extractor based on the {@link FileExtractor}.
@@ -43,24 +44,24 @@
public class LibraryExtractor extends ConcurrentFileExtractor {
/**
- * Instantiates a native dynamic library extractor with a jar path, library path and extract destination file path.
+ * Instantiates a native dynamic library extractor with a jar path, library path and extract destination filesystem path.
*
- * @param jarPath an absolute path to the jar file containing the library
- * @param libraryPath the path of the library inside the jar file
- * @param destination the extraction destination file path
- * @throws IOException if the jar file to be located is not found, or if the extraction destination is not found
+ * @param jarPath an absolute path to the jar filesystem containing the library
+ * @param libraryPath the path of the library inside the jar filesystem
+ * @param destination the extraction destination filesystem path
+ * @throws IOException if the jar filesystem to be located is not found, or if the extraction destination is not found
*/
public LibraryExtractor(String jarPath, String libraryPath, String destination) throws IOException {
super(new LibraryLocator(jarPath, libraryPath), destination);
}
/**
- * Instantiates a native dynamic library extractor with a library path and an extract destination file path. This
- * object locates a dynmaic native library inside the stock jar file based on a classpath input stream.
+ * Instantiates a native dynamic library extractor with a library path and an extract destination filesystem path. This
+ * object locates a dynamic native library inside the stock jar filesystem based on a classpath input stream.
*
- * @param libraryPath the path of the library inside the jar file
- * @param destination the extraction destination file path
- * @throws IOException if the jar file to be located is not found, or if the extraction destination is not found
+ * @param libraryPath the path of the library inside the jar filesystem
+ * @param destination the extraction destination filesystem path
+ * @throws IOException if the jar filesystem to be located is not found, or if the extraction destination is not found
*/
public LibraryExtractor(String libraryPath, String destination) throws IOException {
super(new LibraryLocator(libraryPath), destination);
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/library/LibraryLocator.java b/snaploader/src/main/java/electrostatic/snaploader/library/LibraryLocator.java
similarity index 81%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/library/LibraryLocator.java
rename to snaploader/src/main/java/electrostatic/snaploader/library/LibraryLocator.java
index 0c22fee..1a71580 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/library/LibraryLocator.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/library/LibraryLocator.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,26 +29,27 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.library;
+
+package electrostatic.snaploader.library;
import java.io.IOException;
import java.util.jar.JarFile;
import java.util.zip.ZipEntry;
-import com.avrsandbox.snaploader.file.ZipCompressionType;
-import com.avrsandbox.snaploader.file.FileLocator;
+import electrostatic.snaploader.filesystem.ZipCompressionType;
+import electrostatic.snaploader.filesystem.FileLocator;
/**
- * Locates a library inside a jar file, the probable source for the native dynamic libraries to extract and load.
+ * Locates a library inside a jar filesystem, the probable source for the native dynamic libraries to extract and load.
*
* @author pavl_g
*/
public class LibraryLocator extends FileLocator {
/**
- * Locates the library inside the stock jar file.
+ * Locates the library inside the stock jar filesystem.
* This object leaks an input stream.
*
- * @param libraryPath the path to the dynamic native library inside that jar file
+ * @param libraryPath the path to the dynamic native library inside that jar filesystem
*/
public LibraryLocator(String libraryPath) {
this.fileInputStream = LibraryLocator.class.getClassLoader().getResourceAsStream(libraryPath);
@@ -59,8 +60,8 @@ public LibraryLocator(String libraryPath) {
* the native library is defined as a {@link ZipEntry}.
* This object leaks an input stream.
*
- * @param directory the absolute path for the external jar file
- * @param libraryPath the path to the dynamic native library inside that jar file
+ * @param directory the absolute path for the external jar filesystem
+ * @param libraryPath the path to the dynamic native library inside that jar filesystem
* @throws IOException if the jar to be located is not found or an interrupt I/O operation has occured
*/
public LibraryLocator(String directory, String libraryPath) throws IOException {
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/file/package-info.java b/snaploader/src/main/java/electrostatic/snaploader/library/package-info.java
similarity index 79%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/file/package-info.java
rename to snaploader/src/main/java/electrostatic/snaploader/library/package-info.java
index 54da040..bf2f195 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/file/package-info.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/library/package-info.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -31,6 +31,6 @@
*/
/**
- * Provides I/O stream provider interfaces for {@link com.avrsandbox.snaploader.library.LibraryLocator} and {@link com.avrsandbox.snaploader.library.LibraryExtractor}.
+ * Provides specialized implementation for {@link electrostatic.snaploader.filesystem.FileLocator} and {@link electrostatic.snaploader.filesystem.FileExtractor}.
*/
-package com.avrsandbox.snaploader.file;
+package electrostatic.snaploader.library;
\ No newline at end of file
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/package-info.java b/snaploader/src/main/java/electrostatic/snaploader/package-info.java
similarity index 87%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/package-info.java
rename to snaploader/src/main/java/electrostatic/snaploader/package-info.java
index 6848181..21d25d4 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/package-info.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/package-info.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -33,4 +33,4 @@
/**
* Provides a loader api for the library, the loader extracts and loads the system specific binary on the runtime.
*/
-package com.avrsandbox.snaploader;
+package electrostatic.snaploader;
diff --git a/snaploader/src/main/java/electrostatic/snaploader/platform/NativeDynamicLibrary.java b/snaploader/src/main/java/electrostatic/snaploader/platform/NativeDynamicLibrary.java
new file mode 100644
index 0000000..7f6b965
--- /dev/null
+++ b/snaploader/src/main/java/electrostatic/snaploader/platform/NativeDynamicLibrary.java
@@ -0,0 +1,205 @@
+/*
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package electrostatic.snaploader.platform;
+
+import java.io.File;
+import electrostatic.snaploader.LibraryInfo;
+import electrostatic.snaploader.NativeBinaryLoader;
+import electrostatic.snaploader.platform.util.NativeVariant;
+import electrostatic.snaploader.platform.util.PlatformPredicate;
+import electrostatic.snaploader.platform.util.PropertiesProvider;
+
+/**
+ * Represents a filesystem to a platform-specific binary inside
+ * a compression with a predicate; if the predicate evaluates, the
+ * library is loaded by the {@link NativeBinaryLoader}.
+ *
+ * @author pavl_g
+ */
+public class NativeDynamicLibrary {
+
+ /**
+ * The absolute path for the Jar file to
+ * extract and load the library from.
+ */
+ protected String jarPath;
+
+ /**
+ * The library path inside the compression (i.e., Jar file).
+ */
+ protected String platformDirectory;
+
+ /**
+ * A designator for the library name with the platform extension
+ * (basename + extension).
+ */
+ protected String libraryFile;
+
+ /**
+ * A designator for the extraction directory of the
+ * native library.
+ */
+ protected String extractionDir;
+
+ /**
+ * The platform-specific predicate; that if evaluated as
+ * true, the respective native library object will be
+ * assigned by the {@link NativeBinaryLoader} to be extracted
+ * and loaded.
+ */
+ protected PlatformPredicate platformPredicate;
+
+ /**
+ * Creates a Native dynamic library from a relative directory and a library filesystem.
+ *
+ * @param platformDirectory the library directory inside the jar compression, "null" for the default library directory.
+ * @param libraryFile the full library name including the platform extension which if assigned
+ * as "null", it will make the loader rely on the library info to obtain
+ * the full library name.
+ * @param platformPredicate the predicate to test against; that if evaluated as true, the native library will be selected
+ * to be loaded by the native loader
+ */
+ public NativeDynamicLibrary(String platformDirectory, String libraryFile,
+ PlatformPredicate platformPredicate) {
+ this(platformDirectory, platformPredicate);
+ this.libraryFile = libraryFile;
+ }
+
+ /**
+ * Creates a Native dynamic library from a relative directory and a library filesystem.
+ *
+ * @param platformDirectory the library directory inside the jar compression, "null" for the default library directory.
+ * @param platformPredicate the predicate to test against; that if evaluated as true, the native library will be selected
+ * to be loaded by the native loader
+ */
+ public NativeDynamicLibrary(String platformDirectory,
+ PlatformPredicate platformPredicate) {
+ this.platformDirectory = platformDirectory;
+ this.platformPredicate = platformPredicate;
+ }
+
+ /**
+ * Initializes the native dynamic library with the library info.
+ *
+ * @param libraryInfo wraps abstract data representing the native library
+ */
+ public void initWithLibraryInfo(LibraryInfo libraryInfo) {
+
+ /* Initializes the library file if it's not initialized by the user */
+ if (libraryFile == null) {
+ // default values for library prefix
+ // and library extensions
+ String libraryPrefix = "lib";
+ String libraryExtension = ".so";
+
+ // reassign according to the operating system environment
+ if (NativeVariant.Os.isMac()) {
+ libraryExtension = ".dylib";
+ } else if (NativeVariant.Os.isWindows()) {
+ libraryExtension = ".dll";
+ libraryPrefix = ""; // selectively remove the prefixed value on Windows
+ }
+
+ libraryFile = libraryPrefix + libraryInfo.getBaseName() + libraryExtension;
+ }
+
+ /* Initializes the library jar path to locate before extracting, "null" to use the classpath */
+ jarPath = libraryInfo.getJarPath();
+
+ /* Initializes the library with an extraction path, "null" to extract to the current user directory */
+ extractionDir = libraryInfo.getExtractionDir();
+
+ /* Fallback initializes the library directory within the jar from the library-info */
+ if (platformDirectory == null) {
+ platformDirectory = libraryInfo.getDirectory();
+ }
+ }
+
+ /**
+ * Retrieves the absolute path for the jar compression as specified by the {@link LibraryInfo} API.
+ *
+ * @return a string representing the absolute path to the jar compression containing the dynamic libraries
+ */
+ public String getJarPath() {
+ return jarPath;
+ }
+
+ /**
+ * Retrieves the native library directory inside the jar compression.
+ *
+ * @return a string representing the location of the native dynamic library to be loaded
+ */
+ public String getPlatformDirectory() {
+ return platformDirectory;
+ }
+
+ /**
+ * Retrieves the library path within the jar compression.
+ *
+ * @return a string representing the library path within the jar compression
+ */
+ public String getCompressedLibrary() {
+ return platformDirectory + PropertiesProvider.ZIP_FILE_SEPARATOR.getSystemProperty() + libraryFile;
+ }
+
+ /**
+ * Retrieves the absolute path for the native library as supposed to be on the extraction directory.
+ *
+ * @return the absolute path composed of the extraction directory and the library name and system-specific extension
+ */
+ public String getExtractedLibrary() {
+ if (extractionDir != null) {
+ return extractionDir + PropertiesProvider.FILE_SEPARATOR.getSystemProperty() + libraryFile;
+ }
+ return PropertiesProvider.USER_DIR.getSystemProperty() +
+ PropertiesProvider.FILE_SEPARATOR.getSystemProperty() + libraryFile;
+ }
+
+ /**
+ * Tests whether the native library is extracted to the specified extraction directory.
+ *
+ * @return true if the library has been extracted before, false otherwise
+ */
+ public boolean isExtracted() {
+ return new File(getExtractedLibrary()).exists();
+ }
+
+ /**
+ * Retrieves the platform-specific predicate to test against.
+ *
+ * @return the predefined platform-specific predicate object.
+ */
+ public PlatformPredicate getPlatformPredicate() {
+ return platformPredicate;
+ }
+}
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/platform/package-info.java b/snaploader/src/main/java/electrostatic/snaploader/platform/package-info.java
similarity index 87%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/platform/package-info.java
rename to snaploader/src/main/java/electrostatic/snaploader/platform/package-info.java
index 3b0e98b..97748eb 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/platform/package-info.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/platform/package-info.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -33,4 +33,4 @@
/**
* Provides platform-dependent specifications to handle the abstract interface for the jSnapLoader.
*/
-package com.avrsandbox.snaploader.platform;
\ No newline at end of file
+package electrostatic.snaploader.platform;
\ No newline at end of file
diff --git a/snaploader/src/main/java/electrostatic/snaploader/platform/util/DefaultDynamicLibraries.java b/snaploader/src/main/java/electrostatic/snaploader/platform/util/DefaultDynamicLibraries.java
new file mode 100644
index 0000000..c7a7b6d
--- /dev/null
+++ b/snaploader/src/main/java/electrostatic/snaploader/platform/util/DefaultDynamicLibraries.java
@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package electrostatic.snaploader.platform.util;
+
+import electrostatic.snaploader.platform.NativeDynamicLibrary;
+
+/**
+ * Defines default helper objects for plug-and-play usage.
+ *
+ * In order to add more predicated variants, extend
+ * this namespace class and add more static objects.
+ *
+ * @author pavl_g
+ */
+public class DefaultDynamicLibraries {
+
+ /**
+ * Represents a linux x86 binary with 64-bit instruction set.
+ */
+ public static NativeDynamicLibrary LINUX_X86_64 =
+ new NativeDynamicLibrary("lib/linux/x86-64", PlatformPredicate.LINUX_X86_64);
+
+ /**
+ * Represents a linux x86 binary with 32-bit instruction set.
+ */
+ public static NativeDynamicLibrary LINUX_X86 =
+ new NativeDynamicLibrary("lib/linux/x86", PlatformPredicate.LINUX_X86);
+
+ /**
+ * Represents a mac x86 binary with 64-bit instruction set.
+ */
+ public static NativeDynamicLibrary MAC_X86_64 =
+ new NativeDynamicLibrary("lib/macos/x86-64", PlatformPredicate.MACOS_X86_64);
+
+ /**
+ * Represents a mac x86 binary with 32-bit instruction set.
+ */
+ public static NativeDynamicLibrary MAC_X86 =
+ new NativeDynamicLibrary("lib/macos/x86", PlatformPredicate.MACOS_X86);
+
+ /**
+ * Represents a windows x86 binary with 64-bit instruction set.
+ */
+ public static NativeDynamicLibrary WIN_X86_64 =
+ new NativeDynamicLibrary("lib/windows/x86-64", PlatformPredicate.WIN_X86_64);
+
+ /**
+ * Represents a windows x86 binary with 32-bit instruction set.
+ */
+ public static NativeDynamicLibrary WIN_X86 =
+ new NativeDynamicLibrary("lib/windows/x86", PlatformPredicate.WIN_X86);
+
+ private DefaultDynamicLibraries() {
+ }
+}
diff --git a/snaploader/src/main/java/electrostatic/snaploader/platform/util/NativeVariant.java b/snaploader/src/main/java/electrostatic/snaploader/platform/util/NativeVariant.java
new file mode 100644
index 0000000..ac27eaf
--- /dev/null
+++ b/snaploader/src/main/java/electrostatic/snaploader/platform/util/NativeVariant.java
@@ -0,0 +1,263 @@
+/*
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package electrostatic.snaploader.platform.util;
+
+/**
+ * Wraps objects for native variant constituents (OS + ARCH={CPU + INSTRUCT_SET} + VM).
+ *
+ *
+ * Use the following list to build your platform predicates:
+ *
+ * - x86: 32-bit x86 architecture
+ * - x86_64: 64-bit x86 architecture, often referred to as amd64
+ * - amd64: Another name for x86_64
+ * - i386: Another designation for 32-bit x86 architecture
+ * - arm: ARM architecture
+ * - aarch64: 64-bit ARM architecture
+ * - sparc: SPARC architecture
+ * - sparcv9: 64-bit SPARC architecture
+ * - ppc: PowerPC architecture
+ * - ppc64: 64-bit PowerPC architecture
+ * - ppc64le: 64-bit PowerPC architecture, little-endian
+ * - s390: IBM System/390 architecture
+ * - s390x: 64-bit IBM System/390 architecture
+ * - riscv32: 32-bit RISC-V architecture
+ * - riscv64: 64-bit RISC-V architecture
+ *
+ *
+ * @author pavl_g
+ */
+public enum NativeVariant {
+
+ /**
+ * The Operating system name property for this variant.
+ */
+ OS_NAME(System.getProperty("os.name")),
+
+ /**
+ * The Operating system architecture.
+ */
+ OS_ARCH(System.getProperty("os.arch")),
+
+ /**
+ * The current java virtual machine.
+ */
+ JVM(System.getProperty("java.vm.name"));
+
+ private static final String Linux = "Linux";
+ private static final String Windows = "Windows";
+ private static final String Mac = "Mac";
+ private static final String Dalvik = "Dalvik";
+
+ private final String property;
+
+ NativeVariant(final String property) {
+ this.property = property;
+ }
+
+ /**
+ * A namespace class exposing the Operating System Propositions.
+ */
+ public static final class Os {
+ private Os() {
+ }
+ /**
+ * Tests whether the current system is a Linux.
+ *
+ * @return true if the current OS is a Linux, false otherwise.
+ */
+ public static boolean isLinux() {
+ return NativeVariant.OS_NAME.getProperty().contains(NativeVariant.Linux);
+ }
+
+ /**
+ * Tests whether the current system is a Windows.
+ *
+ * @return true if the current OS is a Windows, false otherwise.
+ */
+ public static boolean isWindows() {
+ return NativeVariant.OS_NAME.getProperty().contains(NativeVariant.Windows);
+ }
+
+ /**
+ * Tests whether the current system is a Mac.
+ *
+ * @return true if the current OS is a Mac, false otherwise.
+ */
+ public static boolean isMac() {
+ return NativeVariant.OS_NAME.getProperty().contains(NativeVariant.Mac);
+ }
+
+ /**
+ * Tests whether the current system is an Android.
+ *
+ * @return true if the current OS is an Android, false otherwise.
+ */
+ public static boolean isAndroid() {
+ return JVM.getProperty().contains(NativeVariant.Dalvik);
+ }
+ }
+
+ /**
+ * A namespace class exposing the CPU propositions.
+ */
+ public static final class Cpu {
+ private Cpu() {
+ }
+
+ /**
+ * Tests whether the current environment is running
+ * on a RISC-V (reduced instruction-set) CPU, typically plain RISC-V means 32-bit, and
+ * with the added predicate {@link Cpu#is64()} adds the 64-bit
+ * predicate.
+ *
+ * @return true if the current runtime is operating on a RISC-V
+ */
+ public static boolean isRiscV() {
+ return JVM.getProperty().contains("riscv");
+ }
+
+ /**
+ * Tests whether the current runtime environment is operating
+ * on a Sparc CPU, typically plain Sparc means 32-bit.
+ *
+ * @return true if the current runtime is operating on a Sparc.
+ * @see Cpu#isSparcV9()
+ */
+ public static boolean isSparc() {
+ return JVM.getProperty().contains("sparc");
+ }
+
+ /**
+ * Tests whether the current runtime environment is operating
+ * on a SparcV9 CPU, the typical 64-bit version of the Sparc CPU.
+ *
+ * @return true if the current runtime environment is running on a SparcV9.
+ * @see Cpu#isSparc()
+ */
+ public static boolean isSparcV9() {
+ return JVM.getProperty().contains("sparcv9");
+ }
+
+ /**
+ * Tests whether the current runtime environment is operating
+ * on a PowerPc CPU, typically Ppc only means 32-bit.
+ *
+ * @return true if the current runtime environment is operating on a PPC.
+ * @see Cpu#isPpc64le()
+ */
+ public static boolean isPpc() {
+ return JVM.getProperty().contains("ppc");
+ }
+
+ /**
+ * Tests whether the current runtime environment is operating
+ * on a PowerPc CPU, typically the 64-bit version with the little
+ * endian byte-order (i.e., le architecture).
+ *
+ * @return true if the current runtime environment is operating on a PPC-64-bit-le.
+ * @see Cpu#isPpc()
+ */
+ public static boolean isPpc64le() {
+ return JVM.getProperty().contains("ppc64le");
+ }
+
+ /**
+ * Tests whether the current runtime environment is operating on an
+ * IBM System/390 CPU, typically plain s390 means the 32-bit version.
+ *
+ * @return true if the current runtime environment is operating on an IBM System/390.
+ * @see Cpu#isS390x()
+ */
+ public static boolean isS390() {
+ return JVM.getProperty().contains("s390");
+ }
+
+ /**
+ * Tests whether the current runtime environment is operating on an
+ * IBM System/390 CPU, typically the 64-bit version.
+ *
+ * @return true if the current runtime environment is operating on an IBM System/390-64-bit.
+ * @see Cpu#isS390()
+ */
+ public static boolean isS390x() {
+ return JVM.getProperty().contains("s390x");
+ }
+
+ /**
+ * Tests whether the current system architecture is a 64-bit chipset
+ * (NOT APPLICABLE TO ALL CPUs).
+ *
+ * @return true if the current OS architecture is a 64-bit chipset, false otherwise.
+ */
+ public static boolean is64() {
+ return OS_ARCH.getProperty().contains("64");
+ }
+
+ /**
+ * Tests whether the current system architecture is of an x86 chipset, typically 32-bit intel chipsets.
+ *
+ * @return true if the current OS architecture is of an x86 chipset, false otherwise.
+ */
+ public static boolean isX86() {
+ return OS_ARCH.getProperty().contains("x86") || OS_ARCH.getProperty().contains("i386");
+ }
+
+ /**
+ * Tests whether the current CPU vendor is an AMD vendor (e.g., x86_64 Intel Chipset).
+ *
+ * @return true if the current CPU vendor is an AMD vendor.
+ */
+ public static boolean isAMD() {
+ return OS_ARCH.getProperty().contains("amd");
+ }
+
+ /**
+ * Tests whether the current CPU vendor is an ARM vendor (e.g., Broadcom Chipset).
+ *
+ * @return true if the current CPU vendor is an ARM vendor.
+ */
+ public static boolean isARM() {
+ return OS_ARCH.getProperty().contains("arm") || OS_ARCH.getProperty().contains("aarch");
+ }
+ }
+
+ /**
+ * Retrieves the data of this native variant property.
+ *
+ * @return the specified property object in a string format.
+ */
+ public String getProperty() {
+ return property;
+ }
+}
diff --git a/snaploader/src/main/java/electrostatic/snaploader/platform/util/PlatformPredicate.java b/snaploader/src/main/java/electrostatic/snaploader/platform/util/PlatformPredicate.java
new file mode 100644
index 0000000..922d7f4
--- /dev/null
+++ b/snaploader/src/main/java/electrostatic/snaploader/platform/util/PlatformPredicate.java
@@ -0,0 +1,145 @@
+/*
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package electrostatic.snaploader.platform.util;
+
+/**
+ * Wraps a platform-specific predicate; that if all of its propositions evaluated
+ * as true, the respective platform library will be assigned to be extracted
+ * and loaded by the loader object in-command.
+ *
+ * @author pavl_g
+ */
+public final class PlatformPredicate {
+
+ /**
+ * Alias object for Linux on X86 Chipset.
+ */
+ public static final PlatformPredicate LINUX_X86 = new PlatformPredicate(NativeVariant.Os.isLinux() && NativeVariant.Cpu.isX86());
+
+ /**
+ * Alias object for Linux on X86-64 Chipset.
+ */
+ public static final PlatformPredicate LINUX_X86_64 = new PlatformPredicate(NativeVariant.Os.isLinux() && NativeVariant.Cpu.isAMD() && NativeVariant.Cpu.is64());
+
+ /**
+ * Alias object for Linux on arm-32 Chipset.
+ */
+ public static final PlatformPredicate LINUX_ARM_32 = new PlatformPredicate(NativeVariant.Os.isLinux() && NativeVariant.Cpu.isARM());
+
+ /**
+ * Alias object for Linux on arm-64 Chipset.
+ */
+ public static final PlatformPredicate LINUX_ARM_64 = new PlatformPredicate(NativeVariant.Os.isLinux() && NativeVariant.Cpu.isARM() && NativeVariant.Cpu.is64());
+
+ /**
+ * Alias object for Linux on RiscV-32 Chipset.
+ */
+ public static final PlatformPredicate LINUX_RISC_V_32 = new PlatformPredicate(NativeVariant.Os.isLinux() && NativeVariant.Cpu.isRiscV());
+
+ /**
+ * Alias object for Linux on RiscV-64 Chipset.
+ */
+ public static final PlatformPredicate LINUX_RISC_V_64 = new PlatformPredicate(NativeVariant.Os.isLinux() && NativeVariant.Cpu.isRiscV() && NativeVariant.Cpu.is64());
+
+ /**
+ * Alias object for MacOSX on X86 Chipset.
+ */
+ public static final PlatformPredicate MACOS_X86 = new PlatformPredicate(NativeVariant.Os.isMac() && NativeVariant.Cpu.isX86());
+
+ /**
+ * Alias object for MacOSX on X86-64 Chipset.
+ */
+ public static final PlatformPredicate MACOS_X86_64 = new PlatformPredicate(NativeVariant.Os.isMac() && NativeVariant.Cpu.isX86() && NativeVariant.Cpu.is64());
+
+ /**
+ * Alias object for MacOSX on arm-32 Chipset.
+ */
+ public static final PlatformPredicate MACOS_ARM_32 = new PlatformPredicate(NativeVariant.Os.isMac() && NativeVariant.Cpu.isARM());
+
+ /**
+ * Alias object for MacOSX on arm-64 Chipset.
+ */
+ public static final PlatformPredicate MACOS_ARM_64 = new PlatformPredicate(NativeVariant.Os.isMac() && NativeVariant.Cpu.isARM() && NativeVariant.Cpu.is64());
+
+ /**
+ * Alias object for Windows on X86 Chipset.
+ */
+ public static final PlatformPredicate WIN_X86 = new PlatformPredicate(NativeVariant.Os.isWindows() && NativeVariant.Cpu.isX86());
+
+ /**
+ * Alias object for Windows on X86-64 Chipset.
+ */
+ public static final PlatformPredicate WIN_X86_64 = new PlatformPredicate(NativeVariant.Os.isWindows() && NativeVariant.Cpu.isAMD() && NativeVariant.Cpu.is64());
+
+ /**
+ * Alias object for Windows on arm-32 Chipset.
+ */
+ public static final PlatformPredicate WIN_ARM_32 = new PlatformPredicate(NativeVariant.Os.isWindows() && NativeVariant.Cpu.isARM());
+
+ /**
+ * Alias object for Windows on arm-64 Chipset.
+ */
+ public static final PlatformPredicate WIN_ARM_64 = new PlatformPredicate(NativeVariant.Os.isWindows() && NativeVariant.Cpu.isARM() && NativeVariant.Cpu.is64());
+
+ /**
+ * Alias object for Windows on RiscV-32 Chipset.
+ */
+ public static final PlatformPredicate WIN_RISC_V_32 = new PlatformPredicate(NativeVariant.Os.isWindows() && NativeVariant.Cpu.isRiscV());
+
+ /**
+ * Alias object for Windows on RiscV-64 Chipset.
+ */
+ public static final PlatformPredicate WIN_RISC_V_64 = new PlatformPredicate(NativeVariant.Os.isWindows() && NativeVariant.Cpu.isRiscV());
+
+ private final boolean predicate;
+
+ /**
+ * Instantiates a platform-specific predicate object
+ * that wraps a predicate composed of multiple
+ * propositions appended by logical operations.
+ *
+ * @param predicate a raw boolean predicate to evaluate against
+ */
+ public PlatformPredicate(boolean predicate) {
+ this.predicate = predicate;
+ }
+
+ /**
+ * Evaluate the propositions of the predefined platform-predicate.
+ *
+ * @return true if the
+ */
+ public boolean evaluatePredicate() {
+ return predicate;
+ }
+}
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/platform/PropertiesProvider.java b/snaploader/src/main/java/electrostatic/snaploader/platform/util/PropertiesProvider.java
similarity index 88%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/platform/PropertiesProvider.java
rename to snaploader/src/main/java/electrostatic/snaploader/platform/util/PropertiesProvider.java
index cd447d9..ea135b4 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/platform/PropertiesProvider.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/platform/util/PropertiesProvider.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -29,7 +29,8 @@
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
-package com.avrsandbox.snaploader.platform;
+
+package electrostatic.snaploader.platform.util;
/**
* Provides platform-dependent system properties for the current running machine.
@@ -51,12 +52,12 @@ public enum PropertiesProvider {
USER_HOME(System.getProperty("user.home")),
/**
- * Provides a string representation for the platform-dependent file separator.
+ * Provides a string representation for the platform-dependent filesystem separator.
*/
FILE_SEPARATOR(System.getProperty("file.separator")),
/**
- * Provides a string representation for the file separator of the Zip specification.
+ * Provides a string representation for the filesystem separator of the Zip specification.
*/
ZIP_FILE_SEPARATOR("/"),
diff --git a/snaploader/src/main/java/com/avrsandbox/snaploader/library/package-info.java b/snaploader/src/main/java/electrostatic/snaploader/platform/util/package-info.java
similarity index 82%
rename from snaploader/src/main/java/com/avrsandbox/snaploader/library/package-info.java
rename to snaploader/src/main/java/electrostatic/snaploader/platform/util/package-info.java
index 51c2661..90c82d8 100644
--- a/snaploader/src/main/java/com/avrsandbox/snaploader/library/package-info.java
+++ b/snaploader/src/main/java/electrostatic/snaploader/platform/util/package-info.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2023, AvrSandbox, jSnapLoader
+ * Copyright (c) 2023-2024, The Electrostatic-Sandbox Distributed Simulation Framework, jSnapLoader
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -13,7 +13,7 @@
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
- * * Neither the name of 'AvrSandbox' nor the names of its contributors
+ * * Neither the name of 'Electrostatic-Sandbox' nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
@@ -31,6 +31,6 @@
*/
/**
- * Provides specialized implementation for {@link com.avrsandbox.snaploader.file.FileLocator} and {@link com.avrsandbox.snaploader.file.FileExtractor}.
+ * Provides utilities to handle platform-specific binaries.
*/
-package com.avrsandbox.snaploader.library;
\ No newline at end of file
+package electrostatic.snaploader.platform.util;
\ No newline at end of file
## Quick Building and running examples:
```bash
@@ -30,8 +45,13 @@ BUILD SUCCESSFUL in 1s
4 actionable tasks: 2 executed, 2 up-to-date
```
-## Appendix
-Features:
+## Plug-and-play usage:
+
+
+## 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] Extract native libraries from the stock jar library (classpath).
- [x] Locate external jars and extract native libraries from them.
@@ -39,8 +59,10 @@ Features:
- [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.
- [ ] Extract automatically based on the application name and version.
-Documentation-list:
-- [ ] Architecture paradigm.
+### Documentation-list:
+- [x] Architecture paradigm.
- [x] API documentation.
+- [ ] Java-Doc page.
diff --git a/architecture/architectural-paradigm.png b/architecture/architectural-paradigm.png
new file mode 100644
index 0000000..e71c299
Binary files /dev/null and b/architecture/architectural-paradigm.png differ
diff --git a/architecture/architectural-paradigm.puml b/architecture/architectural-paradigm.puml
new file mode 100644
index 0000000..b21e306
--- /dev/null
+++ b/architecture/architectural-paradigm.puml
@@ -0,0 +1,104 @@
+@startuml
+'https://plantuml.com/component-diagram
+
+'Structural composition
+package platform {
+ package util {
+ component NativeVariant #22AADD {
+ component [Os] {
+ }
+ component [Cpu] {
+ }
+ }
+ component PropertiesProvider {
+ }
+ component PlatformPredicate {
+ }
+ }
+ component NativeDynamicLibrary <