jnr.ffi

Class LibraryLoader<T>

java.lang.Object

jnr.ffi.LibraryLoader<T>

public abstract class LibraryLoader<T>
extends Object

Loads a native library and maps it to a java interface.

Example usage

 public interface LibC {
    int puts(String str);
 }

 LibC libc = LibraryLoader.create(LibC.class).load("c");

 libc.puts("Hello, World");

 
 

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LibraryLoader(Class<T> interfaceClass)

Method Summary

Methods

Modifier and Type	Method and Description
LibraryLoader<T>	convention(CallingConvention convention) Sets the native function calling convention.
static <T> LibraryLoader<T>	create(Class<T> interfaceClass) Creates a new LibraryLoader instance.
LibraryLoader<T>	failImmediately() Turns off lazy propagation of load failures.
LibraryLoader<T>	library(String libraryName) Adds a library to be loaded.
T	load() Loads a native library and links the methods defined in interfaceClass to native methods in the library.
T	load(String libraryName) Loads a native library and links the methods defined in interfaceClass to native methods in the library.
protected abstract T	loadLibrary(Class<T> interfaceClass, Collection<String> libraryNames, Collection<String> searchPaths, Map<LibraryOption,Object> options) Implemented by FFI providers to load the actual library.
LibraryLoader<T>	mapper(FunctionMapper typeMapper) Adds a function mapper to use when resolving symbols in this library.
LibraryLoader<T>	mapper(SignatureTypeMapper typeMapper) Adds a type mapper to use when resolving method parameter and result types.
LibraryLoader<T>	mapper(TypeMapper typeMapper) Adds a type mapper to use when resolving method parameter and result types.
LibraryLoader<T>	option(LibraryOption option, Object value) Sets an option when loading libraries.
LibraryLoader<T>	search(String path) Adds a path to search for libraries.
LibraryLoader<T>	stdcall() Sets the calling convention of the library to the Windows stdcall calling convention

Methods inherited from class java.lang.Object

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

Constructor Detail

LibraryLoader

protected LibraryLoader(Class<T> interfaceClass)

Method Detail

create

public static <T> LibraryLoader<T> create(Class<T> interfaceClass)

Creates a new LibraryLoader instance.

Parameters:

interfaceClass - the interface that describes the native library functions

Returns:

A LibraryLoader instance.

library

public LibraryLoader<T> library(String libraryName)

Adds a library to be loaded. Multiple libraries can be specified using additional calls to this method, and all libraries will be searched to resolve symbols (e.g. functions, variables).

Parameters:

libraryName - The name or path of library to load.

Returns:

The LibraryLoader instance.

search

public LibraryLoader<T> search(String path)

Adds a path to search for libraries. Multiple paths can be specified using multiple calls to this method, and all paths will be searched..

Parameters:

path - A directory to search.

Returns:

The LibraryLoader instance.

option

public LibraryLoader<T> option(LibraryOption option,
                      Object value)

Sets an option when loading libraries.

Parameters:

option - The option to set

value - The value for the option.

Returns:

The LibraryLoader instance.

See Also:

LibraryOption

mapper

public LibraryLoader<T> mapper(TypeMapper typeMapper)

Adds a type mapper to use when resolving method parameter and result types. Multiple type mappers can be specified by additional calls to this method, and each mapper will be tried in order until one is successful.

Parameters:

typeMapper - The type mapper to use.

Returns:

The LibraryLoader instance.

mapper

public LibraryLoader<T> mapper(SignatureTypeMapper typeMapper)

Adds a type mapper to use when resolving method parameter and result types. Multiple type mappers can be specified by additional calls to this method, and each mapper will be tried in order until one is successful.

Parameters:

typeMapper - The type mapper to use.

Returns:

The LibraryLoader instance.

mapper

public LibraryLoader<T> mapper(FunctionMapper typeMapper)

Adds a function mapper to use when resolving symbols in this library. Multiple function mappers can be specified by additional calls to this method, and each mapper will be tried in order, until one is successful.

Parameters:

typeMapper - The function mapper to use.

Returns:

The LibraryLoader instance.

convention

public LibraryLoader<T> convention(CallingConvention convention)

Sets the native function calling convention.

This is only needed on windows platforms - unless explicitly specified, all platforms assume CallingConvention.DEFAULT as the calling convention.

Returns:

The LibraryLoader instance.

stdcall

public final LibraryLoader<T> stdcall()

Sets the calling convention of the library to the Windows stdcall calling convention

Returns:

This LibraryLoader instance.

failImmediately

public final LibraryLoader<T> failImmediately()

Turns off lazy propagation of load failures. By default, load() will not fail immediately if any libraries cannot be loaded - instead, it will create an instance of the library interface that re-throws any load errors when invoked. Calling this method will make load() throw errors immediately.

Returns:

This LibraryLoader instance.

load

public T load(String libraryName)

Loads a native library and links the methods defined in interfaceClass to native methods in the library.

Parameters:

libraryName - The name or path of library to load.

Returns:

an implementation of the interface provided to create(Class) that will call the native methods.

load

public T load()

Loads a native library and links the methods defined in interfaceClass to native methods in the library.

Returns:

an implementation of the interface provided to create(Class) that will call the native methods.

loadLibrary

protected abstract T loadLibrary(Class<T> interfaceClass,
            Collection<String> libraryNames,
            Collection<String> searchPaths,
            Map<LibraryOption,Object> options)

Implemented by FFI providers to load the actual library.

Parameters:

interfaceClass - The java class that describes the functions to be mapped.

libraryNames - A list of libraries to load & search for symbols

searchPaths - The paths to search for libraries to be loaded

options - The options to apply when loading the library

Returns:

an instance of interfaceClass that will call the native methods.