public final class NativeLibrary extends Object implements DynamicLookupHelper
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.DEBUG, DEBUG_LOOKUP
Modifier and Type | Method and 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 insensitive
|
static 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() |
public static final NativeLibrary open(String libName, boolean searchSystemPath, boolean searchSystemPathFirst, ClassLoader loader, boolean global) throws SecurityException
The searchSystemPath
argument changes the behavior to
either use the default system path or not at all.
Assuming searchSystemPath
is true
,
the searchSystemPathFirst
argument changes the behavior to first
search the default system path rather than searching it last.
libName
- library name, with or without prefix and suffixsearchSystemPath
- if true
library shall be searched in the system path (default), otherwise false
.searchSystemPathFirst
- if true
system path shall be searched first (default), rather than searching it last.
if searchSystemPath
is false
this argument is ignored.loader
- ClassLoader
to locate the libraryglobal
- if true
allows system wide access of the loaded library, otherwise access is restricted to the process.NativeLibrary
instance or null
if library could not be loaded.SecurityException
- if user is not granted access for the named library.public static final NativeLibrary open(String windowsLibName, String unixLibName, String macOSXLibName, boolean searchSystemPath, boolean searchSystemPathFirst, ClassLoader loader, boolean global) throws SecurityException
The searchSystemPath
argument changes the behavior to
either use the default system path or not at all.
Assuming searchSystemPath
is true
,
the searchSystemPathFirst
argument changes the behavior to first
search the default system path rather than searching it last.
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
- if true
library shall be searched in the system path (default), otherwise false
.searchSystemPathFirst
- if true
system path shall be searched first (default), rather than searching it last.
if searchSystemPath
is false
this argument is ignored.loader
- ClassLoader
to locate the libraryglobal
- if true
allows system wide access of the loaded library, otherwise access is restricted to the process.NativeLibrary
instance or null
if library could not be loaded.SecurityException
- if user is not granted access for the named library.public final void claimAllLinkPermission() throws SecurityException
claimAllLinkPermission
in interface DynamicLookupHelper
SecurityException
- if user is not granted access for the library set.public final void releaseAllLinkPermission() throws SecurityException
releaseAllLinkPermission
in interface DynamicLookupHelper
SecurityException
- if user is not granted access for the library set.public final long dynamicLookupFunction(String funcName) throws SecurityException
DynamicLookupHelper
dynamicLookupFunction
in interface DynamicLookupHelper
SecurityException
- if user is not granted access for the library set.public final boolean isFunctionAvailable(String funcName) throws SecurityException
DynamicLookupHelper
isFunctionAvailable
in interface DynamicLookupHelper
SecurityException
- if user is not granted access for the library set.public final long dynamicLookupFunctionGlobal(String funcName) throws SecurityException
SecurityException
- if user is not granted access for the named library.public final long getLibraryHandle()
public final String getLibraryPath()
public final void close() throws SecurityException
SecurityException
- if user is not granted access for the named library.public static final String isValidNativeLibraryName(String libName, boolean isLowerCaseAlready)
libName
- the full path library name with prefix and suffixisLowerCaseAlready
- indicates if libName is already lower-casepublic static final List<String> enumerateLibraryPaths(String windowsLibName, String unixLibName, String macOSXLibName, ClassLoader loader)
public static final List<String> enumerateLibraryPaths(String windowsLibName, String unixLibName, String macOSXLibName, boolean searchSystemPathFirst, ClassLoader loader)
public static final String findLibrary(String libName, ClassLoader loader)