Package org.jline.nativ

Class JLineNativeLoader

java.lang.Object

org.jline.nativ.JLineNativeLoader

public class JLineNativeLoader
extends Object

Manages the loading of JLine's native libraries (*.dll, *.jnilib, *.so) according to the current operating system (Windows, Linux, macOS) and architecture.

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

Call initialize() 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:

1. From the path specified by the library.jline.path system property
2. From the JAR file's embedded native libraries
3. 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 using OSInfo 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:

• For details on platform detection

Constructor Summary

Constructors

Constructor	Description
JLineNativeLoader()

Method Summary

Modifier and Type	Method	Description
static int	getMajorVersion()	Returns the major version number of the JLine library.
static int	getMinorVersion()	Returns the minor version number of the JLine library.
static String	getNativeLibraryPath()	Returns the absolute path to the loaded native library file.
static String	getNativeLibrarySourceUrl()	Returns the source URL from which the native library was loaded.
static String	getVersion()	Returns the full version string of the JLine library.
static boolean	initialize()	Loads the JLine native library for the current platform.

Methods inherited from class java.lang.Object

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

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

public static String 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

public static String 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:

• getVersion()

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()

getVersion

public static String 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.