io.humble.ferry

Class JNILibraryLoader

java.lang.Object

io.humble.ferry.JNILibraryLoader

public final class JNILibraryLoader
extends Object

Internal Only. Finds and loads native libraries that we depend on.

It supplements the Java builtin System.loadLibrary(String) by looking in more places.

Many methods in this class are marked as "package level". In reality, they are private, but are at this protection level so our test suite can test internals.

Method Summary

Modifier and Type	Method and Description
static void	loadLibrary(String aLibraryName) Redirects to loadLibrary(String, Long), but leaves the version as null (not requested).
static void	loadLibrary(String aLibraryName, Long aMajorVersion) Deprecated. Use JNILibrary instead. Attempts to find and load the given library, with the given version of the library if version is asked for. First, if we detect that we've already loaded the given library, we'll just return rather than attempt a second load (which will fail on some OSes). If we haven't already loaded this library, we will search in the path defined by the property java.library.path for the library, creating OS-dependent names, and using version strings. If we can't find it in that property, we'll search through the OS-dependent shared-library specification environment variable. If we can't find a versioned library (and one was requested) but can find an unversioned library, we'll use the unversioned library. But we will first search all directories for a versioned library under the assumption that if you asked for a version, you care more about meeting that requirement than finding it in the first directory we run across. If all that still fails, we'll fall back to the System.loadLibrary(String) method (for example, if we cannot guess a libtool-like convention for the OS we're on). We assume a libtool-like library name for the shared library, but will check for common variants on that name. Hopefully an illustration will make this all clearer. Assume we're looking for a library named "foo" with version 1, this method will search as follows: OS Filenames searched for (in order) Directories looked in (in order) On Windows: foo-1.dll libfoo-1.dll cygfoo-1.dll foo.dll libfoo.dll cygfoo.dll Every directory in the java property java.library.path Every directory in the environment variable PATH On Linux: libfoo.so.1 libfoo.so Every directory in the java property java.library.path Every directory in the environment variable LD_LIBRARY_PATH On Apple OS-X: libfoo.1.dylib libfoo.dylib Every directory in the java property java.library.path Every directory in the environment variable DYLD_LIBRARY_PATH

Methods inherited from class java.lang.Object

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

Method Detail

loadLibrary

@Deprecated
public static void loadLibrary(String aLibraryName,
                                           Long aMajorVersion)

Deprecated. Use JNILibrary instead. Attempts to find and load the given library, with the given version of the library if version is asked for.

First, if we detect that we've already loaded the given library, we'll just return rather than attempt a second load (which will fail on some OSes).

If we haven't already loaded this library, we will search in the path defined by the property java.library.path for the library, creating OS-dependent names, and using version strings. If we can't find it in that property, we'll search through the OS-dependent shared-library specification environment variable.

If we can't find a versioned library (and one was requested) but can find an unversioned library, we'll use the unversioned library. But we will first search all directories for a versioned library under the assumption that if you asked for a version, you care more about meeting that requirement than finding it in the first directory we run across.

If all that still fails, we'll fall back to the System.loadLibrary(String) method (for example, if we cannot guess a libtool-like convention for the OS we're on).

We assume a libtool-like library name for the shared library, but will check for common variants on that name.

Hopefully an illustration will make this all clearer. Assume we're looking for a library named "foo" with version 1, this method will search as follows:

OS	Filenames searched for (in order)	Directories looked in (in order)
On Windows:	foo-1.dll libfoo-1.dll cygfoo-1.dll foo.dll libfoo.dll cygfoo.dll	Every directory in the java property java.library.path Every directory in the environment variable PATH
On Linux:	libfoo.so.1 libfoo.so	Every directory in the java property java.library.path Every directory in the environment variable LD_LIBRARY_PATH
On Apple OS-X:	libfoo.1.dylib libfoo.dylib	Every directory in the java property java.library.path Every directory in the environment variable DYLD_LIBRARY_PATH

Parameters:

aLibraryName - The name of the library, without any OS-dependent adornments like "lib", ".so" or ".dll".

aMajorVersion - The major version of this library, or null if you want to take any version.

Throws:

UnsatisfiedLinkError - If we cannot find the library after searching in all the aforementioned locations.

loadLibrary

public static void loadLibrary(String aLibraryName)

Redirects to loadLibrary(String, Long), but leaves the version as null (not requested).

Parameters:

aLibraryName - The name of the library, without any OS-dependent adornments like "lib", ".so" or ".dll".