Bug 1268 - DynamicLibraryBundleInfo: Add NativeLibrary's 'searchSystemPath' and 'searchSystemPathFirst' attributes

NativeLibrary can be instantiate by defining
'searchSystemPath' and 'searchSystemPathFirst' arguments,
allowing to specify the system path role while looking up the library.

Since NativeLibrary is utilized via DynamicLibraryBundleInfo upstream,
the latter interface shall allow users to specify those attributes.

3 files changed, 65 insertions, 33 deletions

diff --git a/src/java/com/jogamp/common/os/DynamicLibraryBundle.java b/src/java/com/jogamp/common/os/DynamicLibraryBundle.java
index 66a24eb..a3d6198 100644
--- a/src/java/com/jogamp/common/os/DynamicLibraryBundle.java
+++ b/src/java/com/jogamp/common/os/DynamicLibraryBundle.java
@@ -249,9 +249,12 @@ public class DynamicLibraryBundle implements DynamicLookupHelper {
         return aptr;
     }
 
-    protected static final NativeLibrary loadFirstAvailable(final List<String> libNames, final ClassLoader loader, final boolean global) throws SecurityException {
+    protected static final NativeLibrary loadFirstAvailable(final List<String> libNames,
+                                                            final boolean searchSystemPath,
+                                                            final boolean searchSystemPathFirst,
+                                                            final ClassLoader loader, final boolean global) throws SecurityException {
         for (int i=0; i < libNames.size(); i++) {
-            final NativeLibrary lib = NativeLibrary.open(libNames.get(i), loader, global);
+            final NativeLibrary lib = NativeLibrary.open(libNames.get(i), searchSystemPath, searchSystemPathFirst, loader, global);
             if (lib != null) {
                 return lib;
             }
@@ -269,7 +272,10 @@ public class DynamicLibraryBundle implements DynamicLookupHelper {
         for (i=0; i < toolLibNames.size(); i++) {
             final List<String> libNames = toolLibNames.get(i);
             if( null != libNames && libNames.size() > 0 ) {
-                lib = loadFirstAvailable(libNames, cl, info.shallLinkGlobal());
+                lib = loadFirstAvailable(libNames,
+                                         info.searchToolLibInSystemPath(),
+                                         info.searchToolLibSystemPathFirst(),
+                                         cl, info.shallLinkGlobal());
                 if ( null == lib ) {
                     if(DEBUG) {
                         System.err.println("Unable to load any Tool library of: "+libNames);
diff --git a/src/java/com/jogamp/common/os/DynamicLibraryBundleInfo.java b/src/java/com/jogamp/common/os/DynamicLibraryBundleInfo.java
index 7be5f25..01068b4 100644
--- a/src/java/com/jogamp/common/os/DynamicLibraryBundleInfo.java
+++ b/src/java/com/jogamp/common/os/DynamicLibraryBundleInfo.java
@@ -37,6 +37,21 @@ public interface DynamicLibraryBundleInfo {
     public static final boolean DEBUG = DynamicLibraryBundle.DEBUG;
 
     /**
+     * Returns {@code true} if tool libraries shall be searched in the system path <i>(default)</i>, otherwise {@code false}.
+     * @since 2.4.0
+     */
+    public boolean searchToolLibInSystemPath();
+
+    /**
+     * Returns {@code true} if system path shall be searched <i>first</i> <i>(default)</i>, rather than searching it last.
+     * <p>
+     * If {@link #searchToolLibInSystemPath()} is {@code false} the return value is ignored.
+     * </p>
+     * @since 2.4.0
+     */
+    public boolean searchToolLibSystemPathFirst();
+
+    /**
      * If a {@link SecurityManager} is installed, user needs link permissions
      * for the named libraries.
      *
diff --git a/src/java/com/jogamp/common/os/NativeLibrary.java b/src/java/com/jogamp/common/os/NativeLibrary.java
index 49e921f..2ba2581 100644
--- a/src/java/com/jogamp/common/os/NativeLibrary.java
+++ b/src/java/com/jogamp/common/os/NativeLibrary.java
@@ -138,23 +138,31 @@ public final class NativeLibrary implements DynamicLookupHelper {
   }
 
   /** Opens the given native library, assuming it has the same base
-      name on all platforms, looking first in the system's search
-      path, and in the context of the specified ClassLoader, which is
-      used to help find the library in the case of e.g. Java Web Start.
-   * @throws SecurityException if user is not granted access for the named library.
-   */
-  public static final NativeLibrary open(final String libName, final ClassLoader loader) throws SecurityException {
-    return open(libName, libName, libName, true, loader, true);
-  }
-
-  /** Opens the given native library, assuming it has the same base
-      name on all platforms, looking first in the system's search
-      path, and in the context of the specified ClassLoader, which is
-      used to help find the library in the case of e.g. Java Web Start.
+      name on all platforms.
+      <p>
+      The {@code searchSystemPath} argument changes the behavior to
+      either use the default system path or not at all.
+      </p>
+      <p>
+      Assuming {@code searchSystemPath} is {@code true},
+      the {@code searchSystemPathFirst} argument changes the behavior to first
+      search the default system path rather than searching it last.
+      </p>
+   * @param libName library name, with or without prefix and suffix
+   * @param searchSystemPath if {@code true} library shall be searched in the system path <i>(default)</i>, otherwise {@code false}.
+   * @param searchSystemPathFirst if {@code true} system path shall be searched <i>first</i> <i>(default)</i>, rather than searching it last.
+   *                              if {@code searchSystemPath} is {@code false} this argument is ignored.
+   * @param loader {@link ClassLoader} to locate the library
+   * @param global if {@code true} allows system wide access of the loaded library, otherwise access is restricted to the process.
+   * @return {@link NativeLibrary} instance or {@code null} if library could not be loaded.
    * @throws SecurityException if user is not granted access for the named library.
+   * @since 2.4.0
    */
-  public static final NativeLibrary open(final String libName, final ClassLoader loader, final boolean global) throws SecurityException {
-    return open(libName, libName, libName, true, loader, global);
+  public static final NativeLibrary open(final String libName,
+                                         final boolean searchSystemPath,
+                                         final boolean searchSystemPathFirst,
+                                         final ClassLoader loader, final boolean global) throws SecurityException {
+    return open(libName, libName, libName, searchSystemPath, searchSystemPathFirst, loader, global);
   }
 
   /** Opens the given native library, assuming it has the given base
@@ -163,7 +171,12 @@ public final class NativeLibrary implements DynamicLookupHelper {
       context of the specified ClassLoader, which is used to help find
       the library in the case of e.g. Java Web Start.
       <p>
-      The {@code searchSystemPathFirst} argument changes the behavior to first
+      The {@code searchSystemPath} argument changes the behavior to
+      either use the default system path or not at all.
+      </p>
+      <p>
+      Assuming {@code searchSystemPath} is {@code true},
+      the {@code searchSystemPathFirst} argument changes the behavior to first
       search the default system path rather than searching it last.
       </p>
       Note that we do not currently handle DSO versioning on Unix.
@@ -173,29 +186,27 @@ public final class NativeLibrary implements DynamicLookupHelper {
       ending in .so, for example .so.0), and in general if this
       dynamic loading facility is used correctly the version number
       will be irrelevant.
+   * @param windowsLibName windows library name, with or without prefix and suffix
+   * @param unixLibName unix library name, with or without prefix and suffix
+   * @param macOSXLibName mac-osx library name, with or without prefix and suffix
+   * @param searchSystemPath if {@code true} library shall be searched in the system path <i>(default)</i>, otherwise {@code false}.
+   * @param searchSystemPathFirst if {@code true} system path shall be searched <i>first</i> <i>(default)</i>, rather than searching it last.
+   *                              if {@code searchSystemPath} is {@code false} this argument is ignored.
+   * @param loader {@link ClassLoader} to locate the library
+   * @param global if {@code true} allows system wide access of the loaded library, otherwise access is restricted to the process.
+   * @return {@link NativeLibrary} instance or {@code null} if library could not be loaded.
    * @throws SecurityException if user is not granted access for the named library.
    */
   public static final NativeLibrary open(final String windowsLibName,
                                          final String unixLibName,
                                          final String macOSXLibName,
+                                         final boolean searchSystemPath,
                                          final boolean searchSystemPathFirst,
-                                         final ClassLoader loader) throws SecurityException {
-    return open(windowsLibName, unixLibName, macOSXLibName, searchSystemPathFirst, loader, true);
-  }
-
-  /**
-   * @throws SecurityException if user is not granted access for the named library.
-   */
-  public static final NativeLibrary open(final String windowsLibName,
-                                         final String unixLibName,
-                                         final String macOSXLibName,
-                                         final boolean searchSystemPathFirst,
-                                         final ClassLoader loader,
-                                         final boolean global) throws SecurityException {
+                                         final ClassLoader loader, final boolean global) throws SecurityException {
     final List<String> possiblePaths = enumerateLibraryPaths(windowsLibName,
                                                        unixLibName,
                                                        macOSXLibName,
-                                                       searchSystemPathFirst,
+                                                       searchSystemPath, searchSystemPathFirst,
                                                        loader);
     Platform.initSingleton(); // loads native gluegen-rt library