Package org.jocl
Class LibUtils
java.lang.Object
org.jocl.LibUtils
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.
This class is not intended to be used by clients.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static enum
Enumeration of common CPU architectures.(package private) static enum
Enumeration of common operating systems, independent of version or architecture. -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static String
Returns a the lower case String representation of theArchType
of this platform.private static LibUtils.ArchType
Calculates the current ARCHType(package private) static LibUtils.OSType
Calculates the current OSTypeprivate static String
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
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 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 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 theOSType
of this platform.private static boolean
Returns whether all temporary files that are created should be tracked with aLibTracker
PRELIMINARY!private static boolean
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 benull
, and may not exist yet)
-
Field Details
-
logger
The logger used in this class -
level
The default log level -
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
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:
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 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:
Throwable
- If the library could not be loaded
-
createTempFile
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
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:
NullPointerException
- If the given file isnull
IllegalArgumentException
- If the given file already existsIOException
- 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
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
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
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
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
Returns a the lower case String representation of theOSType
of this platform. E.g."windows"
.- Returns:
- The string describing the operating system
-
archString
Returns a the lower case String representation of theArchType
of this platform. E.g."x86_64"
.- Returns:
- The string describing the architecture
-
calculateOS
Calculates the current OSType- Returns:
- The current OSType
-
calculateArch
Calculates the current ARCHType- Returns:
- The current ARCHType
-