JNR 2023-06-06 · jnr.ffi.LibraryLoader

Modifier and Type	Class and Description
pack-priv static class	LibraryLoader.DefaultLibPaths

Modifier and Type	Field and Description
public static final String	DEFAULT_LIBRARY
private boolean	failImmediately
private final FunctionMapper.Builder	functionMapperBuilder
private final List<FunctionMapper>	functionMappers
private final Class<T>	interfaceClass
private final List<String>	libraryNames
private final Map<LibraryOption, Object>	optionMap
private final List<String>	searchPaths
private final TypeMapper.Builder	typeMapperBuilder
private final List<SignatureTypeMapper>	typeMappers

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

Method Summary

Modifier and Type	Method and Description
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. convention(CallingConvention The calling convention. convention) Sets the native function calling convention.
public static < The library type. T> LibraryLoader<T>	Returns: A `LibraryLoader` instance. create(Class<T> the interface that describes the native library functions interfaceClass) Creates a new `LibraryLoader` instance.
private T	createErrorProxy(final Throwable ex)
public final LibraryLoader<T>	Returns: This `LibraryLoader` instance. failImmediately() Turns off lazy propagation of load failures.
private static List<String>	getPropertyPaths(String propName)
private Collection<String>	getSearchPaths()
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. library(String The name or path of library to load. libraryName) Adds a library to be loaded.
public T	Returns: an implementation of the interface provided to `create(Class)` that will call the native methods. load(String The name or path of library to load. libraryName) Loads a native library and links the methods defined in `interfaceClass` to native methods in the library.
public T	Returns: an implementation of the interface provided to `create(Class)` that will call the native methods. load() Loads a native library and links the methods defined in `interfaceClass` to native methods in the library.
public static < the interface type. T> T	Returns: an instance of `interfaceclass` that will call the native methods. loadLibrary(Class<T> the interface that describes the native library interface interfaceClass, Map<LibraryOption, ?> options libraryOptions, Map<String, List<String>> a map of library names to paths that should be searched searchPaths, String... the name of the library to load libraryNames) Loads a native library and links the methods defined in `interfaceClass` to native methods in the library.
public static < the interface type T> T	Returns: a new object implementing the interface and bound to the library loadLibrary(Class<T> the interface to implement interfaceClass, Map<LibraryOption, ?> options libraryOptions, String... names to try when searching for the library libraryNames) Same as calling `loadLibrary(Class, Map, Map, String...)` with an empty search path map.
protected abstract T	Returns: an instance of `interfaceClass` that will call the native methods. loadLibrary(Class<T> The java class that describes the functions to be mapped. interfaceClass, Collection<String> A list of libraries to load and search for symbols. libraryNames, Collection<String> The paths to search for libraries to be loaded. searchPaths, Map<LibraryOption, Object> The options to apply when loading the library. options, boolean whether to fast-fail when the library does not implement the requested functions failImmediately) Implemented by FFI providers to load the actual library.
public < The Java type. J> LibraryLoader<T>	Returns: The `LibraryLoader` instance. map(Class<? extends J> The java type to convert to a native type. javaType, ToNativeConverter<? extends J, ?> A `jnr.ffi.mapper.ToNativeConverter` that will convert from the java type to a native type. toNativeConverter) Adds a custom java type mapping.
public < The Java type. J> LibraryLoader<T>	Returns: The `LibraryLoader` instance. map(Class<? extends J> The java type to convert to a native type. javaType, FromNativeConverter<? extends J, ?> A `jnr.ffi.mapper.ToNativeConverter` that will convert from the native type to a java type. fromNativeConverter) Adds a custom java type mapping.
public <J> LibraryLoader<T>	map(Class<? extends J> javaType, DataConverter<? extends J, ?> dataConverter)
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. map(String The java method name. javaName, String The native library symbol to map the java method name to. nativeFunction) Adds a function name mapping to use when resolving symbols in this library.
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. mapper(TypeMapper The type mapper to use. typeMapper) Adds a type mapper to use when resolving method parameter and result types.
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. mapper(SignatureTypeMapper The type mapper to use. typeMapper) Adds a type mapper to use when resolving method parameter and result types.
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. mapper(FunctionMapper The function mapper to use. functionMapper) Adds a function mapper to use when resolving symbols in this library.
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. option(LibraryOption The option to set. option, Object The value for the option. value) Sets an option when loading libraries.
public static boolean	Returns: true if the error was saved, false otherwise saveError(Map<LibraryOption, ?> options options, boolean whether the method has error-saving enabled methodHasSave, boolean whether the method ignores errors methodHasIgnore) When either the `jnr.ffi.annotations.SaveError` or `jnr.ffi.annotations.IgnoreError` annotations are used, the following matrix applies: (SL = save at library level, IM = ignore at method level, etc) \| none \| SL \| IL \| SL+IL\| ------------------------------------- none \| save \| save \| ignr \| save \| SM \| save \| save \| save \| save \| IM \| ignr \| ignr \| ignr \| ignr \| SM + IM \| save \| save \| save \| save \|
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. search(String A directory to search. path) Adds a path to search for libraries.
public LibraryLoader<T>	Returns: The `LibraryLoader` instance. searchDefault() Add the default library to the search order.
public final LibraryLoader<T>	Returns: This `LibraryLoader` instance. stdcall() Sets the calling convention of the library to the Windows stdcall calling convention

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

