Package 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 routinesSystem.load()
andSystem.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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
claimAllLinkPermission()
void
close()
Closes this native library.long
dynamicLookupFunction(String funcName)
Returns the function handle for function 'funcName'.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 using the system path.static List<String>
enumerateLibraryPaths(String windowsLibName, String unixLibName, String macOSXLibName, 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 not using the system path.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 String
isValidNativeLibraryName(String libName, boolean isLowerCaseAlready)
Comparison of prefix and suffix of the given libName's basename is performed case insensitivestatic NativeLibrary
open(String libName, boolean searchSystemPath, boolean searchSystemPathFirst, ClassLoader loader, boolean global)
Opens the given native library, assuming it has the same base name on all platforms.static NativeLibrary
open(String windowsLibName, String unixLibName, String macOSXLibName, boolean searchSystemPath, boolean searchSystemPathFirst, ClassLoader loader, boolean global)
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.void
releaseAllLinkPermission()
String
toString()
-
-
-
Method Detail
-
open
public static final NativeLibrary open(String libName, boolean searchSystemPath, boolean searchSystemPathFirst, ClassLoader loader, boolean global) throws SecurityException
Opens the given native library, assuming it has the same base name on all platforms.The
searchSystemPath
argument changes the behavior to either use the default system path or not at all.Assuming
searchSystemPath
istrue
, thesearchSystemPathFirst
argument changes the behavior to first search the default system path rather than searching it last.- Parameters:
libName
- library name, with or without prefix and suffixsearchSystemPath
- iftrue
library shall be searched in the system path (default), otherwisefalse
.searchSystemPathFirst
- iftrue
system path shall be searched first (default), rather than searching it last. ifsearchSystemPath
isfalse
this argument is ignored.loader
-ClassLoader
to locate the libraryglobal
- iftrue
allows system wide access of the loaded library, otherwise access is restricted to the process.- Returns:
NativeLibrary
instance ornull
if library could not be loaded.- Throws:
SecurityException
- if user is not granted access for the named library.- Since:
- 2.4.0
-
open
public static final NativeLibrary open(String windowsLibName, String unixLibName, String macOSXLibName, boolean searchSystemPath, boolean searchSystemPathFirst, ClassLoader loader, boolean global) throws SecurityException
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
searchSystemPath
argument changes the behavior to either use the default system path or not at all.Assuming
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.searchSystemPath
istrue
, thesearchSystemPathFirst
argument changes the behavior to first search the default system path rather than searching it last.- Parameters:
windowsLibName
- windows library name, with or without prefix and suffixunixLibName
- unix library name, with or without prefix and suffixmacOSXLibName
- mac-osx library name, with or without prefix and suffixsearchSystemPath
- iftrue
library shall be searched in the system path (default), otherwisefalse
.searchSystemPathFirst
- iftrue
system path shall be searched first (default), rather than searching it last. ifsearchSystemPath
isfalse
this argument is ignored.loader
-ClassLoader
to locate the libraryglobal
- iftrue
allows system wide access of the loaded library, otherwise access is restricted to the process.- Returns:
NativeLibrary
instance ornull
if library could not be loaded.- Throws:
SecurityException
- if user is not granted access for the named library.
-
claimAllLinkPermission
public final void claimAllLinkPermission() throws SecurityException
- Specified by:
claimAllLinkPermission
in interfaceDynamicLookupHelper
- Throws:
SecurityException
- if user is not granted access for the library set.
-
releaseAllLinkPermission
public final void releaseAllLinkPermission() throws SecurityException
- Specified by:
releaseAllLinkPermission
in interfaceDynamicLookupHelper
- Throws:
SecurityException
- if user is not granted access for the library set.
-
dynamicLookupFunction
public final long dynamicLookupFunction(String funcName) throws SecurityException
Description copied from interface:DynamicLookupHelper
Returns the function handle for function 'funcName'.- Specified by:
dynamicLookupFunction
in interfaceDynamicLookupHelper
- Throws:
SecurityException
- if user is not granted access for the library set.
-
isFunctionAvailable
public final boolean isFunctionAvailable(String funcName) throws SecurityException
Description copied from interface:DynamicLookupHelper
Queries whether function 'funcName' is available.- Specified by:
isFunctionAvailable
in interfaceDynamicLookupHelper
- Throws:
SecurityException
- if user is not granted access for the library set.
-
dynamicLookupFunctionGlobal
public final long dynamicLookupFunctionGlobal(String funcName) throws SecurityException
Looks up the given function name in all loaded libraries.- Throws:
SecurityException
- if user is not granted access for the named library.
-
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() throws SecurityException
Closes this native library. Further lookup operations are not allowed after calling this method.- Throws:
SecurityException
- if user is not granted access for the named library.
-
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 suffixisLowerCaseAlready
- 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, 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 not using the system path.
-
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 using the system path.
-
findLibrary
public static final String findLibrary(String libName, ClassLoader loader)
-
-