com.mimer.jdbc
Class Connection

java.lang.Object
  |
  +--com.mimer.jdbc.Connection

All Implemented Interfaces:

Cloneable, Connection

public final class Connection

extends Object

implements Connection, Cloneable

Connection represents a JDBC connection to a Mimer database server.

Field Summary

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Method Summary

void	clearWarnings() Clears all warnings reported on the object.
void	close() Closes the connection.
void	commit() Commits a transaction.
Statement	createStatement() Creates a new Statement object.
Statement	createStatement(int resultSetType, int resultSetConcurrency) Creates a new Statement object with specified scrollability and read/write mode.
boolean	getAutoCommit() Checks if auto commit is enabled or not.
String	getCatalog() Returns the current catalog of the connection.
DatabaseMetaData	getMetaData() Returns a DatabaseMetaData object for this connection.
Statistics	getStatistics() Return the Mimer connection statistics object.
int	getTransactionIsolation() Returns the current transaction isolation.
Map	getTypeMap() Returns the current type map associated with the current statement.
SQLWarning	getWarnings() Returns the first warning posted to this object.
boolean	isClosed() Returns true if the connection is closed.
boolean	isReadOnly() Returns transaction readonly/readwrite status.
String	nativeSQL(String sql) Converts any escape clauses in the statement.
CallableStatement	prepareCall(String sql) Prepares a SQL statement with output parameters and creates a new CallableStatement object.
CallableStatement	prepareCall(String sql, int resultSetType, int resultSetConcurrency) Prepares a SQL statement with output parameters and creates a new CallableStatement object.
PreparedStatement	prepareStatement(String sql) Prepares a SQL statement with input parameters and creates a new PreparedStatement object.
PreparedStatement	prepareStatement(String sql, int resultSetType, int resultSetConcurrency) Prepares a SQL statement with input parameters and creates a new PreparedStatement object.
void	rollback() Rollbacks all changes made in the current transaction.
void	setAutoCommit(boolean autoCommit) Sets the commit mode of the connection.
void	setCatalog(String catalog) Changes the current catalog of the connection.
void	setReadOnly(boolean readOnly) Alters the readonly state of transactions on this connection.
void	setTransactionIsolation(int level) Alters the isolation of transactions on this connection.
void	setTypeMap(Map map) Sets the current type map associated with the current statement.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.sql.Connection

createStatement, getHoldability, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, setHoldability, setSavepoint, setSavepoint

Method Detail

clearWarnings

public void clearWarnings()
                   throws SQLException

Clears all warnings reported on the object.

Specified by:

clearWarnings in interface Connection

Throws:

SQLException - if an error occurs.

close

public void close()
           throws SQLException

Closes the connection.

Specified by:

close in interface Connection

Throws:

SQLException - if a database error occurs. If an error occurs here, it is most probably because some kind of server-client-communication error occurred.

commit

public void commit()
            throws SQLException

Commits a transaction. When this method is called, the server will validate all changes applied during the transaction to see if any transaction conflicts occurred. In practice, this validation compares the contents of the Read Set (which contains all data the transaction has seen) with the corresponding table contents. If any of these comparisons fail, the commit fails since the facts the transaction was based on has changed.

Due to this feature of the optimistic concurrency control that Mimer employs, this is the only time when a transaction may fail. In a locking environment transactions may fail at any time because of deadlocks or simply because they timed out. A Mimer transaction never encounters a deadlock, nor will it ever time out.

If applications are expected to be portable, you should however make sure appropriate transaction error handling is covered everywhere.

Also see article on Optimistic Concurrency Control

Specified by:

commit in interface Connection

Throws:

SQLException - if a database error occurred. This could be because of two main reasons. Either a client-server-communication error occurred, or the server was unable to commit because of a transaction conflict. The latter will throw an SQLSTATE 40001.

See Also:

setAutoCommit(boolean), getAutoCommit(), rollback()

createStatement

public Statement createStatement()
                          throws SQLException

Creates a new Statement object.

Specified by:

createStatement in interface Connection

Returns:

The new Statement object.

Throws:

SQLException - if an error occurs. The only runtime error likely to occur is that the JVM was unable to instantiate the new object. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

prepareCall(java.lang.String), prepareStatement(java.lang.String)

createStatement

public Statement createStatement(int resultSetType,
                                 int resultSetConcurrency)
                          throws SQLException

Creates a new Statement object with specified scrollability and read/write mode.

Performance consideration: Scrollable result sets are different from forward only result sets in that all rows once visited in the result remains stored in a temporary table on the server. A large scrollable result set may therefore consume a lot of memory on the server. The buildup of the temporary table mentioned will alone make a forward only result set faster than a scrollable result set.

Specified by:

createStatement in interface Connection

Parameters:

resultSetType - Either ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE or ResultSet.TYPE_SCROLL_INSENSITIVE. Mimer SQL supports only stable cursors, so ResultSet.TYPE_SCROLL_SENSITIVE will default back to ResultSet.TYPE_SCROLL_INSENSITIVE.

