Package org.jocl
Class LibUtils
- java.lang.Object
-
- org.jocl.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 levelprivate static java.lang.String
LIBRARY_PATH_IN_JAR
The directory where libraries are expected in JAR files, when they are loaded as resourcesprivate 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 theArchType
of this platform.private static LibUtils.ArchType
calculateArch()
Calculates the current ARCHType(package private) static LibUtils.OSType
calculateOS()
Calculates the current OSTypeprivate 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 respectiveOSType
andArcType
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 theOSType
of this platform.private static boolean
trackCreatedTempFiles()
Returns whether all temporary files that are created should be tracked with aLibTracker
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 benull
, and may not exist yet)
-
-
-
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
-
-
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 usualSystem.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 theSystem.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-specificlibrary 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 theosString()
andarchString()
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 expectedlibraryName
- 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 storeddependentLibraryNames
- 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 benull
, and may not exist yet)- Parameters:
resourceName
- The name of the resourcefile
- The file to write to- Throws:
java.lang.NullPointerException
- If the given file isnull
java.lang.IllegalArgumentException
- If the given file already existsjava.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 aLibTracker
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 respectiveOSType
andArcType
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 theOSType
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 theArchType
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
-
-