Package com.norconex.commons.lang

# Class SystemUtil

java.lang.Object
com.norconex.commons.lang.SystemUtil

public final class SystemUtil extends Object
System-related convenience methods.

Since:
  2.0.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `SystemUtil.Captured<T>`
  Holds possible return value and standard output/error when invoking `callAndCaptureOutput(Callable)` or `runAndCaptureOutput(Runnable)`.
  `static class`
  `SystemUtil.UncheckedCallableException`
  Runtime exception wrapping possible exceptions thrown by invoking `Callable` by one of `SystemUtil` methods.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> SystemUtil.Captured<T>`
  `callAndCaptureOutput(Callable<T> callable)`
  Executes a `Callable` and return its value along with any standard output or error (i.e., STDOUT/STDERR).
  `static <T> T`
  `callWithProperty(String name, String value, Callable<T> callable)`
  Executes the supplied `Callable` after setting the system property and then resets that system property.
  `static String`
  `getEnvironment(String name)`
  Gets the value of the specified environment variable matching the exact name, or a supported variant.
  `static String`
  `getEnvironmentOrProperty(String name)`
  Gets the environment variable or system property matching the exact name, or a supported variant.
  `static String`
  `getProperty(String name)`
  Gets the value of the system property matching the exact name, or a supported variant.
  `static String`
  `getPropertyOrEnvironment(String name)`
  Gets the system property or environment variable matching the exact name, or a supported variant.
  `static SystemUtil.Captured<Void>`
  `runAndCaptureOutput(Runnable runnable)`
  Executes a `Runnable` and return any standard output or error (i.e., STDOUT/STDERR).
  `static void`
  `runWithProperty(String name, String value, Runnable runnable)`
  Executes the supplied `Runnable` after setting the system property and then resets that system property.
  `static <T> SystemUtil.Captured<T>`
  `withOutputCapture(Callable<T> callable)`
  Same as `callAndCaptureOutput(Callable)` but with no thread-safety guarantee.

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

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

- ## Method Details

  - ### withOutputCapture

    public static <T> SystemUtil.Captured<T> withOutputCapture(Callable<T> callable)
    Same as `callAndCaptureOutput(Callable)` but with no thread-safety guarantee. This method is not synchronized.
    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `callable` - the code to execute
    Returns:
      captured return value and standard output/error
    Throws:
      `SystemUtil.UncheckedCallableException` - wrapper around any `Callable` exception
    Since:
      3.0.0

  - ### callAndCaptureOutput

    public static <T> SystemUtil.Captured<T> callAndCaptureOutput(Callable<T> callable)
    Executes a `Callable` and return its value along with any standard output or error (i.e., STDOUT/STDERR). While this method is synchronized, nothing prevent other threads from also writing to `System.out` or `System.err`. For this reason this method should not be considered thread-safe.
    Type Parameters:
      `T` - the type of the return value
    Parameters:
      `callable` - the code to execute
    Returns:
      captured return value and standard output/error
    Throws:
      `SystemUtil.UncheckedCallableException` - wrapper around any `Callable` exception
    Since:
      3.0.0

  - ### runAndCaptureOutput

    public static SystemUtil.Captured<Void> runAndCaptureOutput(Runnable runnable)
    Executes a `Runnable` and return any standard output or error (i.e., STDOUT/STDERR). While this method is synchronized, nothing prevent other threads from also writing to `System.out` or `System.err`. For this reason this method should not be considered thread-safe.
    Parameters:
      `runnable` - the code to execute
    Returns:
      captured standard output/error
    Since:
      3.0.0

  - ### runWithProperty

    public static void runWithProperty(String name, String value, Runnable runnable)

    Executes the supplied `Runnable` after setting the system property and then resets that system property. This method is synchronized to make sure setting the property does not affect other threads. The system property is restored to its original value (if any) after execution. Useful when the invoked code expects a system property that is configurable and may change from one thread to another.

    #### `null` handling

    This method is `null`-safe. If the runnable is `null`, invoking this method has no effect. If the property name is `null`, the runnable is invoked without setting any property beforehand. If the property value is `null`, it will temporary clear any existing system property with the same name (if any) for the duration of the execution.

    Parameters:
      `name` - system property name
      `value` - system property value
      `runnable` - code to run with the system property set

  - ### callWithProperty

    public static <T> T callWithProperty(String name, String value, Callable<T> callable)

    Executes the supplied `Callable` after setting the system property and then resets that system property. This method is synchronized to make sure setting the property does not affect other threads. The system property is restored to its original value (if any) after execution. Useful when the invoked code expects a system property that is configurable and may change from one thread to another.

    #### `null` handling

    This method is `null`-safe. If the callable is `null`, invoking this method returns `null`. If the property name is `null`, the runnable is invoked without setting any property beforehand. If the property value is `null`, it will temporary clear any existing system property with the same name (if any) for the duration of the execution.

    Type Parameters:
      `T` - class type of return value
    Parameters:
      `name` - system property name
      `value` - system property value
      `callable` - code to run with the system property set
    Returns:
      the callable return value
    Throws:
      `SystemUtil.UncheckedCallableException` - wrapper around any `Callable` exception

  - ### getEnvironmentOrProperty

    public static String getEnvironmentOrProperty(String name)
    Gets the environment variable or system property matching the exact name, or a supported variant. Same as invoking `getEnvironment(String)` and if `null`, invoking `getProperty(String)`.
    Parameters:
      `name` - property or environment name
    Returns:
      property or environment value

  - ### getPropertyOrEnvironment

    public static String getPropertyOrEnvironment(String name)
    Gets the system property or environment variable matching the exact name, or a supported variant. Same as invoking `getProperty(String)` and if `null`, invoking `getEnvironment(String)`.
    Parameters:
      `name` - environment or property name
    Returns:
      environment or property value

  - ### getEnvironment

    public static String getEnvironment(String name)
    Gets the value of the specified environment variable matching the exact name, or a supported variant. First, it looks for a direct environment variable name match, as with `System.getenv(String)`. If no matches are found, it will iterate through all environment variables names and compare them all with the requested name, but only after stripping all non alpha-numeric characters and ignoring case.
    Parameters:
      `name` - the name of the environment variable
    Returns:
      environment variable value

  - ### getProperty

    public static String getProperty(String name)
    Gets the value of the system property matching the exact name, or a supported variant. First, it looks for a direct property name match, as with `System.getProperty(String)`. If no matches are found, it will iterate through all system property names and compare them all with the requested name, but only after stripping all non alpha-numeric characters and ignoring case.
    Parameters:
      `name` - the name of the system property
    Returns:
      system property value