Package ch.systemsx.cisd.base.utilities
Class NativeLibraryUtilities
- java.lang.Object
-
- ch.systemsx.cisd.base.utilities.NativeLibraryUtilities
-
public final class NativeLibraryUtilities extends java.lang.Object
A utility class for loading native shared libraries (following the JNI specification). A native shared library is identified by a name. The process of loading the shared library is performed by callingloadNativeLibrary(String)
.A native shared library can be provided to your program either as a file on the file system or as a resource in a jar file that is on the classpath of your program. In the later case the resources will be copied to a file before being loaded. This utility class tries the following approaches (in this order):
- Use a specific Java property
native.libpath.<libname>
for each library<libname>
. The name of the library needs to be fully specified, e.g.-Dnative.libpath.<libname>=/home/joe/java/native/<some_shared_library_file>
The file has to exist or elseloadNativeLibrary(String)
will throw an exception. - Use a naming schema that looks for a path to the library which is compatible with the platform the program is running on (as determined by
#getCompatibleComputerPlatform()
). The root of the hierarchy is given by the property-Dnative.libpath=/home/joe/java/native/
A real world example is the native librarynativedata
which has the hierarchy:nativedata nativedata/arm-Linux nativedata/arm-Linux/libnativedata.so nativedata/i386-Linux nativedata/i386-Linux/libnativedata.so nativedata/amd64-Linux nativedata/amd64-Linux/libnativedata.so nativedata/i386-Mac OS X nativedata/i386-Mac OS X/libnativedata.jnilib nativedata/x86_64-Mac OS X nativedata/x86_64-Mac OS X/libnativedata.jnilib nativedata/x86-SunOS nativedata/x86-SunOS/libnativedata.so nativedata/amd64-SunOS nativedata/amd64-SunOS/libnativedata.so nativedata/sparc-SunOS nativedata/sparc-SunOS/libnativedata.so nativedata/sparcv9-SunOS nativedata/sparcv9-SunOS/libnativedata.so nativedata/x86-Windows nativedata/x86-Windows/nativedata.dll nativedata/amd64-Windows nativedata/amd64-Windows/nativedata.dll
The file has to exist or elseloadNativeLibrary(String)
will throw an exception. - If you use the property
native.caching.libpath.<libname>
instead ofnative.libpath.<libname>
, then you will get the behavior of 1, but the library file on the file system will be considered a cache of a resource inside one of the jar files in the class path. Inside of the jar file, the resources need ot have the structure as explained in 2.The file does not have to exist as it will be unpacked from the appropriate jar file resource.
- If you use the property
native.caching.libpath
instead ofnative.libpath
, then you will get the behavior of 2, but the library files on the file system will all be considered a cache of a resource inside one of the jar files in the class path with the same hierarchical structure.The file does not have to exist as it will be unpacked from the appropriate jar file resource.
- If you do not set any of the properties desribed above when starting up your program, but you happen to have a hierarchical directory structure
as explained in 2 in one of the jar files of your class path, then
loadNativeLibrary(String)
will unpack the appopriate shared library into a temporary directory and load it from there. The temporary file will be deleted at shutdown of the program (except on Microsoft Windows where mandatory locks make this impossible). This is the 'auto mode' and thus the simplest way of using this utility class for the user of your program. - Finally, if no appropriate structure is found in the classpath,
loadNativeLibrary(String)
will fall back to the Java default method of loading JNI libraries viaSystem.loadLibrary(String)
. This may require the Java propertyjava.library.path
to be set and it may require the library to follow a platform specific naming convention for the native shared library file.
- Use a specific Java property
-
-
Constructor Summary
Constructors Constructor Description NativeLibraryUtilities()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static boolean
loadNativeLibrary(java.lang.String libraryName)
Loads the native library libraryName.static java.lang.String
tryCopyNativeLibraryToTempFile(java.lang.String libraryName, boolean verbose)
Tries to copy a native library which is available as a resource to a temporary file.
-
-
-
Method Detail
-
loadNativeLibrary
public static boolean loadNativeLibrary(java.lang.String libraryName)
Loads the native library libraryName. The native library will be searched for in the way described inNativeLibraryUtilities
.- Parameters:
libraryName
- The name of the native library to be loaded.- Returns:
true
if the library has been loaded successfully andfalse
otherwise.
-
tryCopyNativeLibraryToTempFile
public static java.lang.String tryCopyNativeLibraryToTempFile(java.lang.String libraryName, boolean verbose)
Tries to copy a native library which is available as a resource to a temporary file. It will use the following naming schema to locate the resource containing the native library:/native/<libraryName>/<platform_id>/<libraryName>.so
.- Parameters:
libraryName
- The name of the library.verbose
- Iftrue
, print error tostderr
if copying fails.- Returns:
- The name of the temporary file, or
null
, if the resource could not be copied.
-
-