Mimer JDBC Engine 2.12

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

Mimer JDBC Engine 2.12

Submit a comment or suggestion Version 2.12 of Mimer JDBC Engine
Copyright Upright Database Technology AB, Box 1713, SE-751 47 UPPSALA, Sweden. All Rights Reserved.