DEFAULT_LIBRARY	back to summary
public static final String DEFAULT_LIBRARY

failImmediately	back to summary
private boolean failImmediately

functionMapperBuilder	back to summary
private final FunctionMapper.Builder functionMapperBuilder

functionMappers	back to summary
private final List<FunctionMapper> functionMappers

interfaceClass	back to summary
private final Class<T> interfaceClass

libraryNames	back to summary
private final List<String> libraryNames

optionMap	back to summary
private final Map<LibraryOption, Object> optionMap

searchPaths	back to summary
private final List<String> searchPaths

typeMapperBuilder	back to summary
private final TypeMapper.Builder typeMapperBuilder

typeMappers	back to summary
private final List<SignatureTypeMapper> typeMappers

LibraryLoader	back to summary
protected LibraryLoader(Class<T> interfaceClass)

Method Detail

convention back to summary

convention	back to summary
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. Parameters convention:CallingConvention The calling convention. Returns:LibraryLoader<T> The `LibraryLoader` instance.

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.

Parameters

convention:CallingConvention: The calling convention.

Returns:LibraryLoader<T>

The LibraryLoader instance.

create back to summary

create	back to summary
public static <T> LibraryLoader<T> create(Class<T> interfaceClass) Creates a new `LibraryLoader` instance. Parameters <T> The library type. interfaceClass:Class<T> the interface that describes the native library functions Returns:LibraryLoader<T> A `LibraryLoader` instance.

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

Creates a new LibraryLoader instance.

Parameters

<T>: The library type.
interfaceClass:Class<T>: the interface that describes the native library functions

Returns:LibraryLoader<T>

A LibraryLoader instance.

createErrorProxy	back to summary
private T createErrorProxy(final Throwable ex)

failImmediately back to summary

failImmediately	back to summary
public final LibraryLoader<T> failImmediately() Turns off lazy propagation of load failures. By default, `jnr.ffi.LibraryLoader#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 `jnr.ffi.LibraryLoader#load()` throw errors immediately. Returns:LibraryLoader<T> This `LibraryLoader` instance.

public final LibraryLoader<T> failImmediately()

Turns off lazy propagation of load failures. By default, jnr.ffi.LibraryLoader#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 jnr.ffi.LibraryLoader#load() throw errors immediately.

Returns:LibraryLoader<T>: This LibraryLoader instance.

getPropertyPaths	back to summary
private static List<String> getPropertyPaths(String propName)

getSearchPaths	back to summary
private Collection<String> getSearchPaths()

library back to summary

library	back to summary
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:String The name or path of library to load. Returns:LibraryLoader<T> The `LibraryLoader` instance.

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:String: The name or path of library to load.

Returns:LibraryLoader<T>

The LibraryLoader instance.

load back to summary

load	back to summary
public T load(String libraryName) Loads a native library and links the methods defined in `interfaceClass` to native methods in the library. Parameters libraryName:String The name or path of library to load. Returns:T an implementation of the interface provided to `create(Class)` that will call the native methods.

public T load(String libraryName)

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

Parameters

libraryName:String: The name or path of library to load.

Returns:T

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

load back to summary

load	back to summary
public T load() Loads a native library and links the methods defined in `interfaceClass` to native methods in the library. Returns:T an implementation of the interface provided to `create(Class)` that will call the native methods.

public T load()

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

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

loadLibrary back to summary

loadLibrary	back to summary
public static <T> T loadLibrary(Class<T> interfaceClass, Map<LibraryOption, ?> libraryOptions, Map<String, List<String>> searchPaths, String... libraryNames) Loads a native library and links the methods defined in `interfaceClass` to native methods in the library. Parameters <T> the interface type. interfaceClass:Class<T> the interface that describes the native library interface libraryOptions:Map<LibraryOption, ?> options searchPaths:Map<String, List<String>> a map of library names to paths that should be searched libraryNames:String[] the name of the library to load Returns:T an instance of `interfaceclass` that will call the native methods.

public static <T> T loadLibrary(Class<T> interfaceClass, Map<LibraryOption, ?> libraryOptions, Map<String, List<String>> searchPaths, String... libraryNames)

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

Parameters

