Top Description Fields Constructors Methods
com.jogamp.common.os

public final Class NativeLibrary

extends Object
implements DynamicLookupHelper
Class Inheritance
All Implemented Interfaces
com.jogamp.common.os.DynamicLookupHelper
Imports
java.io.File, java.lang.reflect.Method, java.net.URISyntaxException, java.security.AccessController, .PrivilegedAction, java.util.ArrayList, .Iterator, .List, .StringTokenizer, jogamp.common.os.BionicDynamicLinker32bitImpl, .BionicDynamicLinker64BitImpl, .MacOSXDynamicLinkerImpl, .PlatformPropsImpl, .PosixDynamicLinkerImpl, .WindowsDynamicLinkerImpl, com.jogamp.common.ExceptionUtils, com.jogamp.common.util.IOUtil, com.jogamp.common.util.cache.TempJarCache
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

Modifier and TypeField and Description
private final DynamicLinker
dynLink

private static Method
findLibraryMethod

private final boolean
global

private static boolean
initializedFindLibraryMethod

private static final boolean
isOSX

private long
libraryHandle

private final String
libraryPath

private static final String[]
prefixes

private static final String[]
suffixes

Constructor Summary

AccessConstructor and Description
private
NativeLibrary(final DynamicLinker dynLink, final long libraryHandle, final String libraryPath, final boolean global)

Method Summary

Modifier and TypeMethod and Description
private static final void
addPaths(final String path, final String[] baseNames, final List<String> paths)

private static final String[]
buildNames(final String libName)

public final void
claimAllLinkPermission()

Implements com.jogamp.common.os.DynamicLookupHelper.claimAllLinkPermission.

public final void
close()

Closes this native library.

public final long
dynamicLookupFunction(final String funcName)

Implements com.jogamp.common.os.DynamicLookupHelper.dynamicLookupFunction.

Returns the function handle for function 'funcName'.
public final long
dynamicLookupFunctionGlobal(final String funcName)

Looks up the given function name in all loaded libraries.

public static final List<String>
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 system path.

public static final List<String>
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 system path.

private static final List<String>
enumerateLibraryPaths(final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPath, final boolean searchSystemPathFirst, final ClassLoader loader)

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

private static final String
findLibraryImpl(final String libName, final ClassLoader loader)

pack-priv final DynamicLinker
getDynamicLinker()

public final long
getLibraryHandle()

Retrieves the low-level library handle from this NativeLibrary object.

public final String
getLibraryPath()

Retrieves the path under which this library was opened.

public final boolean
isFunctionAvailable(final String funcName)

Implements com.jogamp.common.os.DynamicLookupHelper.isFunctionAvailable.

Queries whether function 'funcName' is available.
public static final String

Returns:

basename of libName w/o path, ie. /usr/lib/libDrinkBeer.so -> DrinkBeer on Unix systems, but null on Windows.
isValidNativeLibraryName(final String
the full path library name with prefix and suffix
libName, final boolean
indicates if libName is already lower-case
isLowerCaseAlready)

Comparison of prefix and suffix of the given libName's basename is performed case insensitive

