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 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