Package com.tableau.hyperapi

# Class HyperProcess

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

All Implemented Interfaces:
  `AutoCloseable`

public final class HyperProcess extends Object implements 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, String userAgent)`
  Starts a new Hyper process trying to automatically locate the Hyper binary.
  `HyperProcess(Telemetry telemetry, String userAgent, Map<String,String> parameters)`
  Starts a new Hyper process trying to automatically locate the Hyper binary.
  `HyperProcess(Path hyperPath, Telemetry telemetry)`
  Starts a new Hyper process using the given path to the Hyper executable.
  `HyperProcess(Path hyperPath, Telemetry telemetry, String userAgent)`
  Starts a new Hyper process using the given path to the Hyper executable.
  `HyperProcess(Path hyperPath, Telemetry telemetry, String userAgent, Map<String,String> parameters)`
  Starts a new Hyper process using the given path to the Hyper executable.

- ## Method Summary

  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 Details

  - ### HyperProcess

    public HyperProcess(Path hyperPath, Telemetry telemetry, String userAgent, Map<String,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(Path hyperPath, Telemetry telemetry, 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, String userAgent, Map<String,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, 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(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 Details

  - ### 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 `AutoCloseable`