com.aceql.client.jdbc

Class AceQLConnection

java.lang.Object

org.kawanfw.driver.jdbc.abstracts.AbstractConnection

com.aceql.client.jdbc.AceQLConnection

All Implemented Interfaces:

Closeable, AutoCloseable, Cloneable, Connection, Wrapper

public class AceQLConnection
extends org.kawanfw.driver.jdbc.abstracts.AbstractConnection
implements Connection, Cloneable, Closeable

Provides a Connection implementation that enable to use a virtual JDBC Connection that is mapped to a Server JDBC Connection in order to access a remote SQL database through HTTP.
This class acts as a wrapper of AceQL HTTP APIs.

This Connection implementation supports:

• Main JDBC data formats.
• Blob/Clob updates with clean streaming behavior when uploading.
• Blob/Clob reads with clean streaming behavior when downloading.
• Transaction through commit and rollback orders.

Supplementary specific methods that are not of instance of Connection are also added. After creating the AceQLConnection, just use it like a regular Connection to execute your PreparedStatement and Statement, and to navigate through your ResultSet.

All thrown exceptions are of type AceQLException. Use Throwable.getCause() to get the original wrapped Exception.

The AceQL error_type value is available via the AceQLException#getErrorCode() and the remote_stack value as a string is available with AceQLException.getRemoteStackTrace()

Example:

 // Define URL of the path to the AceQL Manager Servlet
 // We will use a secure SSL/TLS session. All uploads/downloads of SQL
 // commands & data will be encrypted.
 String url = "https://www.acme.org:9443/aceql";
 
 // The login info for strong authentication on server side.
 // These are *not* the username/password of the remote JDBC Driver,
 // but are the auth info checked by remote server
 // DatabaseConfigurator.login(username, password) method.
 String database = "mydatabase";
 String username = "MyUsername";
 String password = "MyPassword";
 
 // Attempts to establish a connection to the remote database:
 Connection connection = new AceQLConnection(serverUrl, database, username,
        password);
 
 // We can now use our remote JDBC Connection as a regular JDBC
 // Connection for our queries and updates:
 String sql = "SELECT CUSTOMER_ID, FNAME, LNAME FROM CUSTOMER "
        + "WHERE CUSTOMER_ID = ?";
 PreparedStatement prepStatement = connection.prepareStatement(sql);
 prepStatement.setInt(1, 1);
 
 ResultSet rs = prepStatement.executeQuery();
 while (rs.next()) {
     String customerId = rs.getString("customer_id");
     String fname = rs.getString("fname");
     String lname = rs.getString("lname");
 
     System.out.println("customer_id: " + customerId);
     System.out.println("fname      : " + fname);
     System.out.println("lname      : " + lname);
     // Etc.
 }
 

The following dedicated AceQLConnection methods are specific to the software and may be accessed with a cast:

• setCancelled(AtomicBoolean)
• setGzipResult(boolean)
• setPrettyPrinting(boolean)
• setProgress(AtomicInteger)

All long Blobs update/reading that need to be run on a separated thread may be followed in Swing using a JProgressBar, ProgressMonitor or Android using a ProgressDialog

This is done by sharing two atomic variables that will be declared as fields:

• An AtomicInteger that represents the Blob/Clob transfer progress between 0 and 100.
• An AtomicBoolean that says if the end user has cancelled the Blob/Clob transfer.

The atomic variables values will be shared by AceQL download/upload processes and by the Progress Monitor used for the Progress Bar. The values are to be initialized and passed to AceQLConnection before the JDBC actions with the setters:
setProgress(AtomicInteger)
setCancelled(AtomicBoolean)

Example:

 // Attempts to establish a connection to the remote database:
 Connection connection = new AceQLConnection(url, username, password,
        database);
 
 // Pass the mutable & sharable progress and canceled to the
 // underlying AceQLConnection.
 // - progress value will be updated by the AceQLConnection and
 // retrieved by progress monitors to increment the progress.
 // - cancelled value will be updated to true if user cancels the
 // task and AceQLConnection will interrupt the blob(s) transfer.
 
 ((AceQLConnection) connection).setProgress(progress);
 ((AceQLConnection) connection).setCancelled(cancelled);
 
 // Execute JDBC statement
 

See the source code of SqlProgressMonitorDemo.java that demonstrates the use of atomic variables when inserting a Blob.

Author:

Nicolas de Pomereu

Field Summary

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Constructor Summary

Constructors

