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 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 Subroutines System search's behavior depends on `searchOSSystemPath` and `searchSystemPathFirst`. ### OS System Search - System search path direct lookup (absolute path) - Windows: `PATH` - MacOS: `DYLD_LIBRARY_PATH` - Unix: `LD_LIBRARY_PATH` - System search path implicit lookup (relative path) - OSX System search path direct lookup (absolute path) - `/Library/Frameworks/` - `/System/Library/Frameworks/` ### System Search First - If `searchOSSystemPath` - Perform described `OS System Search` above - Java's ClassLoader `findLibrary` mechanism - Java's Java system library path property - `sun.boot.library.path` ### System Search Last - Java's Java system library path property - `sun.boot.library.path` - Java's ClassLoader `findLibrary` mechanism - If `searchOSSystemPath` - Perform described `OS System Search` above ## Native Library Search Resolution - Absolute path only, if given - JogAmp's optional primary search path from Java property `jogamp.primary.library.path` - path is separated via `File.pathseparator` - if `searchSystemPathFirst` - Perform described `System Search First` above - Java's Java user library path property - `java.library.path` - Java's Java user current working directory - user: `user.dir` - user+fat: `user.dir` + File.separator + `natives` + File.separator + `PlatformPropsImpl.os_and_arch` - if `!searchSystemPathFirst` - Perform described `System Search Last` above

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	NativeLibrary.LibPath	Native Library Path Specification

Field Summary

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

DEBUG, DEBUG_LOOKUP

Method Summary

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<NativeLibrary.LibPath>	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 OS system path.
static List<NativeLibrary.LibPath>	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 OS system path.
static String	findLibrary(String libName, ClassLoader loader)
static String	getJogAmpPrimaryLibraryPaths()	Returns JogAmp's primary library path `jogamp.primary.library.path` separated with File.pathSeparator.
NativeLibrary.LibPath	getLibPath()	Retrieves the path under which this library was opened.
long	getLibraryHandle()	Retrieves the low-level library handle from this NativeLibrary object.
String	getLibraryPath()	Retrieves the path under which this library was opened.
String	getNativeLibraryPath()	Returns the native library path of the opened native getLibraryHandle(), maybe null if not supported by OS.
static String	getSystemEnvLibraryPaths()	Returns a system paths separated with File.pathSeparator, from the getSystemEnvLibraryPathVarname() variable.
static String	getSystemEnvLibraryPathVarname()	Returns the system's environment variable name used for the dynamic linker to resolve library locations, e.g.
boolean	isFunctionAvailable(String funcName)	Queries whether function 'funcName' is available.
boolean	isOpen()	Returns true if library is loaded and open, otherwise false.
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 searchOSSystemPath, 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 libName, boolean searchOSSystemPath, boolean searchSystemPathFirst, ClassLoader loader, boolean global, String symbolName)	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 searchOSSystemPath, boolean searchSystemPathFirst, ClassLoader loader, boolean global, String symbolName)	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()

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

getSystemEnvLibraryPathVarname

public static final String getSystemEnvLibraryPathVarname()

Returns the system's environment variable name used for the dynamic linker to resolve library locations, e.g. - Windows: PATH - MacOS: DYLD_LIBRARY_PATH - Unix: LD_LIBRARY_PATH

getSystemEnvLibraryPaths

public static final String getSystemEnvLibraryPaths()

Returns a system paths separated with File.pathSeparator, from the getSystemEnvLibraryPathVarname() variable.

getJogAmpPrimaryLibraryPaths

public static final String getJogAmpPrimaryLibraryPaths()

Returns JogAmp's primary library path `jogamp.primary.library.path` separated with File.pathSeparator.

open

public static final NativeLibrary open(String libName,
                                       boolean searchOSSystemPath,
                                       boolean searchSystemPathFirst,
                                       ClassLoader loader,
                                       boolean global)
                                throws SecurityException

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.

Parameters:

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.

Returns:

NativeLibrary instance or null 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 libName,
                                       boolean searchOSSystemPath,
                                       boolean searchSystemPathFirst,
                                       ClassLoader loader,
                                       boolean global,
                                       String symbolName)
                                throws SecurityException

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.

Parameters:

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

Returns:

NativeLibrary instance or null 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 searchOSSystemPath,
                                       boolean searchSystemPathFirst,
                                       ClassLoader loader,
                                       boolean global,
                                       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. 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.

Parameters:

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

Returns:

NativeLibrary instance or null 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 interface DynamicLookupHelper

Throws:

SecurityException - if user is not granted access for the library set.

releaseAllLinkPermission

public final void releaseAllLinkPermission()
                                    throws SecurityException

Specified by:

releaseAllLinkPermission in interface DynamicLookupHelper

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 interface DynamicLookupHelper

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 interface DynamicLookupHelper

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().

isOpen

public final boolean isOpen()

Description copied from interface: DynamicLookupHelper

Returns true if library is loaded and open, otherwise false.

Specified by:

isOpen in interface DynamicLookupHelper

getLibraryPath

public final String getLibraryPath()

Retrieves the path under which this library was opened.

getLibPath

public final NativeLibrary.LibPath getLibPath()

Retrieves the path under which this library was opened.

getNativeLibraryPath

public final String getNativeLibraryPath()

Returns the native library path of the opened native getLibraryHandle(), maybe null if not supported by OS.

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 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<NativeLibrary.LibPath> 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 OS system path.

enumerateLibraryPaths

public static final List<NativeLibrary.LibPath> 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 OS system path.

findLibrary

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