public final class Connection
extends java.lang.Object
implements java.lang.AutoCloseable
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 and Description |
---|
Connection(Endpoint endpoint)
Connects to a hyper endpoint.
|
Connection(Endpoint endpoint,
java.util.Map<java.lang.String,java.lang.String> parameters)
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.
|
Modifier and Type | Method and 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.
|
public Connection(Endpoint endpoint, java.lang.String database, CreateMode createMode, java.util.Map<java.lang.String,java.lang.String> parameters)
Throws if connecting to this endpoint is not supported by the version of the API.
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".HyperException
- An error is thrown when the connection fails.public Connection(Endpoint endpoint, java.lang.String database, CreateMode createMode)
Throws if connecting to this endpoint is not supported by the version of the API.
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.HyperException
- An error is thrown when the connection fails.public Connection(Endpoint endpoint, java.lang.String database)
Throws if connecting to this endpoint is not supported by the version of the API.
endpoint
- The endpoint to connect to.database
- The database to connect to. Database must exist.HyperException
- An error is thrown when the connection fails.public Connection(Endpoint endpoint, java.lang.String[] databases)
Throws if connecting to this endpoint is not supported by the version of the API.
endpoint
- The endpoint to connect to.databases
- The databases to connect to. Databases must exist.HyperException
- An error is thrown when the connection fails.public Connection(Endpoint endpoint)
Throws if connecting to this endpoint is not supported by the version of the API.
endpoint
- The endpoint to connect to.HyperException
- An error is thrown when the connection fails.public Connection(Endpoint endpoint, java.util.Map<java.lang.String,java.lang.String> parameters)
Throws if connecting to this endpoint is not supported by the version of the API.
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".HyperException
- An error is thrown when the connection fails.public Connection(Endpoint endpoint, java.lang.String[] databases, CreateMode createMode, java.util.Map<java.lang.String,java.lang.String> parameters)
Throws if connecting to this endpoint is not supported by the version of the API.
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".HyperException
- An error is thrown when the connection fails.public Result executeQuery(java.lang.String sql)
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.
sql
- The query.HyperException
- when Hyper can't execute the statement.public java.util.OptionalLong executeCommand(java.lang.String sql)
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.
sql
- The query.HyperException
- when Hyper can't execute the statement.public <T> java.util.Optional<T> executeScalarQuery(java.lang.String sql)
The query must return exactly one row with one column.
T
- The type of the single value.sql
- The query.HyperException
- when Hyper cannot execute the statement, it returns more than one row or column, or no row
or no column.public HyperServiceVersion getHyperServiceVersion()
public boolean isCapabilityActive(java.lang.String capabilityFlag)
capabilityFlag
- The capability flag to check, is prefixed with `capability_`public static java.util.List<HyperServiceVersion> querySupportedHyperServiceVersionRange(Endpoint endpoint)
endpoint
- Endpoint to connect to.HyperException
- If connecting failed.public Catalog getCatalog()
public void cancel()
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.
public boolean isReady()
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)
HyperException
- Thrown when the connection is closed.public boolean isOpen()
public void close()
close
in interface java.lang.AutoCloseable