Constructor and Description
AceQLConnection(String serverUrl, String database, String username, char[] password) Login on the AceQL server and connect to a database
AceQLConnection(String serverUrl, String database, String username, char[] password, Proxy proxy, PasswordAuthentication passwordAuthentication) Login on the AceQL server and connect to a database

Method Summary

Methods

Modifier and Type	Method and Description
Connection	clone()
void	close() Releases this Connection object's database and JDBC resources immediately instead of waiting for them to be automatically released.
void	commit() Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object.
Statement	createStatement() Creates a Statement object for sending SQL statements to the database.
boolean	getAutoCommit() Retrieves the current auto-commit mode for this Connection object.
AtomicBoolean	getCancelled() Returns the cancelled value set by the progress indicator
String	getClientVersion() Returns the SDK current Version.
int	getHoldability() Retrieves the current holdability of ResultSet objects created using this Connection object.
AtomicInteger	getProgress() Returns the sharable progress variable that will store Blob/Clob upload or download progress between 0 and 100
String	getServerVersion() Returns the server product version
int	getTransactionIsolation() Retrieves this Connection object's current transaction isolation level.
boolean	isClosed() Retrieves whether this Connection object has been closed.
boolean	isReadOnly() Retrieves whether this Connection object is in read-only mode.
static boolean	isTraceOn() Says if trace is on
void	logout()
PreparedStatement	prepareStatement(String sql) Creates a PreparedStatement object for sending parameterized SQL statements to the database.
void	rollback() Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object.
void	setAutoCommit(boolean autoCommit) Sets this connection's auto-commit mode to the given state.
void	setCancelled(AtomicBoolean cancelled) Sets the sharable canceled variable that will be used by the progress indicator to notify this instance that the user has cancelled the current Blob/Clob upload or download.
static void	setConnectTimeout(int connectTimeout) Sets the connect timeout.
void	setGzipResult(boolean gzipResult) Define if SQL result sets are returned compressed with the GZIP file format before download.
void	setHoldability(int holdability) Changes the holdability of ResultSet objects created using this Connection object to the given holdability.
void	setPrettyPrinting(boolean prettyPrinting) Says if JSON contents are to be pretty printed.
void	setProgress(AtomicInteger progress) Sets the sharable progress variable that will store Blob/Clob upload or download progress between 0 and 100.
void	setReadOnly(boolean readOnly) Puts this connection in read-only mode as a hint to the driver to enable database optimizations.
static void	setReadTimeout(int readTimeout) Sets the read timeout.
static void	setTraceOn(boolean traceOn) Sets the trace on/off
void	setTransactionIsolation(int level) Attempts to change the transaction isolation level for this Connection object to the one given.

Methods inherited from class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

abort, clearWarnings, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStruct, getCatalog, getClientInfo, getClientInfo, getMetaData, getNetworkTimeout, getSchema, getTypeMap, getWarnings, isValid, isWrapperFor, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, setCatalog, setClientInfo, setClientInfo, setNetworkTimeout, setSavepoint, setSavepoint, setSchema, setTypeMap, unwrap

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.sql.Connection

abort, clearWarnings, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStruct, getCatalog, getClientInfo, getClientInfo, getMetaData, getNetworkTimeout, getSchema, getTypeMap, getWarnings, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, setCatalog, setClientInfo, setClientInfo, setNetworkTimeout, setSavepoint, setSavepoint, setSchema, setTypeMap

Methods inherited from interface java.sql.Wrapper

isWrapperFor, unwrap

Constructor Detail

AceQLConnection

public AceQLConnection(String serverUrl,
               String database,
               String username,
               char[] password)
                throws SQLException

Login on the AceQL server and connect to a database

Parameters:

serverUrl - the URL of the AceQL server. Example: http://localhost:9090/aceql

database - the server database to connect to.

username - the login

password - the password

Throws:

SQLException - if any I/O error occurs

AceQLConnection

public AceQLConnection(String serverUrl,
               String database,
               String username,
               char[] password,
               Proxy proxy,
               PasswordAuthentication passwordAuthentication)
                throws SQLException

Login on the AceQL server and connect to a database

Parameters:

serverUrl - the URL of the AceQL server. Example: http://localhost:9090/aceql

database - the server database to connect to.

username - the login

password - the password

proxy - the proxy to use. null if none.

passwordAuthentication - the username and password holder to use for authenticated proxy. Null if no proxy or if proxy does not require authentication.

Throws:

SQLException - if any I/O error occurs

Method Detail