<T>: the interface type.
interfaceClass:Class<T>: the interface that describes the native library interface
libraryOptions:Map<LibraryOption, ?>: options
searchPaths:Map<String, List<String>>: a map of library names to paths that should be searched
libraryNames:String[]: the name of the library to load

Returns:T

an instance of interfaceclass that will call the native methods.

loadLibrary back to summary

loadLibrary	back to summary
public static <T> T loadLibrary(Class<T> interfaceClass, Map<LibraryOption, ?> libraryOptions, String... libraryNames) Same as calling `loadLibrary(Class, Map, Map, String...)` with an empty search path map. Parameters <T> the interface type interfaceClass:Class<T> the interface to implement libraryOptions:Map<LibraryOption, ?> options libraryNames:String[] names to try when searching for the library Returns:T a new object implementing the interface and bound to the library See Also `loadLibrary(Class, Map, Map, String...)`

public static <T> T loadLibrary(Class<T> interfaceClass, Map<LibraryOption, ?> libraryOptions, String... libraryNames)

Same as calling loadLibrary(Class, Map, Map, String...) with an empty search path map.

Parameters

<T>: the interface type
interfaceClass:Class<T>: the interface to implement
libraryOptions:Map<LibraryOption, ?>: options
libraryNames:String[]: names to try when searching for the library

Returns:T

a new object implementing the interface and bound to the library

loadLibrary back to summary

loadLibrary	back to summary
protected abstract T loadLibrary(Class<T> interfaceClass, Collection<String> libraryNames, Collection<String> searchPaths, Map<LibraryOption, Object> options, boolean failImmediately) Implemented by FFI providers to load the actual library. Parameters interfaceClass:Class<T> The java class that describes the functions to be mapped. libraryNames:Collection<String> A list of libraries to load and search for symbols. searchPaths:Collection<String> The paths to search for libraries to be loaded. options:Map<LibraryOption, Object> The options to apply when loading the library. failImmediately:boolean whether to fast-fail when the library does not implement the requested functions Returns:T an instance of `interfaceClass` that will call the native methods.

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

Implemented by FFI providers to load the actual library.

Parameters

interfaceClass:Class<T>: The java class that describes the functions to be mapped.
libraryNames:Collection<String>: A list of libraries to load and search for symbols.
searchPaths:Collection<String>: The paths to search for libraries to be loaded.
options:Map<LibraryOption, Object>: The options to apply when loading the library.
failImmediately:boolean: whether to fast-fail when the library does not implement the requested functions

Returns:T

an instance of interfaceClass that will call the native methods.

map back to summary

map	back to summary
public <J> LibraryLoader<T> map(Class<? extends J> javaType, ToNativeConverter<? extends J, ?> toNativeConverter) Adds a custom java type mapping. Parameters <J> The Java type. javaType:Class<? extends J> The java type to convert to a native type. toNativeConverter:ToNativeConverter<? extends J, ?> A `jnr.ffi.mapper.ToNativeConverter` that will convert from the java type to a native type. Returns:LibraryLoader<T> The `LibraryLoader` instance.

public <J> LibraryLoader<T> map(Class<? extends J> javaType, ToNativeConverter<? extends J, ?> toNativeConverter)

Adds a custom java type mapping.

Parameters

<J>: The Java type.
javaType:Class<? extends J>: The java type to convert to a native type.
toNativeConverter:ToNativeConverter<? extends J, ?>: A jnr.ffi.mapper.ToNativeConverter that will convert from the java type to a native type.

Returns:LibraryLoader<T>

The LibraryLoader instance.

map back to summary

map	back to summary
public <J> LibraryLoader<T> map(Class<? extends J> javaType, FromNativeConverter<? extends J, ?> fromNativeConverter) Adds a custom java type mapping. Parameters <J> The Java type. javaType:Class<? extends J> The java type to convert to a native type. fromNativeConverter:FromNativeConverter<? extends J, ?> A `jnr.ffi.mapper.ToNativeConverter` that will convert from the native type to a java type. Returns:LibraryLoader<T> The `LibraryLoader` instance.

public <J> LibraryLoader<T> map(Class<? extends J> javaType, FromNativeConverter<? extends J, ?> fromNativeConverter)

Adds a custom java type mapping.

Parameters

<J>: The Java type.
javaType:Class<? extends J>: The java type to convert to a native type.
fromNativeConverter:FromNativeConverter<? extends J, ?>: A jnr.ffi.mapper.ToNativeConverter that will convert from the native type to a java type.

Returns:LibraryLoader<T>

The LibraryLoader instance.

map	back to summary
public <J> LibraryLoader<T> map(Class<? extends J> javaType, DataConverter<? extends J, ?> dataConverter)

map back to summary

map	back to summary
public LibraryLoader<T> map(String javaName, String nativeFunction) Adds a function name mapping to use when resolving symbols in this library. Parameters javaName:String The java method name. nativeFunction:String The native library symbol to map the java method name to. Returns:LibraryLoader<T> The `LibraryLoader` instance.

