Package com.tableau.hyperapi

## Class Connection

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

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

      public final class Connection
      extends java.lang.Object
      implements java.lang.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, java.lang.String database)` | Connects to a hyper endpoint.
    `Connection​(Endpoint endpoint, java.lang.String[] databases)` | Connects to a hyper endpoint.
    `Connection​(Endpoint endpoint, java.lang.String[] databases, CreateMode createMode, java.util.Map<java.lang.String,​java.lang.String> parameters)` | Connects to a hyper endpoint.
    `Connection​(Endpoint endpoint, java.lang.String database, CreateMode createMode)` | Connects to a hyper endpoint.
    `Connection​(Endpoint endpoint, java.lang.String database, CreateMode createMode, java.util.Map<java.lang.String,​java.lang.String> parameters)` | Connects to a hyper endpoint.
    `Connection​(Endpoint endpoint, java.util.Map<java.lang.String,​java.lang.String> parameters)` | Connects to a hyper endpoint.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    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.
    `java.util.OptionalLong` | `executeCommand​(java.lang.String sql)` | Execute a SQL command and return the affected row count, if any.
    `Result` | `executeQuery​(java.lang.String sql)` | Executes a SQL statement and return its result.
    `<T> java.util.Optional<T>` | `executeScalarQuery​(java.lang.String sql)` | Executes a scalar query that returns a single value.
    `Catalog` | `getCatalog()` | Gets the catalog for this connection.
    `HyperServiceVersion` | `getHyperServiceVersion()` | Returns the Hyper Service version of this connection
    `boolean` | `isCapabilityActive​(java.lang.String capabilityFlag)` | Returns true if the capability flag is active on 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.
    `static java.util.List<HyperServiceVersion>` | `querySupportedHyperServiceVersionRange​(Endpoint endpoint)` | Connects to the Hyper endpoint and determines which Hyper Service version numbers are common between the Hyper API and the Hyper server.

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

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

- - ### Constructor Detail

    - #### Connection

          public Connection​(Endpoint endpoint,
                            java.lang.String database,
                            CreateMode createMode,
                            java.util.Map<java.lang.String,​java.lang.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,
                            java.lang.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,
                            java.lang.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,
                            java.lang.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,
                            java.util.Map<java.lang.String,​java.lang.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,
                            java.lang.String[] databases,
                            CreateMode createMode,
                            java.util.Map<java.lang.String,​java.lang.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 Detail

    - #### executeQuery

          public Result executeQuery​(java.lang.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 java.util.OptionalLong executeCommand​(java.lang.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> java.util.Optional<T> executeScalarQuery​(java.lang.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.

    - #### getHyperServiceVersion

          public HyperServiceVersion getHyperServiceVersion()

      Returns the Hyper Service version of this connection
      Returns:
        The Hyper Service version of this connection.

    - #### isCapabilityActive

          public boolean isCapabilityActive​(java.lang.String capabilityFlag)

      Returns true if the capability flag is active on this connection.
      Parameters:
        `capabilityFlag` - The capability flag to check, is prefixed with `capability_`
      Returns:
        true if the capability flag is active on this connection.

    - #### querySupportedHyperServiceVersionRange

          public static java.util.List<HyperServiceVersion> querySupportedHyperServiceVersionRange​(Endpoint endpoint)

      Connects to the Hyper endpoint and determines which Hyper Service version numbers are common between the Hyper API and the Hyper server.
      Parameters:
        `endpoint` - Endpoint to connect to.
      Returns:
        List of Hyper Service versions that are supported by both this HAPI and the endpoint.
      Throws:
        `HyperException` - If connecting failed.

    - #### 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 `java.lang.AutoCloseable`