com.jme3.system

Class NativeLibraryLoader

java.lang.Object

com.jme3.system.NativeLibraryLoader

public final class NativeLibraryLoader
extends java.lang.Object

Utility class to register, extract, and load native libraries.
Register your own libraries via the registerNativeLibrary(String, Platform, String, String) method, for each platform. You can then extract this library (depending on platform), by using loadNativeLibrary(java.lang.String, boolean).
Example:

 NativeLibraryLoader.registerNativeLibrary("mystuff", Platform.Windows32, "native/windows/mystuff.dll");
 NativeLibraryLoader.registerNativeLibrary("mystuff", Platform.Windows64, "native/windows/mystuff64.dll");
 NativeLibraryLoader.registerNativeLibrary("mystuff", Platform.Linux32,   "native/linux/libmystuff.so");
 NativeLibraryLoader.registerNativeLibrary("mystuff", Platform.Linux64,   "native/linux/libmystuff64.so");
 NativeLibraryLoader.registerNativeLibrary("mystuff", Platform.MacOSX32,  "native/macosx/libmystuff.jnilib");
 NativeLibraryLoader.registerNativeLibrary("mystuff", Platform.MacOSX64,  "native/macosx/libmystuff.jnilib");
 

This will register the library. Load it via:

 NativeLibraryLoader.loadNativeLibrary("mystuff", true);
 

It will load the right library automatically based on the platform.

Method Summary

Modifier and Type	Method and Description
static void	extractNativeLibraries(Platform platform, java.io.File targetDir)
static void	extractNativeLibrary(Platform platform, java.lang.String name, java.io.File targetDir)
static java.io.File	getExtractionFolder() Returns the folder where native libraries will be extracted.
static java.io.File	getJarForNativeLibrary(Platform platform, java.lang.String name)
static java.io.File[]	getJarsWithNatives()
static boolean	isUsingNativeBullet() Determines whether native Bullet is on the classpath.
static void	loadNativeLibrary(java.lang.String name, boolean isRequired) First extracts the native library and then loads it.
static void	registerNativeLibrary(java.lang.String name, Platform platform, java.lang.String path) Register a new known JNI library.
static void	registerNativeLibrary(java.lang.String name, Platform platform, java.lang.String path, java.lang.String extractAsName) Register a new known library.
static void	setCustomExtractionFolder(java.lang.String path) Specify a custom location where native libraries should be extracted to.

Methods inherited from class java.lang.Object

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

Method Detail

registerNativeLibrary

public static void registerNativeLibrary(java.lang.String name,
                                         Platform platform,
                                         java.lang.String path,
                                         java.lang.String extractAsName)

Register a new known library. This simply registers a known library, the actual extraction and loading is performed by calling loadNativeLibrary(java.lang.String, boolean).

Parameters:

name - The name / ID of the library (not OS or architecture specific).

platform - The platform for which the in-natives-jar path has been specified for.

path - The path inside the natives-jar or classpath corresponding to this library. Must be compatible with the platform argument.

extractAsName - The filename that the library should be extracted as, if null, use the same name as in the path.

registerNativeLibrary

public static void registerNativeLibrary(java.lang.String name,
                                         Platform platform,
                                         java.lang.String path)

Register a new known JNI library. This simply registers a known library, the actual extraction and loading is performed by calling loadNativeLibrary(java.lang.String, boolean). This method should be called several times for each library name, each time specifying a different platform + path combination.

Parameters:

name - The name / ID of the library (not OS or architecture specific).

platform - The platform for which the in-natives-jar path has been specified for.

path - The path inside the natives-jar or classpath corresponding to this library. Must be compatible with the platform argument.

isUsingNativeBullet

public static boolean isUsingNativeBullet()

Determines whether native Bullet is on the classpath. Currently, the context extracts the native Bullet libraries, so this method is needed to determine if they are needed. Ideally, native Bullet would be responsible for its own natives.

Returns:

True native bullet is on the classpath, false otherwise.

setCustomExtractionFolder

public static void setCustomExtractionFolder(java.lang.String path)

Specify a custom location where native libraries should be extracted to. Ensure this is a unique path not used by other applications to extract their libraries. Set to null to restore default functionality.

Parameters:

path - Path where to extract native libraries.

getExtractionFolder

public static java.io.File getExtractionFolder()

Returns the folder where native libraries will be extracted. This is automatically determined at run-time based on the following criteria:

• If a custom extraction folder has been specified, it is returned.
• If the user can write to the working folder, then it is returned.
• Otherwise, the storage folder is used, to prevent collisions, a special subfolder is used called natives_<hash> where <hash> is computed automatically as the XOR of the classpath hash code and the last modified date of this class.

Returns:

Path where natives will be extracted to.

getJarsWithNatives

public static java.io.File[] getJarsWithNatives()

extractNativeLibraries

public static void extractNativeLibraries(Platform platform,
                                          java.io.File targetDir)
                                   throws java.io.IOException

Throws:

java.io.IOException

getJarForNativeLibrary

public static java.io.File getJarForNativeLibrary(Platform platform,
                                                  java.lang.String name)

extractNativeLibrary

public static void extractNativeLibrary(Platform platform,
                                        java.lang.String name,
                                        java.io.File targetDir)
                                 throws java.io.IOException

Throws:

java.io.IOException

loadNativeLibrary

public static void loadNativeLibrary(java.lang.String name,
                                     boolean isRequired)

First extracts the native library and then loads it.

Parameters:

name - The name of the library to load.

isRequired - If true and the library fails to load, throw exception. If false, do nothing if it fails to load.