Package jnr.ffi

Class LibraryLoader<T>

  • 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");

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String DEFAULT_LIBRARY  

    • 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 new LibraryLoader instance.
      LibraryLoader<T> failImmediately()
      Turns off lazy propagation of load failures.
      LibraryLoader<T> library​(java.lang.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​(java.lang.String libraryName)
      Loads a native library and links the methods defined in interfaceClass 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, boolean failImmediately)
      Implemented by FFI providers to load the actual library.
      static <T> T loadLibrary​(java.lang.Class<T> interfaceClass, java.util.Map<LibraryOption,​?> libraryOptions, java.lang.String... libraryNames)
      Same as calling loadLibrary(Class, Map, Map, String...) with an empty search path map.
      static <T> T loadLibrary​(java.lang.Class<T> interfaceClass, java.util.Map<LibraryOption,​?> libraryOptions, java.util.Map<java.lang.String,​java.util.List<java.lang.String>> searchPaths, java.lang.String... libraryNames)
      Loads a native library and links the methods defined in interfaceClass to native methods in the 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 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​(java.lang.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

      • Methods inherited from class java.lang.Object

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

    • Field Detail

    • 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 new LibraryLoader 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 the 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 |
        Parameters:
        options - options
        methodHasSave - whether the method has error-saving enabled
        methodHasIgnore - whether the method ignores errors
        Returns:
        true if the error was saved, false otherwise

      • loadLibrary

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

      • loadLibrary

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

      • 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.

      • searchDefault

        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:
        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 - A ToNativeConverter 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 - A ToNativeConverter that will convert from the native type to a java type.
        Returns:
        The LibraryLoader instance.

      • 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 make load() throw errors immediately.
        Returns:
        This LibraryLoader instance.

      • load

        public T load​(java.lang.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​(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,
                                 boolean failImmediately)
        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.
        failImmediately - whether to fast-fail when the library does not implement the requested functions
        Returns:
        an instance of interfaceClass that will call the native methods.