Package com.tableau.hyperapi

## Class HyperProcess

- java.lang.Object
- - com.tableau.hyperapi.HyperProcess

- All Implemented Interfaces:
    `java.lang.AutoCloseable`

      public final class HyperProcess
      extends java.lang.Object
      implements java.lang.AutoCloseable

  Defines a Hyper process. This class starts Hyper and manages its lifetime.

  This is an `AutoCloseable` class since it maintains native resources. The Hyper process must always be closed when it is no longer needed. The best way to guarantee this is to use a try-with-resources block.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `HyperProcess​(Telemetry telemetry)` | Starts a new Hyper process trying to automatically locate the Hyper binary.
    `HyperProcess​(Telemetry telemetry, java.lang.String userAgent)` | Starts a new Hyper process trying to automatically locate the Hyper binary.
    `HyperProcess​(Telemetry telemetry, java.lang.String userAgent, java.util.Map<java.lang.String,​java.lang.String> parameters)` | Starts a new Hyper process trying to automatically locate the Hyper binary.
    `HyperProcess​(java.nio.file.Path hyperPath, Telemetry telemetry)` | Starts a new Hyper process using the given path to the Hyper executable.
    `HyperProcess​(java.nio.file.Path hyperPath, Telemetry telemetry, java.lang.String userAgent)` | Starts a new Hyper process using the given path to the Hyper executable.
    `HyperProcess​(java.nio.file.Path hyperPath, Telemetry telemetry, java.lang.String userAgent, java.util.Map<java.lang.String,​java.lang.String> parameters)` | Starts a new Hyper process using the given path to the Hyper executable.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Closes this Hyper process object, relinquishing the underlying native handle.
    `Endpoint` | `getEndpoint()` | Returns the endpoint descriptor of the Hyper process.
    `boolean` | `isOpen()` | Returns whether the Hyper process is open.
    `void` | `shutdown()` | Shuts down the Hyper process and waits for it to exit.
    `void` | `shutdown​(int timeoutMs)` | Shuts down the Hyper process.

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

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

- - ### Constructor Detail

    - #### HyperProcess

          public HyperProcess​(java.nio.file.Path hyperPath,
                              Telemetry telemetry,
                              java.lang.String userAgent,
                              java.util.Map<java.lang.String,​java.lang.String> parameters)

      Starts a new Hyper process using the given path to the Hyper executable.
      Parameters:
        `hyperPath` - The file path to the Hyper executable.
        `telemetry` - Whether to send telemetry to Tableau.
        `userAgent` - A user agent string, which will be used in telemetry and logging/
        `parameters` - Optional parameters for starting the Hyper process. The available parameters are documented in the Tableau Hyper documentation, chapter "Process Settings".
      Throws:
        `HyperException` - Thrown when starting the Hyper process fails.

    - #### HyperProcess

          public HyperProcess​(java.nio.file.Path hyperPath,
                              Telemetry telemetry,
                              java.lang.String userAgent)

      Starts a new Hyper process using the given path to the Hyper executable.
      Parameters:
        `hyperPath` - The file path to the Hyper executable.
        `telemetry` - Whether to send telemetry to Tableau.
        `userAgent` - A user agent string, which will be used in telemetry and logging/
      Throws:
        `HyperException` - Thrown when starting the Hyper process fails.

    - #### HyperProcess

          public HyperProcess​(Telemetry telemetry,
                              java.lang.String userAgent,
                              java.util.Map<java.lang.String,​java.lang.String> parameters)

      Starts a new Hyper process trying to automatically locate the Hyper binary.

      Tries to locate the Hyper binaries by locating the JAR file. The JAR file is assumed to reside in a libraries directory that contains the Hyper binaries in a "hyper" subfolder.

      Parameters:
        `telemetry` - Whether to send telemetry to Tableau.
        `userAgent` - A user agent string, which will be used in telemetry and logging.
        `parameters` - Optional parameters for starting the Hyper process. The available parameters are documented in the Tableau Hyper documentation, chapter "Process Settings".
      Throws:
        `HyperException` - Thrown when starting the Hyper process fails.

    - #### HyperProcess

          public HyperProcess​(Telemetry telemetry,
                              java.lang.String userAgent)

      Starts a new Hyper process trying to automatically locate the Hyper binary.

      Tries to locate the Hyper binaries by locating the JAR file. The JAR file is assumed to reside in a libraries directory that is on the same level as a "bin" directory that contains the Hyper binaries in a "hyper" subfolder.

      Parameters:
        `telemetry` - Whether to send telemetry to Tableau.
        `userAgent` - A user agent string, which will be used in telemetry and logging.
      Throws:
        `HyperException` - Thrown when starting the Hyper process fails.

    - #### HyperProcess

          public HyperProcess​(java.nio.file.Path hyperPath,
                              Telemetry telemetry)

      Starts a new Hyper process using the given path to the Hyper executable.
      Parameters:
        `hyperPath` - The file path to the Hyper executable.
        `telemetry` - Whether to send telemetry to Tableau.
      Throws:
        `HyperException` - Thrown when starting the Hyper process fails.

    - #### HyperProcess

          public HyperProcess​(Telemetry telemetry)

      Starts a new Hyper process trying to automatically locate the Hyper binary.

      Tries to locate the Hyper binaries by locating the JAR file. The JAR file is assumed to reside in a libraries directory that is on the same level as a "bin" directory that contains the Hyper binaries in a "hyper" subfolder.

      Parameters:
        `telemetry` - Whether to send telemetry to Tableau.
      Throws:
        `HyperException` - Thrown when starting the Hyper process fails.

  - ### Method Detail

    - #### shutdown

          public void shutdown​(int timeoutMs)

      Shuts down the Hyper process.

      If timeoutMs > 0ms, wait for Hyper to shut down gracefully. If the process is still running after a timeout of timeoutMs milliseconds, terminate the process forcefully and throw an exception.

      If timeoutMs < 0ms, wait indefinitely for Hyper to shut down.

      If timeoutMs == 0ms, immediately terminate Hyper forcefully. Does not throw if the process already exited with a non-zero exit code.

      Parameters:
        `timeoutMs` - The timeout in milliseconds
      Throws:
        `HyperException` - Thrown if there was an error stopping the process, if the process was forcefully killed after the timeout, or if the process already exited with a non-zero exit code.

    - #### shutdown

          public void shutdown()

      Shuts down the Hyper process and waits for it to exit.
      Throws:
        `HyperException` - Thrown if there was an error stopping the process, if the process was forcefully killed after the timeout, or if the process already exited with a non-zero exit code.

    - #### getEndpoint

          public Endpoint getEndpoint()

      Returns the endpoint descriptor of the Hyper process. The descriptor is of the Tableau IPC form, e.g., "tab.tcp://[::1]:7483".
      Returns:
        The endpoint descriptor.

    - #### isOpen

          public boolean isOpen()

      Returns whether the Hyper process is open.
      Returns:
        Whether the Hyper process is open.

    - #### close

          public void close()

      Closes this Hyper process object, relinquishing the underlying native handle.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`