Class LibUtils

java.lang.Object
org.jocl.LibUtils
public final class LibUtils extends Object
Utility class for detecting the operating system and architecture types, and automatically loading the matching native library as a resource or from a file.

This class is not intended to be used by clients.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    (package private) static enum 
    LibUtils.ArchType
    Enumeration of common CPU architectures.
    (package private) static enum 
    LibUtils.OSType
    Enumeration of common operating systems, independent of version or architecture.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final Level
    level
    The default log level
    private static final String
    LIBRARY_PATH_IN_JAR
    The directory where libraries are expected in JAR files, when they are loaded as resources
    private static final Logger
    logger
    The logger used in this class

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    LibUtils()
    Private constructor to prevent instantiation.

  • Method Summary

    Modifier and Type
    Method
    Description
    private static String
    archString()
    Returns a the lower case String representation of the ArchType of this platform.
    private static LibUtils.ArchType
    calculateArch()
    Calculates the current ARCHType
    (package private) static LibUtils.OSType
    calculateOS()
    Calculates the current OSType
    private static String
    createLibraryExtension()
    Returns the extension for dynamically linked libraries on the current OS.
    static String
    createLibraryFileName(String libraryName)
    Create the full library file name, including the extension and prefix, for the given library name.
    private static String
    createLibraryPrefix()
    Returns the prefix for dynamically linked libraries on the current OS.
    static String
    createPlatformLibraryName(String baseName)
    Creates the name for the native library with the given base name for the current platform, by appending strings that indicate the current operating system and architecture.

    The resulting name will be of the form
    baseName-OSType-ArchType
    where OSType and ArchType are the lower case Strings of the respective OSType and ArcType enum constants.

    For example, the library name with the base name "EXAMPLE" may be
    EXAMPLE-windows-x86

    Note that the resulting name will not include any platform specific prefixes or extensions for the actual name.
    private static File
    createTempFile(String tempSubdirectoryName, String name)
    Create a file object representing the file with the given name in the specified subdirectory of the default "temp" directory.
    static void
    loadLibrary(String libraryName, String... dependentLibraryNames)
    Loads the specified library.
    private static void
    loadLibraryResource(String resourceSubdirectoryName, String libraryName, String tempSubdirectoryName, String... dependentLibraryNames)
    Load the library with the given name from a resource.
    private static String
    osString()
    Returns a the lower case String representation of the OSType of this platform.
    private static boolean
    trackCreatedTempFiles()
    Returns whether all temporary files that are created should be tracked with a LibTracker
    PRELIMINARY!
    private static boolean
    useUniqueLibraryNames()
    Returns whether the "uniqueLibaryNames" property was set, and the temporary files for the native libraries that are loaded as resources should receive a different name each time that they are loaded.

    PRELIMINARY!
    private static void
    writeResourceToFile(String resourceName, File file)
    Obtain an input stream to the resource with the given name, and write it to the specified file (which may not be null, and may not exist yet)

    Methods inherited from class Object

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

  • Field Details

    • logger

      private static final Logger logger
      The logger used in this class

    • level

      private static final Level level
      The default log level

    • LIBRARY_PATH_IN_JAR

      private static final String LIBRARY_PATH_IN_JAR
      The directory where libraries are expected in JAR files, when they are loaded as resources
      See Also:

  • Constructor Details

    • LibUtils

      private LibUtils()
      Private constructor to prevent instantiation.

  • Method Details

    • loadLibrary

      public static void loadLibrary(String libraryName, String... dependentLibraryNames)
      Loads the specified library.

      The method will attempt to load the library using the usual System.loadLibrary call. In this case, the specified dependent libraries are ignored, because they are assumed to be loaded automatically in the same way as the main library.

      If the library can not be loaded with the System.loadLibrary call, then this method will attempt to load the file as a resource (usually one that is contained in a JAR file). In this case, the library is assumed to be located in subdirectory called "/lib" inside the JAR file. The method will try to load a resource that has the platform-specific library file name from this directory, extract it into the default directory for temporary files, and load the library from there.

      In this case, the specified dependent libraries may also be loaded as resources. They are assumed to be located in subdirectories that are named according to the osString() and archString() of the executing platform. For example, such a library may be located in a directory inside the JAR that is called "/lib/windows/x86_64". These dependent libraries will be extracted and loaded before the main library is loaded.
      Parameters:
      libraryName - The name of the library (without a platform specific prefix or file extension)
      dependentLibraryNames - The names of libraries that the library to load depends on. If the library is loaded as a resource, then it will be attempted to also load these libraries as resources, as described above
      Throws:
      UnsatisfiedLinkError - if the native library could not be loaded.

    • loadLibraryResource

      private static void loadLibraryResource(String resourceSubdirectoryName, String libraryName, String tempSubdirectoryName, String... dependentLibraryNames) throws Throwable
      Load the library with the given name from a resource.
      Parameters:
      resourceSubdirectoryName - The subdirectory where the resource is expected
      libraryName - The library name, e.g. "EXAMPLE-windows-x86"
      tempSubdirectoryName - The name for the subdirectory in the temp directory, where the temporary files for dependent libraries should be stored
      dependentLibraryNames - The names of libraries that the library to load depends on, and that may have to be loaded as resources and stored as temporary files as well
      Throws:
      Throwable - If the library could not be loaded

    • createTempFile

      private static File createTempFile(String tempSubdirectoryName, String name) throws IOException
      Create a file object representing the file with the given name in the specified subdirectory of the default "temp" directory. If the specified subdirectory does not exist yet, it is created.
      Parameters:
      name - The file name
      Returns:
      The file
      Throws:
      IOException - If the subdirectory can not be created

    • writeResourceToFile

      private static void writeResourceToFile(String resourceName, File file) throws IOException
      Obtain an input stream to the resource with the given name, and write it to the specified file (which may not be null, and may not exist yet)
      Parameters:
      resourceName - The name of the resource
      file - The file to write to
      Throws:
      NullPointerException - If the given file is null
      IllegalArgumentException - If the given file already exists
      IOException - If an IO error occurs

    • useUniqueLibraryNames

      private static boolean useUniqueLibraryNames()
      Returns whether the "uniqueLibaryNames" property was set, and the temporary files for the native libraries that are loaded as resources should receive a different name each time that they are loaded.

      PRELIMINARY!
      Returns:
      Whether the temporary files should receive unique names

    • trackCreatedTempFiles

      private static boolean trackCreatedTempFiles()
      Returns whether all temporary files that are created should be tracked with a LibTracker
      PRELIMINARY!
      Returns:
      Whether the files should be tracked

    • createLibraryFileName

      public static String createLibraryFileName(String libraryName)
      Create the full library file name, including the extension and prefix, for the given library name. For example, the name "EXAMPLE" will become
      EXAMPLE.dll on Windows
      libEXAMPLE.so on Linux
      EXAMPLE.dylib on MacOS
      Parameters:
      libraryName - The library name
      Returns:
      The full library name, with extension

    • createLibraryExtension

      private static String createLibraryExtension()
      Returns the extension for dynamically linked libraries on the current OS. That is, returns "dylib" on Apple, "so" on Linux and Sun, and "dll" on Windows.
      Returns:
      The library extension

    • createLibraryPrefix

      private static String createLibraryPrefix()
      Returns the prefix for dynamically linked libraries on the current OS. That is, returns "lib" on Apple, Linux and Sun, and the empty String on Windows.
      Returns:
      The library prefix

    • createPlatformLibraryName

      public static String createPlatformLibraryName(String baseName)
      Creates the name for the native library with the given base name for the current platform, by appending strings that indicate the current operating system and architecture.

      The resulting name will be of the form
      baseName-OSType-ArchType
      where OSType and ArchType are the lower case Strings of the respective OSType and ArcType enum constants.

      For example, the library name with the base name "EXAMPLE" may be
      EXAMPLE-windows-x86

      Note that the resulting name will not include any platform specific prefixes or extensions for the actual name.
      Parameters:
      baseName - The base name of the library
      Returns:
      The library name

    • osString

      private static String osString()
      Returns a the lower case String representation of the OSType of this platform. E.g. "windows".
      Returns:
      The string describing the operating system

    • archString

      private static String archString()
      Returns a the lower case String representation of the ArchType of this platform. E.g. "x86_64".
      Returns:
      The string describing the architecture

    • calculateOS

      static LibUtils.OSType calculateOS()
      Calculates the current OSType
      Returns:
      The current OSType

    • calculateArch

      private static LibUtils.ArchType calculateArch()
      Calculates the current ARCHType
      Returns:
      The current ARCHType