|
GlueGen v2.6.0-rc-20250712
GlueGen, Native Binding Generator for Java (public API).
|
Provides low-level, relatively platform-independent access to shared ("native") libraries. More...
Classes | |
| class | LibPath |
| Native Library Path Specification. More... | |
Public Member Functions | |
| final String | toString () |
| final void | claimAllLinkPermission () throws SecurityException |
| final void | releaseAllLinkPermission () throws SecurityException |
| final long | dynamicLookupFunction (final String funcName) throws SecurityException |
| Returns the function handle for function 'funcName'. More... | |
| final boolean | isFunctionAvailable (final String funcName) throws SecurityException |
| Queries whether function 'funcName' is available. More... | |
| final long | dynamicLookupFunctionGlobal (final String funcName) throws SecurityException |
| Looks up the given function name in all loaded libraries. More... | |
| final long | getLibraryHandle () |
| Retrieves the low-level library handle from this NativeLibrary object. More... | |
| final boolean | isOpen () |
| Returns true if library is loaded and open, otherwise false. More... | |
| final String | getLibraryPath () |
| Retrieves the path under which this library was opened. More... | |
| final LibPath | getLibPath () |
| Retrieves the path under which this library was opened. More... | |
| final String | getNativeLibraryPath () |
Returns the native library path of the opened native getLibraryHandle(), maybe null if not supported by OS. More... | |
| final void | close () throws SecurityException |
| Closes this native library. More... | |
| void | claimAllLinkPermission () throws SecurityException |
| void | releaseAllLinkPermission () throws SecurityException |
| boolean | isOpen () |
| Returns true if library is loaded and open, otherwise false. More... | |
| long | dynamicLookupFunction (String funcName) throws SecurityException |
| Returns the function handle for function 'funcName'. More... | |
| boolean | isFunctionAvailable (String funcName) throws SecurityException |
| Queries whether function 'funcName' is available. More... | |
Static Public Member Functions | |
| static final String | getSystemEnvLibraryPathVarname () |
| Returns the system's environment variable name used for the dynamic linker to resolve library locations, e.g. More... | |
| static final String | getSystemEnvLibraryPaths () |
Returns a system paths separated with File#pathSeparator, from the getSystemEnvLibraryPathVarname() variable. More... | |
| static final String | getJogAmpPrimaryLibraryPaths () |
Returns JogAmp's primary library path jogamp.primary.library.path separated with File#pathSeparator. More... | |
| static final NativeLibrary | open (final String libName, final boolean searchOSSystemPath, final boolean searchSystemPathFirst, final ClassLoader loader, final boolean global) throws SecurityException |
| Opens the given native library, assuming it has the same base name on all platforms. More... | |
| static final NativeLibrary | open (final String libName, final boolean searchOSSystemPath, final boolean searchSystemPathFirst, final ClassLoader loader, final boolean global, final String symbolName) throws SecurityException |
| Opens the given native library, assuming it has the same base name on all platforms. More... | |
| static final NativeLibrary | open (final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchOSSystemPath, final boolean searchSystemPathFirst, final ClassLoader loader, final boolean global, final String symbolName) 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. More... | |
| static final String | isValidNativeLibraryName (final String libName, final boolean isLowerCaseAlready) |
| Comparison of prefix and suffix of the given libName's basename is performed case insensitive More... | |
| static final List< LibPath > | enumerateLibraryPaths (final String windowsLibName, final String unixLibName, final String macOSXLibName, final 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 OS system path. More... | |
| static final List< LibPath > | enumerateLibraryPaths (final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPathFirst, final 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 OS system path. More... | |
| static final String | findLibrary (final String libName, final ClassLoader loader) |
Additional Inherited Members | |
Static Public Attributes inherited from com.jogamp.common.os.DynamicLookupHelper | |
| static final boolean | DEBUG = Debug.debug("NativeLibrary") |
| static final boolean | DEBUG_LOOKUP = Debug.debug("NativeLibrary.Lookup") |
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.
System search's behavior depends on searchOSSystemPath and searchSystemPathFirst.
PATHDYLD_LIBRARY_PATHLD_LIBRARY_PATH/Library/Frameworks//System/Library/Frameworks/searchSystemPathFirstsearchOSSystemPathOS System Search abovefindLibrary mechanismsun.boot.library.path!searchSystemPathFirstsun.boot.library.pathfindLibrary mechanismsearchOSSystemPathOS System Search abovejogamp.primary.library.pathFile.pathseparatorsearchSystemPathFirstSystem Search Resolution abovejava.library.pathuser.diruser.dir + File.separator + natives + File.separator + PlatformPropsImpl.os_and_arch!searchSystemPathFirstSystem Search Resolution above Definition at line 112 of file NativeLibrary.java.
| final void com.jogamp.common.os.NativeLibrary.claimAllLinkPermission | ( | ) | throws SecurityException |
| SecurityException | if user is not granted access for the library set. |
Implements com.jogamp.common.os.DynamicLookupHelper.
Definition at line 480 of file NativeLibrary.java.
| final void com.jogamp.common.os.NativeLibrary.close | ( | ) | throws SecurityException |
Closes this native library.
Further lookup operations are not allowed after calling this method.
| SecurityException | if user is not granted access for the named library. |
Definition at line 569 of file NativeLibrary.java.
| final long com.jogamp.common.os.NativeLibrary.dynamicLookupFunction | ( | final String | funcName | ) | throws SecurityException |
Returns the function handle for function 'funcName'.
| SecurityException | if user is not granted access for the library set. |
Implements com.jogamp.common.os.DynamicLookupHelper.
Definition at line 489 of file NativeLibrary.java.
| final long com.jogamp.common.os.NativeLibrary.dynamicLookupFunctionGlobal | ( | final String | funcName | ) | throws SecurityException |
Looks up the given function name in all loaded libraries.
| SecurityException | if user is not granted access for the named library. |
Definition at line 507 of file NativeLibrary.java.
|
static |
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 OS system path.
Definition at line 634 of file NativeLibrary.java.
|
static |
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 OS system path.
Definition at line 623 of file NativeLibrary.java.
|
static |
|
static |
Returns JogAmp's primary library path jogamp.primary.library.path separated with File#pathSeparator.
Definition at line 283 of file NativeLibrary.java.
| final LibPath com.jogamp.common.os.NativeLibrary.getLibPath | ( | ) |
Retrieves the path under which this library was opened.
Definition at line 556 of file NativeLibrary.java.
| final long com.jogamp.common.os.NativeLibrary.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().
Definition at line 543 of file NativeLibrary.java.
| final String com.jogamp.common.os.NativeLibrary.getLibraryPath | ( | ) |
Retrieves the path under which this library was opened.
Definition at line 551 of file NativeLibrary.java.
| final String com.jogamp.common.os.NativeLibrary.getNativeLibraryPath | ( | ) |
Returns the native library path of the opened native getLibraryHandle(), maybe null if not supported by OS.
Definition at line 561 of file NativeLibrary.java.
|
static |
Returns a system paths separated with File#pathSeparator, from the getSystemEnvLibraryPathVarname() variable.
Definition at line 273 of file NativeLibrary.java.
|
static |
Returns the system's environment variable name used for the dynamic linker to resolve library locations, e.g.
Definition at line 268 of file NativeLibrary.java.
| final boolean com.jogamp.common.os.NativeLibrary.isFunctionAvailable | ( | final String | funcName | ) | throws SecurityException |
Queries whether function 'funcName' is available.
| SecurityException | if user is not granted access for the library set. |
Implements com.jogamp.common.os.DynamicLookupHelper.
Definition at line 497 of file NativeLibrary.java.
| final boolean com.jogamp.common.os.NativeLibrary.isOpen | ( | ) |
Returns true if library is loaded and open, otherwise false.
Implements com.jogamp.common.os.DynamicLookupHelper.
Definition at line 548 of file NativeLibrary.java.
|
static |
Comparison of prefix and suffix of the given libName's basename is performed case insensitive
| libName | the full path library name with prefix and suffix |
| isLowerCaseAlready | indicates if libName is already lower-case |
Definition at line 594 of file NativeLibrary.java.
|
static |
Opens the given native library, assuming it has the same base name on all platforms.
The searchOSSystemPath argument changes the behavior to either use the default system path or not at all.
Assuming searchOSSystemPath 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 suffix |
| searchOSSystemPath | 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 searchOSSystemPath is true this includes the order of the OS system path as well. |
| loader | ClassLoader to locate the library |
| global | 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. |
Definition at line 350 of file NativeLibrary.java.
|
static |
Opens the given native library, assuming it has the same base name on all platforms.
The searchOSSystemPath argument changes the behavior to either use the default system path or not at all.
Assuming searchOSSystemPath 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 suffix |
| searchOSSystemPath | if true library shall be searched in the OS system path (default), otherwise false. |
| searchSystemPathFirst | if true system path shall be searched first (default), rather than searching it last. if searchOSSystemPath is true this includes the order of the OS system path as well. |
| loader | ClassLoader to locate the library |
| global | if true allows system wide access of the loaded library, otherwise access is restricted to the process. |
| symbolName | optional symbol name for an OS which requires the symbol's address to retrieve the path of the containing library |
NativeLibrary instance or null if library could not be loaded. | SecurityException | if user is not granted access for the named library. |
Definition at line 379 of file NativeLibrary.java.
|
static |
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 searchOSSystemPath argument changes the behavior to either use the default OS system path or not at all.
Assuming searchOSSystemPath is true, 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.
| windowsLibName | windows library name, with or without prefix and suffix |
| unixLibName | unix library name, with or without prefix and suffix |
| macOSXLibName | mac-osx library name, with or without prefix and suffix |
| searchOSSystemPath | if true library shall be searched in the OS system path (default), otherwise false. |
| searchSystemPathFirst | if true system path shall be searched first (default), rather than searching it last. if searchOSSystemPath is true this includes the order of the OS system path as well. |
| loader | ClassLoader to locate the library |
| global | if true allows system wide access of the loaded library, otherwise access is restricted to the process. |
| symbolName | optional symbol name for an OS which requires the symbol's address to retrieve the path of the containing library |
NativeLibrary instance or null if library could not be loaded. | SecurityException | if user is not granted access for the named library. |
Definition at line 419 of file NativeLibrary.java.
| final void com.jogamp.common.os.NativeLibrary.releaseAllLinkPermission | ( | ) | throws SecurityException |
| SecurityException | if user is not granted access for the library set. |
Implements com.jogamp.common.os.DynamicLookupHelper.
Definition at line 484 of file NativeLibrary.java.
| final String com.jogamp.common.os.NativeLibrary.toString | ( | ) |
Definition at line 256 of file NativeLibrary.java.