public abstract class LibraryLoader<T> extends Object
Example usage
public interface LibC {
int puts(String str);
}
LibC libc = LibraryLoader.create(LibC.class).load("c");
libc.puts("Hello, World");
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_LIBRARY |
Modifier | Constructor and Description |
---|---|
protected |
LibraryLoader(Class<T> interfaceClass) |
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,
boolean failImmediately)
Implemented by FFI providers to load the actual library.
|
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. |
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. |
<J> LibraryLoader<T> |
map(Class<? extends J> javaType,
DataConverter<? extends J,?> dataConverter) |
<J> LibraryLoader<T> |
map(Class<? extends J> javaType,
FromNativeConverter<? extends J,?> fromNativeConverter)
Adds a custom java type mapping.
|
<J> LibraryLoader<T> |
map(Class<? extends J> javaType,
ToNativeConverter<? extends J,?> toNativeConverter)
Adds a custom java type mapping.
|
LibraryLoader<T> |
map(String javaName,
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,
Object value)
Sets an option when loading libraries.
|
static boolean |
saveError(Map<LibraryOption,?> options,
boolean methodHasSave,
boolean methodHasIgnore)
When either the
SaveError or
IgnoreError annotations are used, the
following matrix applies:
(SL = save at library level, IM = ignore at method level, etc) |
LibraryLoader<T> |
search(String path)
Adds a path to search for libraries.
|
LibraryLoader<T> |
searchDefault()
Add the default library to the search order.
|
LibraryLoader<T> |
stdcall()
Sets the calling convention of the library to the Windows stdcall calling convention
|
public static final String DEFAULT_LIBRARY
public static <T> LibraryLoader<T> create(Class<T> interfaceClass)
LibraryLoader
instance.T
- The library type.interfaceClass
- the interface that describes the native library functionsLibraryLoader
instance.public static boolean saveError(Map<LibraryOption,?> options, boolean methodHasSave, boolean methodHasIgnore)
SaveError
or
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 |
options
- optionsmethodHasSave
- whether the method has error-saving enabledmethodHasIgnore
- whether the method ignores errorspublic static <T> T loadLibrary(Class<T> interfaceClass, Map<LibraryOption,?> libraryOptions, Map<String,List<String>> searchPaths, String... libraryNames)
interfaceClass
to native methods in the library.T
- the interface type.libraryNames
- the name of the library to loadinterfaceClass
- the interface that describes the native library interfacesearchPaths
- a map of library names to paths that should be searchedlibraryOptions
- optionsinterfaceclass
that will call the native methods.public static <T> T loadLibrary(Class<T> interfaceClass, Map<LibraryOption,?> libraryOptions, String... libraryNames)
loadLibrary(Class, Map, Map, String...)
with an empty search path map.T
- the interface typeinterfaceClass
- the interface to implementlibraryOptions
- optionslibraryNames
- names to try when searching for the libraryloadLibrary(Class, Map, Map, String...)
public LibraryLoader<T> library(String libraryName)
libraryName
- The name or path of library to load.LibraryLoader
instance.public LibraryLoader<T> searchDefault()
LibraryLoader
instance.public LibraryLoader<T> search(String path)
path
- A directory to search.LibraryLoader
instance.public LibraryLoader<T> option(LibraryOption option, Object value)
option
- The option to set.value
- The value for the option.LibraryLoader
instance.LibraryOption
public LibraryLoader<T> mapper(TypeMapper typeMapper)
typeMapper
- The type mapper to use.LibraryLoader
instance.public LibraryLoader<T> mapper(SignatureTypeMapper typeMapper)
typeMapper
- The type mapper to use.LibraryLoader
instance.public <J> LibraryLoader<T> map(Class<? extends J> javaType, ToNativeConverter<? extends J,?> toNativeConverter)
J
- The Java type.javaType
- The java type to convert to a native type.toNativeConverter
- A ToNativeConverter
that will convert from the java type to a native type.LibraryLoader
instance.public <J> LibraryLoader<T> map(Class<? extends J> javaType, FromNativeConverter<? extends J,?> fromNativeConverter)
J
- The Java type.javaType
- The java type to convert to a native type.fromNativeConverter
- A ToNativeConverter
that will convert from the native type to a java type.LibraryLoader
instance.public <J> LibraryLoader<T> map(Class<? extends J> javaType, DataConverter<? extends J,?> dataConverter)
public LibraryLoader<T> mapper(FunctionMapper functionMapper)
functionMapper
- The function mapper to use.LibraryLoader
instance.public LibraryLoader<T> map(String javaName, String nativeFunction)
javaName
- The java method name.nativeFunction
- The native library symbol to map the java method name to.LibraryLoader
instance.public LibraryLoader<T> convention(CallingConvention convention)
This is only needed on windows platforms - unless explicitly specified, all platforms assume
CallingConvention.DEFAULT
as the calling convention.
convention
- The calling convention.LibraryLoader
instance.public final LibraryLoader<T> stdcall()
LibraryLoader
instance.public final LibraryLoader<T> failImmediately()
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.LibraryLoader
instance.public T load(String libraryName)
interfaceClass
to native methods in the library.libraryName
- The name or path of library to load.create(Class)
that will call the native methods.public T load()
interfaceClass
to native methods in the library.create(Class)
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)
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.failImmediately
- whether to fast-fail when the library does not implement the requested functionsinterfaceClass
that will call the native methods.Copyright © 2024. All rights reserved.