com.jogamp.common.os
Class NativeLibrary

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

All Implemented Interfaces:

DynamicLookupHelper

public 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

protected static boolean	DEBUG
protected static boolean	DEBUG_LOOKUP

Method Summary

void	close() Closes this native library.
long	dynamicLookupFunction(String funcName) Looks up the given function name in this native library.
static long	dynamicLookupFunctionGlobal(String funcName) Looks up the given function name in all loaded libraries.
static void	ensureNativeLibLoaded()
long	getLibraryHandle() Retrieves the low-level library handle from this NativeLibrary object.
String	getLibraryPath() Retrieves the path under which this library was opened.
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

Field Detail

DEBUG

protected static boolean DEBUG

DEBUG_LOOKUP

protected static boolean DEBUG_LOOKUP

Method Detail

toString

public String toString()

Overrides:

toString in class Object

open

public 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. Java Web Start.

open

public 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. Java Web Start.

open

public 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. 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 NativeLibrary open(String windowsLibName,
                                 String unixLibName,
                                 String macOSXLibName,
                                 boolean searchSystemPathFirst,
                                 ClassLoader loader,
                                 boolean global)

dynamicLookupFunction

public long dynamicLookupFunction(String funcName)

Looks up the given function name in this native library.

Specified by:

dynamicLookupFunction in interface DynamicLookupHelper

dynamicLookupFunctionGlobal

public static long dynamicLookupFunctionGlobal(String funcName)

Looks up the given function name in all loaded libraries.

getLibraryHandle

public 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 String getLibraryPath()

Retrieves the path under which this library was opened.

close

public void close()

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

ensureNativeLibLoaded

public static void ensureNativeLibLoaded()