jSnapLoader-core-API: enhancements to core api

.gitignore

@@ -10,4 +10,6 @@ bin
 
 apache-maven-3.9.3
 
-apache-maven-3.9.3-bin.tar.gz
+apache-maven-3.9.3-bin.tar.gz
+
+snaploader-examples/libs

snaploader-examples/src/main/java/com/avrsandbox/snaploader/examples/TestBasicFeatures.java

@@ -31,8 +31,10 @@
  */
 package com.avrsandbox.snaploader.examples;
 
+import java.io.IOException;
 import com.avrsandbox.snaploader.LibraryInfo;
 import com.avrsandbox.snaploader.NativeBinaryLoader;
+import com.avrsandbox.snaploader.LoadingCriterion;
 
 /**
  * Tests basic features of the {@link NativeBinaryLoader} API.
@@ -54,12 +56,11 @@ public final class TestBasicFeatures {
 
     protected static NativeBinaryLoader loader;
 
-    public static void main(String[] args) {
+    public static void main(String[] args) throws IOException {
         if (loader == null) {
             loader = new NativeBinaryLoader(libraryInfo);
         }
-        loader.setIncrementalLoadEnabled(true);
-        loader.loadLibraryIfEnabled();
+        loader.loadLibrary(LoadingCriterion.INCREMENTAL_LOADING);
         /* Native dynamic library properties */
         System.out.println("Jar Path: " + loader.getNativeDynamicLibrary().getJarPath());
         System.out.println("Library Directory: " + loader.getNativeDynamicLibrary().getLibraryDirectory());

snaploader-examples/src/main/java/com/avrsandbox/snaploader/examples/TestMultipleLoads.java

@@ -32,6 +32,7 @@
 package com.avrsandbox.snaploader.examples;
 
 import java.io.File;
+import java.io.IOException;
 
 /**
  * Tests multiple loads inside the same thread.
@@ -40,7 +41,7 @@
  */
 public final class TestMultipleLoads {
 
-    public static void main(String[] args) throws InterruptedException {
+    public static void main(String[] args) throws InterruptedException, IOException {
         TestBasicFeatures.main(args);
         new File(TestBasicFeatures.finalAbsolutePath).delete();
         Thread.sleep(5000);

snaploader/src/main/java/com/avrsandbox/snaploader/LibraryInfo.java

@@ -47,7 +47,11 @@ public final class LibraryInfo {
      * 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 extractionDir the extraction destination in absolute string format, "null" if the current [user.dir] is 
+     *                      specified as the extraction directory
      */
     public LibraryInfo(String jarPath, String directory, String baseName, String extractionDir) {
         this.jarPath = jarPath;
@@ -59,41 +63,81 @@ public LibraryInfo(String jarPath, String directory, String baseName, String ext
     /**
      * Retrieves the dynamic library basename.
      * 
-     * @return the library base-name in string
+     * @return the library base-name in string (non-null)
      */
     public String getBaseName() {
         return baseName;
     }
 
+    /**
+     * Retrieves the jar file 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 
+     *         an external jar compression
+     */
     public String getJarPath() {
         return jarPath;
     }
 
+    /**
+     * 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 
+     *         default variant-based directories are set to be used
+     */
     public String getDirectory() {
         return directory;
     }
 
+    /**
+     * Retrieves the extraction absolute directory.
+     * 
+     * @return the extraction destination in absolute string format, "null" if the current [user.dir] is 
+     *         specified as the extraction directory
+     */
     public String getExtractionDir() {
         return extractionDir;
     }
 
+    /**
+     * 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.
+     * 
+     * @param jarPath the absolute path to the jar file to locate the library to be extracted, "null" to 
+     *                use the "classpath" (aka. the stock jar)
+     */
     public void setJarPath(String jarPath) {
         this.jarPath = jarPath;
     }
 
+    /**
+     * Sets the directory to the native dynamic library inside the jar compression, "null" to use
+     * the default directories specified for each variant by {@link NativeBinaryLoader}.
+     * 
+     * @param directory the location to the native dynamic library inside the jar compression, "null"
+     *                  to use the default variant-based directories
+     */
     public void setDirectory(String directory) {
         this.directory = directory;
     }
 
     /**
      * Adjusts the library base name in a dynamic library name (lib-[basename]).
      * 
-     * @param baseName a new base-name to assign
+     * @param baseName a new base-name to assign (non-null)
      */
     public void setBaseName(final String baseName) {
         this.baseName = baseName;
     }
 
+    /**
+     * Sets the extraction directory used for extracting the native dynamic library in the 
+     * form of an absolute directory, "null" to use the current [user.dir].
+     * 
+     * @param extractionDir the absolute extraction directory to which the located library
+     *                      will be extracted to, "null" to set the extraction to the current [user.dir]
+     */
     public void setExtractionDir(String extractionDir) {
         this.extractionDir = extractionDir;
     }

snaploader/src/main/java/com/avrsandbox/snaploader/RetryCriteria.java → snaploader/src/main/java/com/avrsandbox/snaploader/LoadingCriterion.java

@@ -32,19 +32,19 @@
 package com.avrsandbox.snaploader;
 
 /**
- * Represents an extraction retry criterion type.
+ * Represents an extraction/loading criterion type.
  * 
  * @author pavl_g
  */
-enum RetryCriteria {
+public enum LoadingCriterion {
 
     /**
-     * Extracts the native binary, ignoring its existence (the newly extracted binary will replace the current file).
+     * Extracts the native binary to the extraction directory, ignoring its existence (the newly extracted binary will replace the current file).
      */
-    RETRY_WITH_CLEAN_EXTRACTION, 
+    CLEAN_EXTRACTION, 
 
     /**
-     * Extracts the native binary only if the current binary isn't present on the [user.dir].
+     * Extracts the native binary only if the current binary isn't present on the extraction directory.
      */
-    RETRY_WITH_INCREMENTAL_EXTRACTION;
+    INCREMENTAL_LOADING;
 }