Class Library


  • public final class Library
    extends java.lang.Object
    Represents a native library
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  Library.DefaultLibrary
      A handle to the current process
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.util.Map<java.lang.String,​java.lang.ref.WeakReference<Library>> cache
      A cache of opened libraries
      private int disposed
      Indicates whether this library has been disposed of.
      private Foreign foreign
      A handle to the foreign interface to keep it alive as long as this object is alive
      static int GLOBAL
      All symbols in the library are made available to other libraries
      private long handle
      The native dl/LoadLibrary handle
      private static java.lang.ThreadLocal<java.lang.String> lastError
      Stores the last error returned by a dlopen or dlsym call
      static int LAZY
      Perform lazy binding.
      static int LOCAL
      Symbols in this library are not made available to other libraries
      private static java.lang.Object lock
      A lock used to serialize all dlopen/dlsym calls
      private java.lang.String name
      The name of this Library
      static int NOW
      Resolve all symbols when loading the library
      private static java.util.concurrent.atomic.AtomicIntegerFieldUpdater<Library> UPDATER  
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Library​(Foreign foreign, java.lang.String name, long address)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private static long dlopen​(Foreign foreign, java.lang.String name, int flags)
      Internal wrapper around dlopen.
      protected void finalize()  
      static Library getCachedInstance​(java.lang.String name, int flags)
      Gets a handle for the named library.
      static Library getDefault()
      Gets a handle to the default library.
      static java.lang.String getLastError()
      Gets the current error string from dlopen/LoadLibrary.
      long getSymbolAddress​(java.lang.String name)
      Gets the address of a symbol within the Library.
      static Library openLibrary​(java.lang.String name, int flags)
      Gets a handle for the named library.
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • cache

        private static final java.util.Map<java.lang.String,​java.lang.ref.WeakReference<Library>> cache
        A cache of opened libraries
      • lock

        private static final java.lang.Object lock
        A lock used to serialize all dlopen/dlsym calls
      • lastError

        private static final java.lang.ThreadLocal<java.lang.String> lastError
        Stores the last error returned by a dlopen or dlsym call
      • LAZY

        public static final int LAZY
        Perform lazy binding. Only resolve symbols as needed
        See Also:
        Constant Field Values
      • NOW

        public static final int NOW
        Resolve all symbols when loading the library
        See Also:
        Constant Field Values
      • LOCAL

        public static final int LOCAL
        Symbols in this library are not made available to other libraries
        See Also:
        Constant Field Values
      • GLOBAL

        public static final int GLOBAL
        All symbols in the library are made available to other libraries
        See Also:
        Constant Field Values
      • handle

        private final long handle
        The native dl/LoadLibrary handle
      • name

        private final java.lang.String name
        The name of this Library
      • foreign

        private final Foreign foreign
        A handle to the foreign interface to keep it alive as long as this object is alive
      • disposed

        private volatile int disposed
        Indicates whether this library has been disposed of.
      • UPDATER

        private static final java.util.concurrent.atomic.AtomicIntegerFieldUpdater<Library> UPDATER
    • Constructor Detail

      • Library

        private Library​(Foreign foreign,
                        java.lang.String name,
                        long address)
    • Method Detail

      • dlopen

        private static long dlopen​(Foreign foreign,
                                   java.lang.String name,
                                   int flags)
        Internal wrapper around dlopen. If the library open fails, then this stores the native error in a thread local variable for later retrieval.
        Parameters:
        name - The name of the library to open
        flags - The flags to pass to dlopen
        Returns:
        The native handle for the opened library, or 0 if it failed to open.
      • getDefault

        public static final Library getDefault()
        Gets a handle to the default library.
        Returns:
        A Library instance representing the default library.
      • getCachedInstance

        public static final Library getCachedInstance​(java.lang.String name,
                                                      int flags)
        Gets a handle for the named library.
        Parameters:
        name - The name or path of the library to open.
        flags - The library flags (e.g. LAZY, NOW, LOCAL, GLOBAL)
        Returns:
        A Library instance representing the named library, or null if the library could not be opened.
      • openLibrary

        public static final Library openLibrary​(java.lang.String name,
                                                int flags)
        Gets a handle for the named library. Note This will not cache the instance, nor will it return a cached instance. Only use when you really need a new handle for the library.
        Parameters:
        name - The name or path of the library to open.
        flags - The library flags (e.g. LAZY, NOW, LOCAL, GLOBAL)
        Returns:
        A Library instance representing the named library, or null if the library cannot be opened.
      • getSymbolAddress

        public final long getSymbolAddress​(java.lang.String name)
        Gets the address of a symbol within the Library.
        Parameters:
        name - The name of the symbol to locate.
        Returns:
        The address of the symbol within the current address space.
      • getLastError

        public static final java.lang.String getLastError()
        Gets the current error string from dlopen/LoadLibrary.
        Returns:
        A String describing the last error.
      • finalize

        protected void finalize()
                         throws java.lang.Throwable
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable