Class JLineNativeLoader


  • public class JLineNativeLoader
    extends java.lang.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
    • Method Summary

      All Methods Static Methods Concrete Methods 
      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 java.lang.String getNativeLibraryPath()
      Returns the absolute path to the loaded native library file.
      static java.lang.String getNativeLibrarySourceUrl()
      Returns the source URL from which the native library was loaded.
      static java.lang.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 Detail

      • JLineNativeLoader

        public JLineNativeLoader()
    • Method Detail

      • 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:
        java.lang.RuntimeException - If the native library cannot be loaded for any reason.
      • getNativeLibraryPath

        public static java.lang.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 java.lang.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 java.lang.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.