resultSetConcurrency - Either ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE. Mimer SQL supports only updatable resultsets through the "UPDATE/DELETE WHERE CURRENT OF" SQL-statements.

Returns:

The new Statement object.

Throws:

SQLException - if an error occurs. The only runtime error likely to occur is that the JVM was unable to instantiate the new object. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

prepareCall(java.lang.String), prepareStatement(java.lang.String)

getAutoCommit

public boolean getAutoCommit()
                      throws SQLException

Checks if auto commit is enabled or not.

Specified by:

getAutoCommit in interface Connection

Returns:

true if auto commit mode is enabled, otherwise false.

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

setAutoCommit(boolean)

getCatalog

public String getCatalog()
                  throws SQLException

Returns the current catalog of the connection. Mimer SQL does not support the notion of catalogs. Therefore this method will always return null.

Specified by:

getCatalog in interface Connection

Returns:

The current catalog as a string. Mimer always returns null.

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

setCatalog(java.lang.String)

getMetaData

public DatabaseMetaData getMetaData()
                             throws SQLException

Returns a DatabaseMetaData object for this connection.

Specified by:

getMetaData in interface Connection

Returns:

The DatabaseMetaData object.

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

getStatistics

public Statistics getStatistics()

Return the Mimer connection statistics object. (Used by jtrace.)

Returns:

The connection statistics object

getTransactionIsolation

public int getTransactionIsolation()
                            throws SQLException

Returns the current transaction isolation.

Specified by:

getTransactionIsolation in interface Connection

Returns:

The current transaction isolation.

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

setTransactionIsolation(int)

getTypeMap

public Map getTypeMap()
               throws SQLException

Returns the current type map associated with the current statement.

Mimer JDBC does not currently support type maps. Whatever the current type map is, it is ignored during execution.

Specified by:

getTypeMap in interface Connection

Returns:

The current type map.

Throws:

SQLException - if an error occurs.

See Also:

setTypeMap(java.util.Map)

getWarnings

public SQLWarning getWarnings()
                       throws SQLException

Returns the first warning posted to this object.

Specified by:

getWarnings in interface Connection

Returns:

The first warning object or null if no warnings available.

Throws:

SQLException - if an error occurred.

See Also:

clearWarnings()

isClosed

public boolean isClosed()
                 throws SQLException

Returns true if the connection is closed.

This routine this not test the connection. This will only return true if closed() has been called. Any connection problems will go unnoticed.

Specified by:

isClosed in interface Connection

Returns:

true if connection is closed.

Throws:

SQLException - if an error occurred.

isReadOnly

public boolean isReadOnly()
                   throws SQLException

Returns transaction readonly/readwrite status.

Specified by:

isReadOnly in interface Connection

Returns:

true if transaction is read only, false if it is read write

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

setReadOnly(boolean)

nativeSQL

public String nativeSQL(String sql)
                 throws SQLException

Converts any escape clauses in the statement.

Performance consideration: This call invokes the server preprocessor to expand the escape clauses. Escape clauses are expanded whenever statements are prepared, so this method is not needed for anything else than seeing what escape clauses actaully is expanded to on a Mimer SQL server.

Specified by:

nativeSQL in interface Connection

Parameters:

sql - SQL statement.

Returns:

The input SQL statement with escape clauses expanded.

Throws:

SQLException - if an error occurs. This request invokes the server and may therefore return many kind of errors. If the connection is not open SQLSTATE 08003 will be thrown.

prepareCall

public CallableStatement prepareCall(String sql)
                              throws SQLException

Prepares a SQL statement with output parameters and creates a new CallableStatement object.

Although CallableStatements first come to mind when talking about procedure calls, any SQL statement that features output parameters must use a CallableStatement object.

Specified by:

prepareCall in interface Connection

Parameters:

sql - The SQL statement with the output parameters.

Returns:

The new CallableStatement object.

Throws:

SQLException - if an error occurs. A compilation error will throw SQLSTATE 42000. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

createStatement(), prepareStatement(java.lang.String)

prepareCall

public CallableStatement prepareCall(String sql,
                                     int resultSetType,
                                     int resultSetConcurrency)
                              throws SQLException

Prepares a SQL statement with output parameters and creates a new CallableStatement object.

Although CallableStatements first come to mind when talking about procedure calls, any SQL statement that features output parameters must use a CallableStatement object.

Performance consideration: Scrollable result sets are different from forward only result sets in that all rows once visited in the result remains stored in a temporary table on the server. A large scrollable result set may therefore consume a lot of memory on the server. The buildup of the temporary table mentioned will alone make a forward only result set faster than a scrollable result set.

Specified by:

prepareCall in interface Connection

Parameters:

sql - The SQL statement with the output parameters.

resultSetType - Either ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE or ResultSet.TYPE_SCROLL_INSENSITIVE. Mimer SQL supports only stable cursors, so ResultSet.TYPE_SCROLL_SENSITIVE will default back to ResultSet.TYPE_SCROLL_INSENSITIVE.

