Package com.tableau.hyperapi

Class 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