com.jogamp.common.os

## Class NativeLibrary

- java.lang.Object
- - com.jogamp.common.os.NativeLibrary

- All Implemented Interfaces:
    DynamicLookupHelper

      public final class NativeLibrary
      extends Object
      implements DynamicLookupHelper

  Provides low-level, relatively platform-independent access to shared ("native") libraries. The core library routines `System.load()` and `System.loadLibrary()` in general provide suitable functionality for applications using native code, but are not flexible enough to support certain kinds of glue code generation and deployment strategies. This class supports direct linking of native libraries to other shared objects not necessarily installed on the system (in particular, via the use of dlopen(RTLD_GLOBAL) on Unix platforms) as well as manual lookup of function names to support e.g. GlueGen's ProcAddressTable glue code generation style without additional supporting code needed in the generated library.

- - ### Field Summary

    - ### Fields inherited from interface com.jogamp.common.os.DynamicLookupHelper

      `DEBUG, DEBUG_LOOKUP`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes this native library.
    `long` | `dynamicLookupFunction(String funcName)` Returns the function handle for function 'funcName'.
    `static long` | `dynamicLookupFunctionGlobal(String funcName)` Looks up the given function name in all loaded libraries.
    `static List<String>` | `enumerateLibraryPaths(String windowsLibName, String unixLibName, String macOSXLibName, boolean searchSystemPathFirst, ClassLoader loader)` Given the base library names (no prefixes/suffixes) for the various platforms, enumerate the possible locations and names of the indicated native library on the system.
    `static String` | `findLibrary(String libName, ClassLoader loader)`
    `long` | `getLibraryHandle()` Retrieves the low-level library handle from this NativeLibrary object.
    `String` | `getLibraryPath()` Retrieves the path under which this library was opened.
    `boolean` | `isFunctionAvailable(String funcName)` Queries whether function 'funcName' is available.
    `static boolean` | `isFunctionAvailableGlobal(String funcName)` Looks up the given function name in all loaded libraries.
    `static String` | `isValidNativeLibraryName(String libName, boolean isLowerCaseAlready)` Comparison of prefix and suffix of the given libName's basename is performed case insensitive
    `static NativeLibrary` | `open(String libName, ClassLoader loader)` 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.
    `static NativeLibrary` | `open(String libName, ClassLoader loader, boolean global)` 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.
    `static NativeLibrary` | `open(String windowsLibName, String unixLibName, String macOSXLibName, boolean searchSystemPathFirst, ClassLoader loader)` Opens the given native library, assuming it has the given base names (no "lib" prefix or ".dll/.so/.dylib" suffix) on the Windows, Unix and Mac OS X platforms, respectively, and in the context of the specified ClassLoader, which is used to help find the library in the case of e.g.
    `static NativeLibrary` | `open(String windowsLibName, String unixLibName, String macOSXLibName, boolean searchSystemPathFirst, ClassLoader loader, boolean global)`
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### toString

          public final String toString()

      Overrides:
        `toString` in class `Object`

    - #### open

          public static final NativeLibrary open(String libName,
                           ClassLoader loader)

      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.

    - #### open

          public static final NativeLibrary open(String libName,
                           ClassLoader loader,
                           boolean global)

      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.

    - #### open

          public static final NativeLibrary open(String windowsLibName,
                           String unixLibName,
                           String macOSXLibName,
                           boolean searchSystemPathFirst,
                           ClassLoader loader)

      Opens the given native library, assuming it has the given base names (no "lib" prefix or ".dll/.so/.dylib" suffix) on the Windows, Unix and Mac OS X platforms, respectively, 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. The searchSystemPathFirst argument changes the behavior to first search the default system path rather than searching it last. Note that we do not currently handle DSO versioning on Unix. Experience with JOAL and OpenAL has shown that it is extremely problematic to rely on a specific .so version (for one thing, ClassLoader.findLibrary on Unix doesn't work with files not ending in .so, for example .so.0), and in general if this dynamic loading facility is used correctly the version number will be irrelevant.

    - #### open

          public static final NativeLibrary open(String windowsLibName,
                           String unixLibName,
                           String macOSXLibName,
                           boolean searchSystemPathFirst,
                           ClassLoader loader,
                           boolean global)

    - #### dynamicLookupFunction

          public final long dynamicLookupFunction(String funcName)

      Description copied from interface: `DynamicLookupHelper`
      Returns the function handle for function 'funcName'.
      Specified by:
        `dynamicLookupFunction` in interface `DynamicLookupHelper`

    - #### isFunctionAvailable

          public final boolean isFunctionAvailable(String funcName)

      Description copied from interface: `DynamicLookupHelper`
      Queries whether function 'funcName' is available.
      Specified by:
        `isFunctionAvailable` in interface `DynamicLookupHelper`

    - #### dynamicLookupFunctionGlobal

          public static final long dynamicLookupFunctionGlobal(String funcName)

      Looks up the given function name in all loaded libraries.

    - #### isFunctionAvailableGlobal

          public static final boolean isFunctionAvailableGlobal(String funcName)

      Looks up the given function name in all loaded libraries.

    - #### getLibraryHandle

          public final long getLibraryHandle()

      Retrieves the low-level library handle from this NativeLibrary object. On the Windows platform this is an HMODULE, and on Unix and Mac OS X platforms the void* result of calling dlopen().

    - #### getLibraryPath

          public final String getLibraryPath()

      Retrieves the path under which this library was opened.

    - #### close

          public final void close()

      Closes this native library. Further lookup operations are not allowed after calling this method.

    - #### isValidNativeLibraryName

          public static final String isValidNativeLibraryName(String libName,
                                        boolean isLowerCaseAlready)

      Comparison of prefix and suffix of the given libName's basename is performed case insensitive
      Parameters:
        `libName` - the full path library name with prefix and suffix
        `isLowerCaseAlready` - indicates if libName is already lower-case
      Returns:
        basename of libName w/o path, ie. /usr/lib/libDrinkBeer.so -> DrinkBeer on Unix systems, but null on Windows.

    - #### enumerateLibraryPaths

          public static final List<String> enumerateLibraryPaths(String windowsLibName,
                                           String unixLibName,
                                           String macOSXLibName,
                                           boolean searchSystemPathFirst,
                                           ClassLoader loader)

      Given the base library names (no prefixes/suffixes) for the various platforms, enumerate the possible locations and names of the indicated native library on the system.

    - #### findLibrary

          public static final String findLibrary(String libName,
                           ClassLoader loader)