Package jnr.ffi
Class LibraryLoader<T>
- java.lang.Object
-
- jnr.ffi.LibraryLoader<T>
-
- Direct Known Subclasses:
NativeLibraryLoader
public abstract class LibraryLoader<T> extends java.lang.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");
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
LibraryLoader.StaticDataHolder
-
Field Summary
Fields Modifier and Type Field Description private boolean
failImmediately
private FunctionMapper.Builder
functionMapperBuilder
private java.util.List<FunctionMapper>
functionMappers
private java.lang.Class<T>
interfaceClass
private java.util.List<java.lang.String>
libraryNames
private java.util.Map<LibraryOption,java.lang.Object>
optionMap
private java.util.List<java.lang.String>
searchPaths
private TypeMapper.Builder
typeMapperBuilder
private java.util.List<SignatureTypeMapper>
typeMappers
-
Constructor Summary
Constructors Modifier Constructor Description protected
LibraryLoader(java.lang.Class<T> interfaceClass)
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description LibraryLoader<T>
convention(CallingConvention convention)
Sets the native function calling convention.static <T> LibraryLoader<T>
create(java.lang.Class<T> interfaceClass)
Creates a newLibraryLoader
instance.private T
createErrorProxy(java.lang.Throwable ex)
LibraryLoader<T>
failImmediately()
Turns off lazy propagation of load failures.private static java.util.List<java.lang.String>
getPropertyPaths(java.lang.String propName)
private java.util.Collection<java.lang.String>
getSearchPaths()
LibraryLoader<T>
library(java.lang.String libraryName)
Adds a library to be loaded.T
load()
Loads a native library and links the methods defined ininterfaceClass
to native methods in the library.T
load(java.lang.String libraryName)
Loads a native library and links the methods defined ininterfaceClass
to native methods in the library.protected abstract T
loadLibrary(java.lang.Class<T> interfaceClass, java.util.Collection<java.lang.String> libraryNames, java.util.Collection<java.lang.String> searchPaths, java.util.Map<LibraryOption,java.lang.Object> options)
Implemented by FFI providers to load the actual library.<J> LibraryLoader<T>
map(java.lang.Class<? extends J> javaType, DataConverter<? extends J,?> dataConverter)
<J> LibraryLoader<T>
map(java.lang.Class<? extends J> javaType, FromNativeConverter<? extends J,?> fromNativeConverter)
Adds a custom java type mapping.<J> LibraryLoader<T>
map(java.lang.Class<? extends J> javaType, ToNativeConverter<? extends J,?> toNativeConverter)
Adds a custom java type mapping.LibraryLoader<T>
map(java.lang.String javaName, java.lang.String nativeFunction)
Adds a function name mapping to use when resolving symbols in this library.LibraryLoader<T>
mapper(FunctionMapper functionMapper)
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, java.lang.Object value)
Sets an option when loading libraries.static boolean
saveError(java.util.Map<LibraryOption,?> options, boolean methodHasSave, boolean methodHasIgnore)
When either theSaveError
orIgnoreError
annotations are used, the following matrix applies: (SL = save at library level, IM = ignore at method level, etc)LibraryLoader<T>
search(java.lang.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
-
-
-
Field Detail
-
searchPaths
private final java.util.List<java.lang.String> searchPaths
-
libraryNames
private final java.util.List<java.lang.String> libraryNames
-
typeMappers
private final java.util.List<SignatureTypeMapper> typeMappers
-
functionMappers
private final java.util.List<FunctionMapper> functionMappers
-
optionMap
private final java.util.Map<LibraryOption,java.lang.Object> optionMap
-
typeMapperBuilder
private final TypeMapper.Builder typeMapperBuilder
-
functionMapperBuilder
private final FunctionMapper.Builder functionMapperBuilder
-
interfaceClass
private final java.lang.Class<T> interfaceClass
-
failImmediately
private boolean failImmediately
-
-
Constructor Detail
-
LibraryLoader
protected LibraryLoader(java.lang.Class<T> interfaceClass)
-
-
Method Detail
-
create
public static <T> LibraryLoader<T> create(java.lang.Class<T> interfaceClass)
Creates a newLibraryLoader
instance.- Type Parameters:
T
- The library type.- Parameters:
interfaceClass
- the interface that describes the native library functions- Returns:
- A
LibraryLoader
instance.
-
saveError
public static boolean saveError(java.util.Map<LibraryOption,?> options, boolean methodHasSave, boolean methodHasIgnore)
When either theSaveError
orIgnoreError
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 |
-
library
public LibraryLoader<T> library(java.lang.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(java.lang.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, java.lang.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.
-
map
public <J> LibraryLoader<T> map(java.lang.Class<? extends J> javaType, ToNativeConverter<? extends J,?> toNativeConverter)
Adds a custom java type mapping.- Type Parameters:
J
- The Java type.- Parameters:
javaType
- The java type to convert to a native type.toNativeConverter
- AToNativeConverter
that will convert from the java type to a native type.- Returns:
- The
LibraryLoader
instance.
-
map
public <J> LibraryLoader<T> map(java.lang.Class<? extends J> javaType, FromNativeConverter<? extends J,?> fromNativeConverter)
Adds a custom java type mapping.- Type Parameters:
J
- The Java type.- Parameters:
javaType
- The java type to convert to a native type.fromNativeConverter
- AToNativeConverter
that will convert from the native type to a java type.- Returns:
- The
LibraryLoader
instance.
-
map
public <J> LibraryLoader<T> map(java.lang.Class<? extends J> javaType, DataConverter<? extends J,?> dataConverter)
-
mapper
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
- The function mapper to use.- Returns:
- The
LibraryLoader
instance.
-
map
public LibraryLoader<T> map(java.lang.String javaName, java.lang.String nativeFunction)
Adds a function name mapping to use when resolving symbols in this library.- Parameters:
javaName
- The java method name.nativeFunction
- The native library symbol to map the java method name to.- 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.- Parameters:
convention
- 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 makeload()
throw errors immediately.- Returns:
- This
LibraryLoader
instance.
-
load
public T load(java.lang.String libraryName)
Loads a native library and links the methods defined ininterfaceClass
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 ininterfaceClass
to native methods in the library.- Returns:
- an implementation of the interface provided to
create(Class)
that will call the native methods.
-
createErrorProxy
private T createErrorProxy(java.lang.Throwable ex)
-
getSearchPaths
private java.util.Collection<java.lang.String> getSearchPaths()
-
loadLibrary
protected abstract T loadLibrary(java.lang.Class<T> interfaceClass, java.util.Collection<java.lang.String> libraryNames, java.util.Collection<java.lang.String> searchPaths, java.util.Map<LibraryOption,java.lang.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 and 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.
-
getPropertyPaths
private static java.util.List<java.lang.String> getPropertyPaths(java.lang.String propName)
-
-