resultSetConcurrency - Either ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE. Mimer SQL supports only updatable resultsets through the "UPDATE/DELETE WHERE CURRENT OF" SQL-statements.

Returns:

The new CallableStatement object.

Throws:

SQLException - if an error occurs. A compilation error will throw SQLSTATE 42000. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

createStatement(), prepareStatement(java.lang.String)

prepareStatement

public PreparedStatement prepareStatement(String sql)
                                   throws SQLException

Prepares a SQL statement with input parameters and creates a new PreparedStatement object.

Specified by:

prepareStatement in interface Connection

Parameters:

sql - The SQL statement with the input parameters.

Returns:

The new PreparedStatement object.

Throws:

SQLException - if an error occurs. A compilation error will throw SQLSTATE 42000. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

createStatement(), prepareCall(java.lang.String)

prepareStatement

public PreparedStatement prepareStatement(String sql,
                                          int resultSetType,
                                          int resultSetConcurrency)
                                   throws SQLException

Prepares a SQL statement with input parameters and creates a new PreparedStatement object.

Performance consideration: Scrollable result sets are different from forward only result sets in that all rows once visited in the result remains stored in a temporary table on the server. A large scrollable result set may therefore consume a lot of memory on the server. The buildup of the temporary table mentioned will alone make a forward only result set faster than a scrollable result set.

Specified by:

prepareStatement in interface Connection

Parameters:

sql - The SQL statement with the input parameters.

resultSetType - Either ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE or ResultSet.TYPE_SCROLL_INSENSITIVE. Mimer SQL supports only stable cursors, so ResultSet.TYPE_SCROLL_SENSITIVE will default back to ResultSet.TYPE_SCROLL_INSENSITIVE.

resultSetConcurrency - Either ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE. Mimer SQL supports only updatable resultsets through the "UPDATE/DELETE WHERE CURRENT OF" SQL-statements.

Returns:

The new PreparedStatement object.

Throws:

SQLException - if an error occurs. A compilation error will throw SQLSTATE 42000. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

createStatement(), prepareCall(java.lang.String)

rollback

public void rollback()
              throws SQLException

Rollbacks all changes made in the current transaction.

Since Mimer SQL stores uncommitted changes in a write set, which is logged and eventually written to database tables upon commit, a rollback will only throw away the current write set.

Specified by:

rollback in interface Connection

Throws:

SQLException - if a database error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws SQLException

Sets the commit mode of the connection.

If autocommit is enabled, every statement will run in a statement of its own. If autocommit is disabled (that is manual commit mode) the JDBC programmer has to explicitly tell the server to commit by calling the commit method.

Performance considerations: When the transaction is executing in autocommit mode, any changes made by a statement is independently secured on disk. This is in contrast to manual commit mode, where the server is not securing changes until the client explicitly says so by committing the transaction.

Therefore, server throughput during UPDATE/INSERT/DELETE operations benefits greatly from manual commit mode, where it is applicable.

A drawback of manual commit mode is that it requires an extra round-trip to the server at commit. The server knows in advance that a connection is in autocommit mode and can therefore commit at will.

When autocommit is turned on, the current transaction is committed.

Specified by:

setAutoCommit in interface Connection

Parameters:

autoCommit - true for autocommit mode, false for manual commit mode

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown. If the commit failed, SQLSTATE 40001 is thrown.

See Also:

commit()

setCatalog

public void setCatalog(String catalog)
                throws SQLException

Changes the current catalog of the connection.

Mimer SQL does not support the notion of catalogs, so setting this has no effect.

Specified by:

setCatalog in interface Connection

Parameters:

catalog - The new catalog of the connection.

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

getCatalog()

setReadOnly

public void setReadOnly(boolean readOnly)
                 throws SQLException

Alters the readonly state of transactions on this connection. It is affecting the next transaction to start.

Performance consideration: A transaction running in read only mode will execute slightly faster because the server knows in advance that no database changes will be be made during the transaction.

Changing this attribute affects the next transaction on this connection.

Specified by:

setReadOnly in interface Connection

Parameters:

readOnly - true for read only mode.

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

isReadOnly()

setTransactionIsolation

public void setTransactionIsolation(int level)
                             throws SQLException

Alters the isolation of transactions on this connection. The change is affecting the next transaction.

The transaction isolation level determines to what extent the transaction is seeing changes made by other transactions. As of Mimer SQL 9.1, only the two highest levels of isolation levels are supported (TRANSACTION_SERIALIZABLE and TRANSACTION_REPEATABLE_READ, the latter being the default).

Specified by:

setTransactionIsolation in interface Connection

Parameters:

level - The selected transaction isolation.

Throws:

SQLException - if an error occurred. If the connection is not open SQLSTATE 08003 will be thrown.

See Also:

getTransactionIsolation()

setTypeMap

public void setTypeMap(Map map)
                throws SQLException

Sets the current type map associated with the current statement.

Mimer JDBC does not currently support type maps. Whatever the current type map is, it is ignored during execution.

Specified by:

setTypeMap in interface Connection

Throws:

SQLException - if an error occurs.

See Also:

getTypeMap()