setConnectTimeout

public static void setConnectTimeout(int connectTimeout)

Sets the connect timeout.

Parameters:

connectTimeout - Sets a specified timeout value, in milliseconds, to be used when opening a communications link to the remote server. If the timeout expires before the connection can be established, a java.net.SocketTimeoutException is raised. A timeout of zero is interpreted as an infinite timeout. See URLConnection.setConnectTimeout(int)

setReadTimeout

public static void setReadTimeout(int readTimeout)

Sets the read timeout.

Parameters:

readTimeout - an int that specifies the read timeout value, in milliseconds, to be used when an http connection is established to the remote server. See URLConnection.setReadTimeout(int)

close

public void close()

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Releases this Connection object's database and JDBC resources immediately instead of waiting for them to be automatically released.

Calling the method close on a Connection object that is already closed is a no-op.

Note: A Connection object is automatically closed when it is garbage collected. Certain fatal errors also close a Connection object.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Connection

Overrides:

close in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

logout

public void logout()

commit

public void commit()
            throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Specified by:

commit in interface Connection

Overrides:

commit in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Throws:

SQLException - if a database access error occurs or this Connection object is in auto-commit mode

See Also:

AbstractConnection.setAutoCommit(boolean)

rollback

public void rollback()
              throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Specified by:

rollback in interface Connection

Overrides:

rollback in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Throws:

SQLException - if a database access error occurs or this Connection object is in auto-commit mode

See Also:

AbstractConnection.setAutoCommit(boolean)

setTransactionIsolation

public void setTransactionIsolation(int level)
                             throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Attempts to change the transaction isolation level for this Connection object to the one given. The constants defined in the interface Connection are the possible transaction isolation levels.

Note: If this method is called during a transaction, the result is implementation-defined.

Specified by:

setTransactionIsolation in interface Connection

Overrides:

setTransactionIsolation in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Parameters:

level - one of the following Connection constants: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or Connection.TRANSACTION_SERIALIZABLE. (Note that Connection.TRANSACTION_NONE cannot be used because it specifies that transactions are not supported.)

Throws:

SQLException - if a database access error occurs or the given parameter is not one of the Connection constants

See Also:

DatabaseMetaData.supportsTransactionIsolationLevel(int), AbstractConnection.getTransactionIsolation()

setHoldability

public void setHoldability(int holdability)
                    throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Changes the holdability of ResultSet objects created using this Connection object to the given holdability.

Specified by:

setHoldability in interface Connection

Overrides:

setHoldability in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Parameters:

holdability - a ResultSet holdability constant; one of ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT

Throws:

SQLException - if a database access occurs, the given parameter is not a ResultSet constant indicating holdability, or the given holdability is not supported

See Also:

AbstractConnection.getHoldability(), ResultSet

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Sets this connection's auto-commit mode to the given state. If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the method commit or the method rollback . By default, new connections are in auto-commit mode.

The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet object, the statement completes when the last row of the ResultSet object has been retrieved or the ResultSet object has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. In these cases, the commit occurs when all results and output parameter values have been retrieved.

NOTE: If this method is called during a transaction, the transaction is committed.

Specified by:

setAutoCommit in interface Connection

Overrides:

setAutoCommit in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Parameters:

autoCommit - true to enable auto-commit mode; false to disable it

Throws:

SQLException - if a database access error occurs

See Also:

AbstractConnection.getAutoCommit()

getAutoCommit

public boolean getAutoCommit()
                      throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Retrieves the current auto-commit mode for this Connection object.

Specified by:

getAutoCommit in interface Connection

Overrides:

getAutoCommit in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Returns:

the current state of this Connection object's auto-commit mode

Throws:

SQLException - if a database access error occurs

See Also:

AbstractConnection.setAutoCommit(boolean)

setReadOnly

public void setReadOnly(boolean readOnly)
                 throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Puts this connection in read-only mode as a hint to the driver to enable database optimizations.

Note: This method cannot be called during a transaction.

Specified by:

setReadOnly in interface Connection

Overrides:

setReadOnly in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Parameters:

readOnly - true enables read-only mode; false disables it

Throws:

SQLException - if a database access error occurs or this method is called during a transaction

isReadOnly

public boolean isReadOnly()
                   throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Retrieves whether this Connection object is in read-only mode.

Specified by:

isReadOnly in interface Connection

Overrides:

isReadOnly in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Returns:

true if this Connection object is read-only; false otherwise

Throws:

SQLException - if a database access error occurs

getHoldability

public int getHoldability()
                   throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Retrieves the current holdability of ResultSet objects created using this Connection object.

Specified by:

getHoldability in interface Connection

Overrides:

getHoldability in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Returns:

the holdability, one of ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT

Throws:

SQLException - if a database access occurs

See Also:

AbstractConnection.setHoldability(int), ResultSet

getTransactionIsolation

public int getTransactionIsolation()
                            throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Retrieves this Connection object's current transaction isolation level.

Specified by:

getTransactionIsolation in interface Connection

Overrides:

getTransactionIsolation in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Returns:

the current transaction isolation level, which will be one of the following constants: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE, or Connection.TRANSACTION_NONE.

Throws:

SQLException - if a database access error occurs

See Also:

AbstractConnection.setTransactionIsolation(int)

createStatement

public Statement createStatement()
                          throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Creates a Statement object for sending SQL statements to the database. SQL statements without parameters are normally executed using Statement objects. If the same SQL statement is executed many times, it may be more efficient to use a PreparedStatement object.

Result sets created using the returned Statement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY.

Specified by:

createStatement in interface Connection

Overrides:

createStatement in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Returns:

a new default Statement object

Throws:

SQLException - if a database access error occurs

prepareStatement

public PreparedStatement prepareStatement(String sql)
                                   throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Creates a PreparedStatement object for sending parameterized SQL statements to the database.

A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however, it does affect which methods throw certain SQLException objects.

Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY.

Specified by:

prepareStatement in interface Connection

Overrides:

prepareStatement in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Parameters:

sql - an SQL statement that may contain one or more '?' IN parameter placeholders

Returns:

a new default PreparedStatement object containing the pre-compiled SQL statement

Throws:

SQLException - if a database access error occurs

clone

public Connection clone()

Overrides:

clone in class Object

getClientVersion

public String getClientVersion()

Returns the SDK current Version.

Returns:

the SDK current Version

getServerVersion

public String getServerVersion()
                        throws AceQLException

Returns the server product version

Returns:

the server product version

Throws:

AceQLException - if any Exception occurs

isTraceOn

public static boolean isTraceOn()

Says if trace is on

Returns:

true if trace is on

setTraceOn

public static void setTraceOn(boolean traceOn)

Sets the trace on/off

Parameters:

traceOn - if true, trace will be on

setPrettyPrinting

public void setPrettyPrinting(boolean prettyPrinting)

Says if JSON contents are to be pretty printed. Defaults to false.

Parameters:

prettyPrinting - if true, JSON contents are to be pretty printed

setGzipResult

public void setGzipResult(boolean gzipResult)

Define if SQL result sets are returned compressed with the GZIP file format before download. Defaults to true.

Parameters:

gzipResult - if true, sets are compressed before download

getCancelled

public AtomicBoolean getCancelled()

Returns the cancelled value set by the progress indicator

Returns:

the cancelled value set by the progress indicator

setCancelled

public void setCancelled(AtomicBoolean cancelled)

Sets the sharable canceled variable that will be used by the progress indicator to notify this instance that the user has cancelled the current Blob/Clob upload or download.

Parameters:

cancelled - the Sharable canceled variable that will be used by the progress indicator to notify this instance that the end user has cancelled the current Blob/Clob upload or download

getProgress

public AtomicInteger getProgress()

Returns the sharable progress variable that will store Blob/Clob upload or download progress between 0 and 100

Returns:

the sharable progress variable that will store Blob/Clob upload or download progress between 0 and 100

setProgress

public void setProgress(AtomicInteger progress)

Sets the sharable progress variable that will store Blob/Clob upload or download progress between 0 and 100. Will be used by progress indicators to show the progress.

Parameters:

progress - the sharable progress variable

isClosed

public boolean isClosed()
                 throws SQLException

Description copied from class: org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Retrieves whether this Connection object has been closed. A connection is closed if the method close has been called on it or if certain fatal errors have occurred. This method is guaranteed to return true only when it is called after the method Connection.close has been called.

This method generally cannot be called to determine whether a connection to a database is valid or invalid. A typical client can determine that a connection is invalid by catching any exceptions that might be thrown when an operation is attempted.

Specified by:

isClosed in interface Connection

Overrides:

isClosed in class org.kawanfw.driver.jdbc.abstracts.AbstractConnection

Returns:

true if this Connection object is closed; false if it is still open

Throws:

SQLException - if a database access error occurs