public LibraryLoader<T> map(String javaName, String nativeFunction)

Adds a function name mapping to use when resolving symbols in this library.

Parameters

javaName:String: The java method name.
nativeFunction:String: The native library symbol to map the java method name to.

Returns:LibraryLoader<T>

The LibraryLoader instance.

mapper back to summary

mapper	back to summary
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:TypeMapper The type mapper to use. Returns:LibraryLoader<T> The `LibraryLoader` instance.

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:TypeMapper: The type mapper to use.

Returns:LibraryLoader<T>

The LibraryLoader instance.

mapper back to summary

mapper	back to summary
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:SignatureTypeMapper The type mapper to use. Returns:LibraryLoader<T> The `LibraryLoader` instance.

public LibraryLoader<T> mapper(SignatureTypeMapper typeMapper)

Parameters

typeMapper:SignatureTypeMapper: The type mapper to use.

Returns:LibraryLoader<T>

The LibraryLoader instance.

mapper back to summary

mapper	back to summary
public LibraryLoader<T> mapper(FunctionMapper functionMapper) 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 functionMapper:FunctionMapper The function mapper to use. Returns:LibraryLoader<T> The `LibraryLoader` instance.

public LibraryLoader<T> mapper(FunctionMapper functionMapper)

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

functionMapper:FunctionMapper: The function mapper to use.

Returns:LibraryLoader<T>

The LibraryLoader instance.

option back to summary

option	back to summary
public LibraryLoader<T> option(LibraryOption option, Object value) Sets an option when loading libraries. Parameters option:LibraryOption The option to set. value:Object The value for the option. Returns:LibraryLoader<T> The `LibraryLoader` instance. See Also `LibraryOption`

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

Sets an option when loading libraries.

Parameters

option:LibraryOption: The option to set.
value:Object: The value for the option.

Returns:LibraryLoader<T>

The LibraryLoader instance.

See Also

LibraryOption

saveError back to summary

saveError	back to summary
public static boolean saveError(Map<LibraryOption, ?> options, boolean methodHasSave, boolean methodHasIgnore) When either the `jnr.ffi.annotations.SaveError` or `jnr.ffi.annotations.IgnoreError` annotations are used, the following matrix applies: (SL = save at library level, IM = ignore at method level, etc) \| none \| SL \| IL \| SL+IL\| ------------------------------------- none \| save \| save \| ignr \| save \| SM \| save \| save \| save \| save \| IM \| ignr \| ignr \| ignr \| ignr \| SM + IM \| save \| save \| save \| save \| Parameters options:Map<LibraryOption, ?> options methodHasSave:boolean whether the method has error-saving enabled methodHasIgnore:boolean whether the method ignores errors Returns:boolean true if the error was saved, false otherwise

public static boolean saveError(Map<LibraryOption, ?> options, boolean methodHasSave, boolean methodHasIgnore)

When either the jnr.ffi.annotations.SaveError or jnr.ffi.annotations.IgnoreError annotations are used, the following matrix applies: (SL = save at library level, IM = ignore at method level, etc)

        | none |  SL  |  IL  | SL+IL|
-------------------------------------
none    | save | save | ignr | save |
SM      | save | save | save | save |
IM      | ignr | ignr | ignr | ignr |
SM + IM | save | save | save | save |

Parameters

options:Map<LibraryOption, ?>: options
methodHasSave:boolean: whether the method has error-saving enabled
methodHasIgnore:boolean: whether the method ignores errors

Returns:boolean

true if the error was saved, false otherwise

search back to summary

search	back to summary
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:String A directory to search. Returns:LibraryLoader<T> The `LibraryLoader` instance.

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:String: A directory to search.

Returns:LibraryLoader<T>

The LibraryLoader instance.

searchDefault back to summary

searchDefault	back to summary
public LibraryLoader<T> searchDefault() Add the default library to the search order. This will search all loaded libraries in the current process according to the system's implementation of dlsym(RTLD_DEFAULT). Returns:LibraryLoader<T> The `LibraryLoader` instance.

public LibraryLoader<T> searchDefault()

Add the default library to the search order. This will search all loaded libraries in the current process according to the system's implementation of dlsym(RTLD_DEFAULT).

Returns:LibraryLoader<T>: The LibraryLoader instance.

stdcall back to summary

stdcall	back to summary
public final LibraryLoader<T> stdcall() Sets the calling convention of the library to the Windows stdcall calling convention Returns:LibraryLoader<T> This `LibraryLoader` instance.

public final LibraryLoader<T> stdcall()

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

Returns:LibraryLoader<T>: This LibraryLoader instance.

public abstract Class LibraryLoader<T>

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Class LibraryLoader.DefaultLibPaths

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail