Package com.tableau.hyperapi

# Class Connection

java.lang.Object
com.tableau.hyperapi.Connection

All Implemented Interfaces:
  `AutoCloseable`

public final class Connection extends Object implements AutoCloseable
Defines a Hyper connection.

Used for all interactions with Hyper.

This is an `AutoCloseable` class since it maintains native resources. The `close()` method must always be called when the connection is no longer needed. The best way to guarantee this is to use a try-with-resources block.

This class is not thread-safe, no two methods may be called simultaneously from different threads. The only exception is `cancel()`, which may be safely called from a different thread.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Connection(Endpoint endpoint)`
  Connects to a hyper endpoint.
  `Connection(Endpoint endpoint, String database)`
  Connects to a hyper endpoint.
  `Connection(Endpoint endpoint, String[] databases)`
  Connects to a hyper endpoint.
  `Connection(Endpoint endpoint, String[] databases, CreateMode createMode, Map<String,String> parameters)`
  Connects to a hyper endpoint.
  `Connection(Endpoint endpoint, String database, CreateMode createMode)`
  Connects to a hyper endpoint.
  `Connection(Endpoint endpoint, String database, CreateMode createMode, Map<String,String> parameters)`
  Connects to a hyper endpoint.
  `Connection(Endpoint endpoint, Map<String,String> parameters)`
  Connects to a hyper endpoint.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cancel()`
  Cancels the current query on this connection.
  `void`
  `close()`
  Closes this connection object, relinquishing the underlying native handle.
  `OptionalLong`
  `executeCommand(String sql)`
  Execute a SQL command and return the affected row count, if any.
  `Result`
  `executeQuery(String sql)`
  Executes a SQL statement and return its result.
  `<T> Optional<T>`
  `executeScalarQuery(String sql)`
  Executes a scalar query that returns a single value.
  `Catalog`
  `getCatalog()`
  Gets the catalog for this connection.
  `boolean`
  `isOpen()`
  Returns whether the connection is open.
  `boolean`
  `isReady()`
  Checks whether the connection is ready, i.e., if the connection can be used.

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

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

- ## Constructor Details

  - ### Connection

    public Connection(Endpoint endpoint, String database, CreateMode createMode, Map<String,String> parameters)
    Connects to a hyper endpoint.

    Throws if connecting to this endpoint is not supported by the version of the API.

    Parameters:
      `endpoint` - The endpoint to connect to.
      `database` - The database to connect to.
      `createMode` - Whether the database should be created and what to do in case of an already existing database.
      `parameters` - Optional connection parameters to pass to Hyper. The available parameters are documented in the Tableau Hyper documentation, chapter "Connection Settings".
    Throws:
      `HyperException` - An error is thrown when the connection fails.

  - ### Connection

    public Connection(Endpoint endpoint, String database, CreateMode createMode)
    Connects to a hyper endpoint.

    Throws if connecting to this endpoint is not supported by the version of the API.

    Parameters:
      `endpoint` - The endpoint to connect to.
      `database` - The database to connect to.
      `createMode` - Whether the database should be created and what to do in case of an already existing database.
    Throws:
      `HyperException` - An error is thrown when the connection fails.

  - ### Connection

    public Connection(Endpoint endpoint, String database)
    Connects to a hyper endpoint.

    Throws if connecting to this endpoint is not supported by the version of the API.

    Parameters:
      `endpoint` - The endpoint to connect to.
      `database` - The database to connect to. Database must exist.
    Throws:
      `HyperException` - An error is thrown when the connection fails.

  - ### Connection

    public Connection(Endpoint endpoint, String[] databases)
    Connects to a hyper endpoint.

    Throws if connecting to this endpoint is not supported by the version of the API.

    Parameters:
      `endpoint` - The endpoint to connect to.
      `databases` - The databases to connect to. Databases must exist.
    Throws:
      `HyperException` - An error is thrown when the connection fails.

  - ### Connection

    public Connection(Endpoint endpoint)
    Connects to a hyper endpoint.

    Throws if connecting to this endpoint is not supported by the version of the API.

    Parameters:
      `endpoint` - The endpoint to connect to.
    Throws:
      `HyperException` - An error is thrown when the connection fails.

  - ### Connection

    public Connection(Endpoint endpoint, Map<String,String> parameters)
    Connects to a hyper endpoint.

    Throws if connecting to this endpoint is not supported by the version of the API.

    Parameters:
      `endpoint` - The endpoint to connect to.
      `parameters` - Optional connection parameters to pass to Hyper. The available parameters are documented in the Tableau Hyper documentation, chapter "Connection Settings".
    Throws:
      `HyperException` - An error is thrown when the connection fails.

  - ### Connection

    public Connection(Endpoint endpoint, String[] databases, CreateMode createMode, Map<String,String> parameters)
    Connects to a hyper endpoint.

    Throws if connecting to this endpoint is not supported by the version of the API.

    Parameters:
      `endpoint` - The endpoint to connect to.
      `databases` - The databases to connect to.
      `createMode` - Whether the database should be created and what to do in case of an already existing database.
      `parameters` - Optional connection parameters to pass to Hyper. The available parameters are documented in the Tableau Hyper documentation, chapter "Connection Settings".
    Throws:
      `HyperException` - An error is thrown when the connection fails.

- ## Method Details

  - ### executeQuery

    public Result executeQuery(String sql)
    Executes a SQL statement and return its result.

    This method can be used to execute any SQL command, even if it doesn't return a result. In this case, the result will be empty. If you don't need a result, use executeCommand instead.

    Parameters:
      `sql` - The query.
    Returns:
      The result of the SQL statement.
    Throws:
      `HyperException` - when Hyper can't execute the statement.

  - ### executeCommand

    public OptionalLong executeCommand(String sql)
    Execute a SQL command and return the affected row count, if any.

    If the SQL statement is an UPDATE, INSERT, or DELETE statement, then this method will return the number of affected rows. Note that this method can be used to execute any SQL command.

    Parameters:
      `sql` - The query.
    Returns:
      The modified row count of the SQL command if it has one.
    Throws:
      `HyperException` - when Hyper can't execute the statement.

  - ### executeScalarQuery

    public <T> Optional<T> executeScalarQuery(String sql)
    Executes a scalar query that returns a single value.

    The query must return exactly one row with one column.

    Type Parameters:
      `T` - The type of the single value.
    Parameters:
      `sql` - The query.
    Returns:
      The optional scalar result of the query. Optional.empty() if value is null.
    Throws:
      `HyperException` - when Hyper cannot execute the statement, it returns more than one row or column, or no row or no column.

  - ### getCatalog

    public Catalog getCatalog()
    Gets the catalog for this connection.
    Returns:
      The catalog.

  - ### cancel

    public void cancel()
    Cancels the current query on this connection.

    This is a best-effort method that does not return any result and never throws. Whether a cancel actually happened cannot be determined. This method is thread-safe, it may be safely called from a different thread.

  - ### isReady

    public boolean isReady()
    Checks whether the connection is ready, i.e., if the connection can be used.

    A connection that is not ready is currently processing a query, so using it for further query methods will throw a HyperException. Note that this method is not thread-safe; only use it on the same thread that potentially uses the connection. (Note that a non-ready connection doesn't mean that the thread is in a blocking call; an open Result for example always keeps the connection busy)

    Returns:
      Whether the connection is ready.
    Throws:
      `HyperException` - Thrown when the connection is closed.

  - ### isOpen

    public boolean isOpen()
    Returns whether the connection is open.
    Returns:
      Whether the connection is open.

  - ### close

    public void close()
    Closes this connection object, relinquishing the underlying native handle.
    Specified by:
      `close` in interface `AutoCloseable`