Package com.xmlmind.util

## Class SystemUtil

- java.lang.Object
- - com.xmlmind.util.SystemUtil

-     public final class SystemUtil
      extends Object

  A collection of utility functions (static methods) which complements what's found in `java.lang.System`.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static boolean` | `IS_GENERIC_UNIX` | `true` if `PLATFORM` is `Platform.GENERIC_UNIX`.
    `static boolean` | `IS_MAC_OS` | `true` if `PLATFORM` is `Platform.MAC_OS`.
    `static boolean` | `IS_UNIX` | `true` if `PLATFORM` is not `Platform.WINDOWS`.
    `static boolean` | `IS_WINDOWS` | `true` if `PLATFORM` is `Platform.WINDOWS`.
    `static VersionNumber` | `JAVA_9_0_0` | Java v9.0.0.
    `static Platform` | `PLATFORM` | Returns the platform running this application: `Platform.WINDOWS`, `Platform.MAC_OS` or `Platform.GENERIC_UNIX`.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static int` | `captureOutput​(Process process, Console console)` | Captures output of specified newly started process (see `shellStart(String)`).
    `static int` | `captureOutput​(Process process, String[] capture)` | Captures output of specified newly started process (see `shellStart(String)`).
    `static File` | `currentWorkingDir()` | Returns the absolute, canonical directory corresponding to system property `user.dir` (that is, the current working directory) if this directory exists.
    `static String` | `defaultEncoding()` | Returns the default character encoding for this platform.
    `static File` | `defaultUserPreferencesDir()` | Equivalent to `userPreferencesDir("XMLmind", "XMLEditor11", "xxe11")`.
    `static File` | `findAppInPath​(String appName)` | Searches specified application using the `PATH` environment variable.
    `static boolean` | `hasJavaFX()` | Returns `true` if the current Java runtime has a usable, found by default in the `CLASSPATH`, JavaFX runtime.
    `static File` | `homeDir()` | Returns the absolute, canonical directory corresponding to system property `user.home` (that is, the home directory of the user of this application) if this directory exists.
    `static VersionNumber` | `javaVersionNumber()` | Returns the version number of current JavaTM runtime.
    `static String[]` | `listEncodings()` | Returns the canonical names of all the charsets supported by the Java runtime.
    `static VersionNumber` | `osVersionNumber()` | Returns the version number of the operating system.
    `static void` | `setUserPreferencesDir​(File dir)` | Specify a custom user preferences directory.
    `static int` | `shellExec​(String command)` | Equivalent to `shellExec(command, null, null, null)`.
    `static int` | `shellExec​(String command, String[] capture)` | Equivalent to `shellExec(command, null, null, capture)`.
    `static int` | `shellExec​(String command, String[] envp, File dir)` | Equivalent to `shellExec(command, envp, dir, null)`.
    `static int` | `shellExec​(String command, String[] envp, File dir, Console console)` | Executes a command using the standard shell of the platform.
    `static int` | `shellExec​(String command, String[] envp, File dir, String[] capture)` | Executes a command using the standard shell of the platform, capturing output to `System.out` and `System.err`.
    `static Process` | `shellStart​(String command)` | Equivalent to `shellStart(command, null, null)`.
    `static Process` | `shellStart​(String command, String[] envp, File dir)` | Executes a command using the standard shell of the platform.
    `static File` | `userPreferencesDir()` | Returns the user preferences directory of this application.
    `static File` | `userPreferencesDir​(String vendor, String product, String app)` | Returns the directory used to store the preferences of specified application.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PLATFORM

          public static final Platform PLATFORM

      Returns the platform running this application: `Platform.WINDOWS`, `Platform.MAC_OS` or `Platform.GENERIC_UNIX`.

    - #### IS_WINDOWS

          public static final boolean IS_WINDOWS

      `true` if `PLATFORM` is `Platform.WINDOWS`.

    - #### IS_UNIX

          public static final boolean IS_UNIX

      `true` if `PLATFORM` is not `Platform.WINDOWS`.

    - #### IS_MAC_OS

          public static final boolean IS_MAC_OS

      `true` if `PLATFORM` is `Platform.MAC_OS`.

    - #### IS_GENERIC_UNIX

          public static final boolean IS_GENERIC_UNIX

      `true` if `PLATFORM` is `Platform.GENERIC_UNIX`.

    - #### JAVA_9_0_0

          public static final VersionNumber JAVA_9_0_0

      Java v9.0.0. (Java 9+ has native support for HiDPI.)

  - ### Method Detail

    - #### homeDir

          public static File homeDir()

      Returns the absolute, canonical directory corresponding to system property `user.home` (that is, the home directory of the user of this application) if this directory exists. Returns `null` otherwise.

    - #### currentWorkingDir

          public static File currentWorkingDir()

      Returns the absolute, canonical directory corresponding to system property `user.dir` (that is, the current working directory) if this directory exists. Returns `null` otherwise.

    - #### setUserPreferencesDir

          public static void setUserPreferencesDir​(File dir)

      Specify a custom user preferences directory.
      Parameters:
        `dir` - the custom user preferences directory The fact that `dir` exists or is a directory is not checked.

        Specify `null` to revert to the default user preferences directory of this application.

      See Also:
        `userPreferencesDir()`

    - #### userPreferencesDir

          public static File userPreferencesDir()

      Returns the user preferences directory of this application. More precisely:
      - Returns the custom user preferences directory, if specified using `setUserPreferencesDir(java.io.File)`.
      - Otherwise returns the default user preferences directory.
      See Also:
        `defaultUserPreferencesDir()`

    - #### defaultUserPreferencesDir

          public static File defaultUserPreferencesDir()

      Equivalent to `userPreferencesDir("XMLmind", "XMLEditor11", "xxe11")`.

    - #### userPreferencesDir

          public static File userPreferencesDir​(String vendor,
                                                String product,
                                                String app)

      Returns the directory used to store the preferences of specified application.

      Example: vendor="XMLmind", product="XMLEditor", app="xxe":

      - $HOME/.xxe/ on Linux, FreeBSD, etc.
      - $HOME/Library/Application Support/XMLmind/XMLEditor on macOS.
      - %APPDATA%\XMLmind\XMLEditor\ on Windows.
      Parameters:
        `vendor` - name of the vendor of the product
        `product` - official product name
        `app` - nickname of the product
      Returns:
        the user preferences directory.

        Returns `null` if system property `user.home` is not set or does not specify an existing directory.

        The returned canonical file may specify a directory which does not exist yet and/or which may be impossible to create.

    - #### defaultEncoding

          public static String defaultEncoding()

      Returns the default character encoding for this platform.
      Returns:
        canonical name of default charset for this platform

    - #### listEncodings

          public static String[] listEncodings()

      Returns the canonical names of all the charsets supported by the Java runtime. The returned array is sorted.

    - #### javaVersionNumber

          public static VersionNumber javaVersionNumber()

      Returns the version number of current JavaTM runtime.

      If the system property "`java.version`" does not exist or cannot be parsed, returns 1.8.0.

    - #### hasJavaFX

          public static final boolean hasJavaFX()

      Returns `true` if the current Java runtime has a usable, found by default in the `CLASSPATH`, JavaFX runtime.
      - As of Java 1.8.0_40, Oracle Java includes JavaFX.
      - As of Java 11, Oracle Java no longer includes JavaFX.
      - OpenJDK does not include JavaFX.

    - #### osVersionNumber

          public static VersionNumber osVersionNumber()

      Returns the version number of the operating system.

      If the system property "`os.version`" does not exist or cannot be parsed, returns `null`.

    - #### shellStart

          public static Process shellStart​(String command)
                                    throws IOException

      Equivalent to `shellStart(command, null, null)`.
      Throws:
        `IOException`

    - #### shellStart

          public static Process shellStart​(String command,
                                           String[] envp,
                                           File dir)
                                    throws IOException

      Executes a command using the standard shell of the platform. Unlike `shellExec(java.lang.String, java.lang.String[])`, does not wait until the command is completed.
      Parameters:
        `command` - the shell command to be executed
        `envp` - array of pairs: environment variable name/value. Specify `null` to inherit the environment settings of the current process.
        `dir` - the working directory of the subprocess. Specify `null` to inherit the working directory of the current process.
      Returns:
        the process of the shell
      Throws:
        `IOException` - if an I/O error occurs

    - #### shellExec

          public static int shellExec​(String command,
                                      String[] capture)
                               throws IOException,
                                      InterruptedException

      Equivalent to `shellExec(command, null, null, capture)`.
      Throws:
        `IOException`
        `InterruptedException`

    - #### shellExec

          public static int shellExec​(String command,
                                      String[] envp,
                                      File dir,
                                      String[] capture)
                               throws IOException,
                                      InterruptedException

      Executes a command using the standard shell of the platform, capturing output to `System.out` and `System.err`.
      Parameters:
        `command` - the shell command to be executed
        `envp` - array of pairs: environment variable name/value. Specify `null` to inherit the environment settings of the current process.
        `dir` - the working directory of the subprocess. Specify `null` to inherit the working directory of the current process.
        `capture` - output to `System.out` is captured and saved to `capture[0]` and output to `System.err` is captured and saved to `capture[1]`. May not be `null`.
      Returns:
        the exit status returned by the shell
      Throws:
        `IOException` - if an I/O error occurs
        `InterruptedException` - if the current thread is interrupted by another thread while it is waiting the completion of the shell command

    - #### captureOutput

          public static int captureOutput​(Process process,
                                          String[] capture)
                                   throws InterruptedException

      Captures output of specified newly started process (see `shellStart(String)`).
      Parameters:
        `process` - newly started process
        `capture` - output to `System.out` is captured and saved to `capture[0]` and output to `System.err` is captured and saved to `capture[1]`. May not be `null`.
      Returns:
        exit status of process
      Throws:
        `InterruptedException` - if the current thread is interrupted by another thread while it is waiting the completion of the process

    - #### shellExec

          public static int shellExec​(String command)
                               throws IOException,
                                      InterruptedException

      Equivalent to `shellExec(command, null, null, null)`.
      Throws:
        `IOException`
        `InterruptedException`

    - #### shellExec

          public static int shellExec​(String command,
                                      String[] envp,
                                      File dir)
                               throws IOException,
                                      InterruptedException

      Equivalent to `shellExec(command, envp, dir, null)`.
      Throws:
        `IOException`
        `InterruptedException`

    - #### shellExec

          public static int shellExec​(String command,
                                      String[] envp,
                                      File dir,
                                      Console console)
                               throws IOException,
                                      InterruptedException

      Executes a command using the standard shell of the platform.
      Parameters:
        `command` - the shell command to be executed
        `envp` - array of pairs: environment variable name/value. Specify `null` to inherit the environment settings of the current process.
        `dir` - the working directory of the subprocess. Specify `null` to inherit the working directory of the current process.
        `console` - output to `System.out` is displayed by this console as `Console.MessageType.INFO` messages and output to `System.err` is is displayed by this console as `Console.MessageType.ERROR` messages. May be `null`.
      Returns:
        the exit status returned by the shell
      Throws:
        `IOException` - if an I/O error occurs
        `InterruptedException` - if the current thread is interrupted by another thread while it is waiting the completion of the shell command

    - #### captureOutput

          public static int captureOutput​(Process process,
                                          Console console)
                                   throws InterruptedException

      Captures output of specified newly started process (see `shellStart(String)`).
      Parameters:
        `process` - newly started process
        `console` - output to `System.out` is captured and displayed as INFO messages on this console and output to `System.err` is captured and sisplayed as ERROR messages on this console. May be `null`.
      Returns:
        exit status of process
      Throws:
        `InterruptedException` - if the current thread is interrupted by another thread while it is waiting the completion of the process

    - #### findAppInPath

          public static File findAppInPath​(String appName)

      Searches specified application using the `PATH` environment variable.
      Parameters:
        `appName` - the basename of the executable file of the application.

        On Windows, this basename may have no extension. In such case, all the extensions found in the the `PATHEXT` environment variable (".exe", ".bat", etc), are tried in turn.

      Returns:
        the absolute filename of the application if found; `null` otherwise.