Package electrostatic4j.snaploader

Class NativeBinaryLoader

java.lang.Object
electrostatic4j.snaploader.NativeBinaryLoader
Direct Known Subclasses:
ConcurrentNativeBinaryLoader
public class NativeBinaryLoader extends Object
A cross-platform utility for extracting and loading native binaries based on the variant properties (OS + ARCH + VM).

  • Field Details

    • libraryInfo

      protected final LibraryInfo libraryInfo

    • registeredLibraries

      protected List<NativeDynamicLibrary> registeredLibraries

    • nativeBinaryLoadingListener

      protected NativeBinaryLoadingListener nativeBinaryLoadingListener

    • systemDetectionListener

      protected SystemDetectionListener systemDetectionListener

    • libraryLocalizingListener

      protected FileLocalizingListener libraryLocalizingListener

    • libraryExtractionListener

      protected FileExtractionListener libraryExtractionListener

    • libraryExtractor

      protected FileExtractor libraryExtractor
      An Output stream concrete provider for library extraction.

    • nativeDynamicLibrary

      protected NativeDynamicLibrary nativeDynamicLibrary
      The native dynamic library object representing the library to extract and load.

    • retryWithCleanExtraction

      protected boolean retryWithCleanExtraction
      Flag for retry loading with clean extract if UnSatisfiedLinkError is thrown.

    • maxNumberOfLoadingFailure

      protected int maxNumberOfLoadingFailure

    • numberOfLoadingFailure

      protected int numberOfLoadingFailure

  • Constructor Details

    • NativeBinaryLoader

      public NativeBinaryLoader(LibraryInfo libraryInfo)
      Instantiates a native dynamic library loader to extract and load a system-specific native dynamic library.

    • NativeBinaryLoader

      public NativeBinaryLoader(List<NativeDynamicLibrary> registeredLibraries, LibraryInfo libraryInfo)
      Instantiates a native dynamic library loader to extract and load a system-specific native dynamic library.

  • Method Details

    • registerNativeLibraries

      public NativeBinaryLoader registerNativeLibraries(NativeDynamicLibrary[] nativeDynamicLibraries)

    • initPlatformLibrary

      public NativeBinaryLoader initPlatformLibrary() throws UnSupportedSystemError
      Initializes the platform-dependent native dynamic library.
      Returns:
      this instance for chained invocations
      Throws:
      UnSupportedSystemError - if the OS is not supported by jSnapLoader

    • loadLibrary

      public NativeBinaryLoader loadLibrary(LoadingCriterion criterion) throws Exception
      Extracts and loads the system and the architecture-specific library from the output jar to a specified directory according to a loading criterion (incremental-load or clean-extract). The directory is determined by the selected NativeDynamicLibrary from the registered platform libraries.

      Note: The default loading action for Android Systems is loading the libraries from the System directories (i.e., /lib/ABI inside the APK packages), while the default loading action for other desktop systems is determined by the user through this parameterized function.

      Fallback loading routines can be implemented as needed via NativeBinaryLoadingListener.onLoadingFailure(NativeBinaryLoader, CallingStackMetaData) and are left for the user applications.

      Parameters:
      criterion - the initial loading criterion, either LoadingCriterion.INCREMENTAL_LOADING, LoadingCriterion.CLEAN_EXTRACTION or LoadingCriterion.SYSTEM_LOAD for loading native dlls from system directories.
      Returns:
      this instance for chained invocations
      Throws:
      IOException - if the library to extract is not present in the jar filesystem
      Exception

    • getNativeDynamicLibrary

      public NativeDynamicLibrary getNativeDynamicLibrary()
      Retrieves the native dynamic library object representing the library to extract and load.
      Returns:
      an object representing the platform-dependent native dynamic library

    • setLoggingEnabled

      public NativeBinaryLoader setLoggingEnabled(boolean loggingEnabled)
      Enables the logging for this object, default value is false.
      Parameters:
      loggingEnabled - true to enable logging, false otherwise

    • isRetryWithCleanExtraction

      public boolean isRetryWithCleanExtraction()
      Tests the retry with clean extraction flag, default value is false.
      Returns:
      true if enabled, false otherwise

    • setRetryWithCleanExtraction

      public NativeBinaryLoader setRetryWithCleanExtraction(boolean retryWithCleanExtraction)
      Enables the retry with clean extraction after a load failure, default value is false.
      Parameters:
      retryWithCleanExtraction - true to enable the flag, false otherwise

    • getRegisteredLibraries

      public List<NativeDynamicLibrary> getRegisteredLibraries()

    • getNativeBinaryLoadingListener

      public NativeBinaryLoadingListener getNativeBinaryLoadingListener()

    • setNativeBinaryLoadingListener

      public NativeBinaryLoader setNativeBinaryLoadingListener(NativeBinaryLoadingListener nativeBinaryLoadingListener)

    • getSystemDetectionListener

      public SystemDetectionListener getSystemDetectionListener()

    • setSystemDetectionListener

      public NativeBinaryLoader setSystemDetectionListener(SystemDetectionListener systemDetectionListener)

    • getLibraryExtractionListener

      public FileExtractionListener getLibraryExtractionListener()

    • setLibraryExtractionListener

      public NativeBinaryLoader setLibraryExtractionListener(FileExtractionListener libraryExtractionListener)

    • getLibraryLocalizingListener

      public FileLocalizingListener getLibraryLocalizingListener()

    • setLibraryLocalizingListener

      public NativeBinaryLoader setLibraryLocalizingListener(FileLocalizingListener libraryLocalizingListener)

    • setMaxNumberOfLoadingFailure

      public NativeBinaryLoader setMaxNumberOfLoadingFailure(int maxNumberOfLoadingFailure)

    • loadSystemBinary

      protected void loadSystemBinary()
      Loads a native binary from the system directories into the process virtual address space using the library basename in a platform-dependent way.

    • loadBinary

      protected void loadBinary(NativeDynamicLibrary library, LoadingCriterion loadingCriterion) throws Exception
      Loads a native binary into the virtual process address space from a specified native library data structure defining the directory path.
      Parameters:
      library - the platform-specific library to load
      loadingCriterion - pass the loading criterion condition to the calling stack metadata structure
      Throws:
      IOException - in case the binary to be extracted is not found on the specified jar
      LoadingRetryExhaustionException - if the number of loading failure exceeds the specified number.
      Exception

    • cleanExtractBinary

      protected void cleanExtractBinary(NativeDynamicLibrary library) throws Exception
      Cleanly extracts and loads the native binary to the current [user.dir].
      Parameters:
      library - the platform-specific library to extract and load
      Throws:
      IOException - in case the binary to be extracted is not found on the specified jar, or an interrupted I/O operation has occurred
      Exception

    • initializeLibraryExtractor

      protected FileExtractor initializeLibraryExtractor(NativeDynamicLibrary library) throws Exception
      Initializes a filesystem extractor object if the filesystem extractor object associated with this loader isn't defined.
      Parameters:
      library - the native dynamic library to load
      Returns:
      a new FileExtractor object that represents an output stream provider
      Throws:
      IOException - if the jar filesystem to be located is not found, or if the extraction destination is not found
      Exception

    • preInitLibraryLocator

      protected LibraryLocator preInitLibraryLocator(FileExtractor extractor)