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 calling loadNativeLibrary(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):

1. 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 else loadNativeLibrary(String) will throw an exception.
2. 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 library nativedata 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 else loadNativeLibrary(String) will throw an exception.
3. If you use the property native.caching.libpath.<libname> instead of native.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.

4. If you use the property native.caching.libpath instead of native.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.

5. 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.
6. Finally, if no appropriate structure is found in the classpath, loadNativeLibrary(String) will fall back to the Java default method of loading JNI libraries via System.loadLibrary(String). This may require the Java property java.library.path to be set and it may require the library to follow a platform specific naming convention for the native shared library file.

Constructor Summary

Constructors

Constructor	Description
NativeLibraryUtilities()

Method Summary

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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NativeLibraryUtilities

public NativeLibraryUtilities()

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 in NativeLibraryUtilities.

Parameters:

libraryName - The name of the native library to be loaded.

Returns:

true if the library has been loaded successfully and false 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 - If true, print error to stderr if copying fails.

Returns:

The name of the temporary file, or null, if the resource could not be copied.