Class 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.
    • 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.
      • 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.