Class JLineNativeLoader
This class handles the discovery, extraction, and loading of the appropriate native library for the current platform. The native libraries are essential for certain terminal operations that require direct system calls.
Usage
Callinitialize()
before using JLine features that require native support:
JLineNativeLoader.initialize();
Library Loading Process
The loader attempts to find and load the native library in the following order:- From the path specified by the
library.jline.path
system property - From the JAR file's embedded native libraries
- From the Java library path (
java.library.path
)
Configuration Options
The following system properties can be used to configure the native library loading:library.jline.path
- Custom directory path where native libraries are located. The loader will check both[library.jline.path]/[os]/[arch]
and[library.jline.path]
directly.library.jline.name
- Custom name for the native library file. If not specified, the default name will be used (e.g., "jlinenative.dll" on Windows).jline.tmpdir
- Custom temporary directory for extracting native libraries. If not specified,java.io.tmpdir
will be used.java.library.path
- Standard Java property for native library search paths, used as a last resort.
Platform Detection
The loader automatically detects the current operating system and architecture usingOSInfo
to determine which native library to load. Supported platforms include:
- Operating Systems: Windows, macOS (Darwin), Linux, AIX
- Architectures: x86, x86_64 (amd64), ARM (various versions), PowerPC, and others
Temporary Files
When loading from the JAR file, the native library is extracted to a temporary location. These temporary files:- Include version and UUID in the filename to avoid conflicts
- Are automatically cleaned up on JVM exit
- Old unused libraries from previous runs are cleaned up
Troubleshooting
If the library fails to load, an exception is thrown with details about:- The detected OS and architecture
- All paths that were searched
- The specific error that occurred
Java Module System (JPMS) Considerations
When using JLine with the Java Module System, you may need to add the--enable-native-access=ALL-UNNAMED
JVM option to allow the native library loading.- See Also:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic int
Returns the major version number of the JLine library.static int
Returns the minor version number of the JLine library.static String
Returns the absolute path to the loaded native library file.static String
Returns the source URL from which the native library was loaded.static String
Returns the full version string of the JLine library.static boolean
Loads the JLine native library for the current platform.
-
Constructor Details
-
JLineNativeLoader
public JLineNativeLoader()
-
-
Method Details
-
initialize
public static boolean initialize()Loads the JLine native library for the current platform.This method should be called before using any JLine features that require native support. It handles the discovery, extraction, and loading of the appropriate native library.
The method is thread-safe and idempotent - calling it multiple times has no additional effect after the first successful call. A background thread is started to clean up old native library files from previous runs.
If the library cannot be loaded, a
RuntimeException
is thrown with detailed information about the failure, including the OS, architecture, and paths that were searched.Example usage:
try { JLineNativeLoader.initialize(); // JLine features that require native support can be used here } catch (RuntimeException e) { // Handle the case where native library cannot be loaded System.err.println("JLine native support not available: " + e.getMessage()); }
- Returns:
- True if the JLine native library is successfully loaded; this will always be true if the method returns normally, as it throws an exception on failure.
- Throws:
RuntimeException
- If the native library cannot be loaded for any reason.
-
getNativeLibraryPath
Returns the absolute path to the loaded native library file.This method can be used to determine which specific native library file was successfully loaded. It's particularly useful for debugging and logging purposes.
Note: This method will return null if called before
initialize()
or if the library failed to load.- Returns:
- The absolute path to the loaded native library file, or null if the library hasn't been loaded.
-
getNativeLibrarySourceUrl
Returns the source URL from which the native library was loaded.This is typically a jar:file: URL pointing to the location within the JAR file from which the native library was extracted. This information can be useful for debugging and logging purposes.
Note: This method will return null if called before
initialize()
or if the library failed to load, or if the library was loaded from the filesystem rather than extracted from a JAR.- Returns:
- The source URL of the loaded native library, or null if not applicable or if the library hasn't been loaded.
-
getMajorVersion
public static int getMajorVersion()Returns the major version number of the JLine library.This method extracts the major version number from the full version string. For example, if the version is "3.21.0", this method returns 3.
The version information is read from the Maven POM properties file in the JAR. If the version cannot be determined, 1 is returned as a default value.
- Returns:
- The major version number of the JLine library, or 1 if it cannot be determined.
- See Also:
-
getMinorVersion
public static int getMinorVersion()Returns the minor version number of the JLine library.This method extracts the minor version number from the full version string. For example, if the version is "3.21.0", this method returns 21.
The version information is read from the Maven POM properties file in the JAR. If the version cannot be determined or doesn't have a minor component, 0 is returned as a default value.
- Returns:
- The minor version number of the JLine library, or 0 if it cannot be determined.
- See Also:
-
getVersion
Returns the full version string of the JLine library.This method retrieves the version information from the Maven POM properties file in the JAR at "/META-INF/maven/org.jline/jline-native/pom.properties".
The version string is cleaned to include only numeric values and dots (e.g., "3.21.0"). If the version information cannot be determined (e.g., the properties file is missing or cannot be read), "unknown" is returned.
This version information is used in the naming of temporary native library files to ensure proper versioning and avoid conflicts between different JLine versions.
- Returns:
- The version string of the JLine library, or "unknown" if it cannot be determined.
-