Package org.jocl

Class LibUtils

  • public final class LibUtils
extends java.lang.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 class  LibUtils.ArchType
      Enumeration of common CPU architectures.
      (package private) static class  LibUtils.OSType
      Enumeration of common operating systems, independent of version or architecture.

    • Field Summary

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

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      private static java.lang.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 java.lang.String createLibraryExtension()
      Returns the extension for dynamically linked libraries on the current OS.
      static java.lang.String createLibraryFileName​(java.lang.String libraryName)
      Create the full library file name, including the extension and prefix, for the given library name.
      private static java.lang.String createLibraryPrefix()
      Returns the prefix for dynamically linked libraries on the current OS.
      static java.lang.String createPlatformLibraryName​(java.lang.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 java.io.File createTempFile​(java.lang.String tempSubdirectoryName, java.lang.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​(java.lang.String libraryName, java.lang.String... dependentLibraryNames)
      Loads the specified library.
      private static void loadLibraryResource​(java.lang.String resourceSubdirectoryName, java.lang.String libraryName, java.lang.String tempSubdirectoryName, java.lang.String... dependentLibraryNames)
      Load the library with the given name from a resource.
      private static java.lang.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​(java.lang.String resourceName, java.io.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 java.lang.Object

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

    • Field Detail

      • logger

        private static final java.util.logging.Logger logger
        The logger used in this class

      • level

        private static final java.util.logging.Level level
        The default log level

      • LIBRARY_PATH_IN_JAR

        private static final java.lang.String LIBRARY_PATH_IN_JAR
        The directory where libraries are expected in JAR files, when they are loaded as resources
        See Also:
        Constant Field Values

    • Constructor Detail

      • LibUtils

        private LibUtils()
        Private constructor to prevent instantiation.

    • Method Detail

      • loadLibrary

        public static void loadLibrary​(java.lang.String libraryName,
                               java.lang.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:
        java.lang.UnsatisfiedLinkError - if the native library could not be loaded.

      • loadLibraryResource

        private static void loadLibraryResource​(java.lang.String resourceSubdirectoryName,
                                        java.lang.String libraryName,
                                        java.lang.String tempSubdirectoryName,
                                        java.lang.String... dependentLibraryNames)
                                 throws java.lang.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:
        java.lang.Throwable - If the library could not be loaded

      • createTempFile

        private static java.io.File createTempFile​(java.lang.String tempSubdirectoryName,
                                           java.lang.String name)
                                    throws java.io.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:
        java.io.IOException - If the subdirectory can not be created

      • writeResourceToFile

        private static void writeResourceToFile​(java.lang.String resourceName,
                                        java.io.File file)
                                 throws java.io.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:
        java.lang.NullPointerException - If the given file is null
        java.lang.IllegalArgumentException - If the given file already exists
        java.io.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 java.lang.String createLibraryFileName​(java.lang.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 java.lang.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 java.lang.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 java.lang.String createPlatformLibraryName​(java.lang.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 java.lang.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 java.lang.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