public static final NativeLibrary
open(final String libName, final 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.

public static final NativeLibrary
open(final String libName, final ClassLoader loader, final 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.

public static final NativeLibrary
open(final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPathFirst, final 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.

public static final NativeLibrary
open(final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPathFirst, final ClassLoader loader, final boolean global)

public final void
releaseAllLinkPermission()

Implements com.jogamp.common.os.DynamicLookupHelper.releaseAllLinkPermission.

private static final String
selectName(final String windowsLibName, final String unixLibName, final String macOSXLibName)

public final String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

findLibraryMethodback to summary
private static Method findLibraryMethod
globalback to summary
private final boolean global
initializedFindLibraryMethodback to summary
private static boolean initializedFindLibraryMethod
isOSXback to summary
private static final boolean isOSX
libraryHandleback to summary
private long libraryHandle
libraryPathback to summary
private final String libraryPath
prefixesback to summary
private static final String[] prefixes
suffixesback to summary
private static final String[] suffixes

Constructor Detail

NativeLibraryback to summary
private NativeLibrary(final DynamicLinker dynLink, final long libraryHandle, final String libraryPath, final boolean global)

Method Detail

addPathsback to summary
private static final void addPaths(final String path, final String[] baseNames, final List<String> paths)
buildNamesback to summary
private static final String[] buildNames(final String libName)
claimAllLinkPermissionback to summary
public final void claimAllLinkPermission() throws SecurityException

Implements com.jogamp.common.os.DynamicLookupHelper.claimAllLinkPermission.

Annotations
@Override
Exceptions
SecurityException:

Doc from com.jogamp.common.os.DynamicLookupHelper.claimAllLinkPermission.

if user is not granted access for the library set.

closeback to summary
public final void close() throws SecurityException

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

Exceptions
SecurityException:
if user is not granted access for the named library.
dynamicLookupFunctionback to summary
public final long dynamicLookupFunction(final String funcName) throws SecurityException

Implements com.jogamp.common.os.DynamicLookupHelper.dynamicLookupFunction.

Doc from com.jogamp.common.os.DynamicLookupHelper.dynamicLookupFunction.

Returns the function handle for function 'funcName'.

Annotations
@Override
Exceptions
SecurityException:
if user is not granted access for the library set.
dynamicLookupFunctionGlobalback to summary
public final long dynamicLookupFunctionGlobal(final String funcName) throws SecurityException

Looks up the given function name in all loaded libraries.

Exceptions
SecurityException:
if user is not granted access for the named library.
enumerateLibraryPathsback to summary
public static final List<String> 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 system path.

enumerateLibraryPathsback to summary
public static final List<String> 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 system path.

enumerateLibraryPathsback to summary
private static final List<String> enumerateLibraryPaths(final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPath, final boolean searchSystemPathFirst, final ClassLoader loader)
findLibraryback to summary
public static final String findLibrary(final String libName, final ClassLoader loader)
findLibraryImplback to summary
private static final String findLibraryImpl(final String libName, final ClassLoader loader)
getDynamicLinkerback to summary
pack-priv final DynamicLinker getDynamicLinker()
getLibraryHandleback to summary
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().

getLibraryPathback to summary
public final String getLibraryPath()

Retrieves the path under which this library was opened.

isFunctionAvailableback to summary
public final boolean isFunctionAvailable(final String funcName) throws SecurityException

Implements com.jogamp.common.os.DynamicLookupHelper.isFunctionAvailable.

Doc from com.jogamp.common.os.DynamicLookupHelper.isFunctionAvailable.

Queries whether function 'funcName' is available.

Annotations
@Override
Exceptions
SecurityException:
if user is not granted access for the library set.
isValidNativeLibraryNameback to summary
public 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

Parameters
libName:String

the full path library name with prefix and suffix

isLowerCaseAlready:boolean

indicates if libName is already lower-case

Returns:String

basename of libName w/o path, ie. /usr/lib/libDrinkBeer.so -> DrinkBeer on Unix systems, but null on Windows.

openback to summary
public static final NativeLibrary open(final String libName, final ClassLoader loader) throws SecurityException

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.

Exceptions
SecurityException:
if user is not granted access for the named library.
openback to summary
public static final NativeLibrary open(final String libName, final ClassLoader loader, final boolean global) throws SecurityException

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.

Exceptions
SecurityException:
if user is not granted access for the named library.
openback to summary
public static final NativeLibrary open(final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPathFirst, final ClassLoader loader) 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 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.
Exceptions
SecurityException:
if user is not granted access for the named library.
openback to summary
public static final NativeLibrary open(final String windowsLibName, final String unixLibName, final String macOSXLibName, final boolean searchSystemPathFirst, final ClassLoader loader, final boolean global) throws SecurityException
Exceptions
SecurityException:
if user is not granted access for the named library.
releaseAllLinkPermissionback to summary
public final void releaseAllLinkPermission() throws SecurityException

Implements com.jogamp.common.os.DynamicLookupHelper.releaseAllLinkPermission.

Annotations
@Override
Exceptions
SecurityException:

Doc from com.jogamp.common.os.DynamicLookupHelper.releaseAllLinkPermission.

if user is not granted access for the library set.

selectNameback to summary
private static final String selectName(final String windowsLibName, final String unixLibName, final String macOSXLibName)
toStringback to summary
public final String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object

Annotations
@Override