org.hsqldb
Class jdbcConnection

java.lang.Object
  |
  +--org.hsqldb.jdbcConnection

public class jdbcConnection
extends java.lang.Object
implements java.sql.Connection

A connection (session) with a specific database. Within the context of a Connection, SQL statements are executed and results are returned.

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, and so on. This information is obtained with the getMetaData method.

Note: By default the Connection automatically commits changes after executing each statement. If auto commit has been disabled, an explicit commit must be done or database changes will not be saved.

To connect to a HSQL database, the following code may be used:

 Class.forName("org.hsqldb.jdbcDriver");
 Connection c=DriverManager.getConnection(url,user,password);
 
For HSQL, the url must start with jdbc:hsqldb. The url for an In-Memory database is jdbc:hsqldb:. The url for a standalone database is jdbc:hsqldb:name where name is the filename of the database, including path. For example: jdbc:hsqldb:test will connect to a database called 'test', with the files test.properties, test.data and test.script. For more information about the internal file structure of HSQL, please read the documentation, page 'Files'.

See Also:
jdbcStatement, jdbcResultSet, jdbcDatabaseMetaData

Field Summary
static int DEFAULT_HSQL_PORT
           
(package private)  java.io.DataInputStream dInput
           
(package private)  java.io.DataOutputStream dOutput
           
(package private) static java.lang.String ENCODING
           
(package private)  java.net.Socket sSocket
           
 
Fields inherited from interface java.sql.Connection
TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE
 
Constructor Summary
(package private) jdbcConnection(Channel c)
          Constructor declaration
(package private) jdbcConnection(java.lang.String s, java.lang.String user, java.lang.String password)
          Constructor declaration
 
Method Summary
 void clearWarnings()
          Clears all warnings reported for this Connection object.
 void close()
          Releases a Connection'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 the Connection.
 java.sql.Statement createStatement()
          Creates a Statement object for sending SQL statements to the database.
 java.sql.Statement createStatement(int type, int concurrency)
          JDBC 2.0 Creates a Statement object that will generate ResultSet objects with the given type and concurrency.
(package private)  jdbcResultSet execute(java.lang.String s)
          Method declaration
 void finalize()
          Method declaration
 boolean getAutoCommit()
          Gets the current auto-commit state.
 java.lang.String getCatalog()
          Returns the Connection's current catalog name.
 java.sql.DatabaseMetaData getMetaData()
          Gets the metadata regarding this connection's database.
(package private)  java.lang.String getName()
          Method declaration
 int getTransactionIsolation()
          Gets this Connection's current transaction isolation level.
 java.util.Map getTypeMap()
          JDBC 2.0 Gets the type map object associated with this connection.
 java.sql.SQLWarning getWarnings()
          Returns the first warning reported by calls on this Connection.
 boolean isClosed()
          Tests to see if a Connection is closed.
 boolean isReadOnly()
          Tests to see if the connection is in read-only mode.
 java.lang.String nativeSQL(java.lang.String sql)
          Converts the given SQL statement into the system's native SQL grammar.
 java.sql.CallableStatement prepareCall(java.lang.String sql)
          Creates a CallableStatement object for calling database stored procedures.
 java.sql.CallableStatement prepareCall(java.lang.String sql, int resultSetType, int resultSetConcurrency)
          JDBC 2.0 Creates a CallableStatement object that will generate ResultSet objects with the given type and concurrency.
 java.sql.PreparedStatement prepareStatement(java.lang.String sql)
          Creates a PreparedStatement object for sending parameterized SQL statements to the database.
 java.sql.PreparedStatement prepareStatement(java.lang.String sql, int type, int concurrency)
          JDBC 2.0 Creates a PreparedStatement object that will generate ResultSet objects with the given type and concurrency.
 void rollback()
          Drops all changes made since the previous commit/rollback and releases any database locks currently held by this Connection.
 void setAutoCommit(boolean autoCommit)
          Sets this connection's auto-commit mode.
 void setCatalog(java.lang.String catalog)
          Sets a catalog name in order to select a subspace of this Connection's database in which to work.
 void setReadOnly(boolean readonly)
          Puts this connection in read-only mode as a hint to enable database optimizations.
 void setTransactionIsolation(int level)
          Attempts to change the transaction isolation level to the one given.
 void setTypeMap(java.util.Map map)
          JDBC 2.0 Installs the given type map as the type map for this connection.
(package private)  boolean usesLocalFiles()
          Method declaration
 
Methods inherited from class java.lang.Object
, clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

sSocket

java.net.Socket sSocket

dOutput

java.io.DataOutputStream dOutput

dInput

java.io.DataInputStream dInput

DEFAULT_HSQL_PORT

public static final int DEFAULT_HSQL_PORT

ENCODING

static final java.lang.String ENCODING
Constructor Detail

jdbcConnection

jdbcConnection(java.lang.String s,
               java.lang.String user,
               java.lang.String password)
         throws java.sql.SQLException
Constructor declaration
Parameters:
s -  
user -  
password -  

jdbcConnection

jdbcConnection(Channel c)
         throws java.sql.SQLException
Constructor declaration
Parameters:
c -  
Method Detail

createStatement

public java.sql.Statement createStatement()
Creates a Statement object for sending SQL statements to the database. SQL statements without parameters are normally executed using Statement objects.
Specified by:
createStatement in interface java.sql.Connection
Returns:
a new Statement object

prepareStatement

public java.sql.PreparedStatement prepareStatement(java.lang.String sql)
Creates a PreparedStatement object for sending parameterized SQL statements to the database. A SQL statement with or without IN parameters can be stored in a PreparedStatement object. This object can then be used to execute this statement multiple times.

In HSQL, the statement is not sent to the database until the PreparedStatement is executed. Other drivers may send the statment to the database when this function is called. This has no direct effect on users; however, it does affect which method throws certain SQLExceptions.

Specified by:
prepareStatement in interface java.sql.Connection
Parameters:
sql - a SQL statement that may contain one or more '?' IN parameter placeholders
Returns:
a new PreparedStatement object containing the pre-compiled statement

prepareCall

public java.sql.CallableStatement prepareCall(java.lang.String sql)
Creates a CallableStatement object for calling database stored procedures. The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing the call to a stored procedure.

Note: This method is optimized for handling stored procedure call statements.

HSQL does not send the call statement to the database when the method prepareCall is done; it waits until the CallableStatement is executed. This has no direct effect on users; however, it does affect which method throws certain SQLExceptions.

Specified by:
prepareCall in interface java.sql.Connection
Parameters:
sql - a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.
Returns:
a new CallableStatement object containing the pre-compiled SQL statement

nativeSQL

public java.lang.String nativeSQL(java.lang.String sql)
Converts the given SQL statement into the system's native SQL grammar.

HSQL does convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; this method returns the native form of the statement that the driver would have sent.

Specified by:
nativeSQL in interface java.sql.Connection
Parameters:
sql - a SQL statement that may contain one or more '?' parameter placeholders
Returns:
the native form of this statement

setAutoCommit

public void setAutoCommit(boolean autoCommit)
                   throws java.sql.SQLException
Sets this connection's auto-commit mode. 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, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet 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.
Specified by:
setAutoCommit in interface java.sql.Connection
Parameters:
autoCommit - true enables auto-commit; false disables auto-commit.
Throws:
java.sql.SQLException - if a database access error occurs

getAutoCommit

public boolean getAutoCommit()
Gets the current auto-commit state.
Specified by:
getAutoCommit in interface java.sql.Connection
Returns:
the current state of auto-commit mode
See Also:
setAutoCommit(boolean)

commit

public void commit()
            throws java.sql.SQLException
Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should be used only when auto-commit mode has been disabled.
Specified by:
commit in interface java.sql.Connection
Throws:
java.sql.SQLException - if a database access error occurs
See Also:
setAutoCommit(boolean)

rollback

public void rollback()
              throws java.sql.SQLException
Drops all changes made since the previous commit/rollback and releases any database locks currently held by this Connection. This method should be used only when auto- commit has been disabled.
Specified by:
rollback in interface java.sql.Connection
Throws:
java.sql.SQLException - if a database access error occurs
See Also:
setAutoCommit(boolean)

close

public void close()
           throws java.sql.SQLException
Releases a Connection's database and JDBC resources immediately instead of waiting for them to be automatically released.

Note: A Connection is automatically closed when it is garbage collected.

Specified by:
close in interface java.sql.Connection
Throws:
java.sql.SQLException - if a database access error occurs

isClosed

public boolean isClosed()
Tests to see if a Connection is closed.
Specified by:
isClosed in interface java.sql.Connection
Returns:
true if the connection is closed; false if it's still open

getMetaData

public java.sql.DatabaseMetaData getMetaData()
Gets the metadata regarding this connection's database. A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, and so on. This information is made available through a DatabaseMetaData object.
Specified by:
getMetaData in interface java.sql.Connection
Returns:
a DatabaseMetaData object for this Connection

setReadOnly

public void setReadOnly(boolean readonly)
                 throws java.sql.SQLException
Puts this connection in read-only mode as a hint to enable database optimizations.

Note: This method should not be called while in the middle of a transaction.

HSQL will in this case commit the transaction automatically.

In HSQL, additionally the whole database can be put in read-only mode by manually adding the line 'readonly=true' to the .properties file. All connections are then automatically readonly. The database files will then be opened in readonly mode, and it is thus possible to create a CD with this database.

Specified by:
setReadOnly in interface java.sql.Connection
Parameters:
readOnly - true enables read-only mode; false disables read-only mode.
Throws:
java.sql.SQLException - if a database access error occurs

isReadOnly

public boolean isReadOnly()
                   throws java.sql.SQLException
Tests to see if the connection is in read-only mode.
Specified by:
isReadOnly in interface java.sql.Connection
Returns:
true if connection is read-only and false otherwise
Throws:
java.sql.SQLException - if a database access error occurs

setCatalog

public void setCatalog(java.lang.String catalog)
Sets a catalog name in order to select a subspace of this Connection's database in which to work.

HSQL does not support catalogs and ignores this request.

Specified by:
setCatalog in interface java.sql.Connection

getCatalog

public java.lang.String getCatalog()
Returns the Connection's current catalog name.
Specified by:
getCatalog in interface java.sql.Connection
Returns:
the current catalog name or null

setTransactionIsolation

public void setTransactionIsolation(int level)
Attempts to change the transaction isolation level to the one given. The constants defined in the interface Connection are the possible transaction isolation levels.

Note: This method should not be called while in the middle of a transaction.

HSQL currently ignores this call.

Specified by:
setTransactionIsolation in interface java.sql.Connection
Parameters:
level - one of the TRANSACTION_* isolation values with the exception of TRANSACTION_NONE; some databases may not support other values
See Also:
DatabaseMetaData.supportsTransactionIsolationLevel(int)

getTransactionIsolation

public int getTransactionIsolation()
Gets this Connection's current transaction isolation level.
Specified by:
getTransactionIsolation in interface java.sql.Connection
Returns:
the current TRANSACTION_* mode value

getWarnings

public java.sql.SQLWarning getWarnings()
Returns the first warning reported by calls on this Connection.

HSQL never produces warnings and returns always null.

Specified by:
getWarnings in interface java.sql.Connection
Returns:
the first SQLWarning or null

clearWarnings

public void clearWarnings()
Clears all warnings reported for this Connection object. After a call to this method, the method getWarnings returns null until a new warning is reported for this Connection.
Specified by:
clearWarnings in interface java.sql.Connection

createStatement

public java.sql.Statement createStatement(int type,
                                          int concurrency)
                                   throws java.sql.SQLException
JDBC 2.0 Creates a Statement object that will generate ResultSet objects with the given type and concurrency. This method is the same as the createStatement method above, but it allows the default result set type and result set concurrency type to be overridden.

HSQL currently supports type TYPE_FORWARD_ONLY and concurrency CONCUR_READ_ONLY.

Specified by:
createStatement in interface java.sql.Connection
Parameters:
resultSetType - a result set type; see ResultSet.TYPE_XXX
resultSetConcurrency - a concurrency type; see ResultSet.CONCUR_XXX
Returns:
a new Statement object
Throws:
java.sql.SQLException - if a database access error occurs

prepareStatement

public java.sql.PreparedStatement prepareStatement(java.lang.String sql,
                                                   int type,
                                                   int concurrency)
                                            throws java.sql.SQLException
JDBC 2.0 Creates a PreparedStatement object that will generate ResultSet objects with the given type and concurrency. This method is the same as the prepareStatement method above, but it allows the default result set type and result set concurrency type to be overridden.

HSQL currently supports type TYPE_FORWARD_ONLY and concurrency CONCUR_READ_ONLY.

Specified by:
prepareStatement in interface java.sql.Connection
Parameters:
resultSetType - a result set type; see ResultSet.TYPE_XXX
resultSetConcurrency - a concurrency type; see ResultSet.CONCUR_XXX
Returns:
a new PreparedStatement object containing the pre-compiled SQL statement
Throws:
java.sql.SQLException - if a database access error occurs

prepareCall

public java.sql.CallableStatement prepareCall(java.lang.String sql,
                                              int resultSetType,
                                              int resultSetConcurrency)
                                       throws java.sql.SQLException
JDBC 2.0 Creates a CallableStatement object that will generate ResultSet objects with the given type and concurrency. This method is the same as the prepareCall method above, but it allows the default result set type and result set concurrency type to be overridden.

HSQL currently supports type TYPE_FORWARD_ONLY and concurrency CONCUR_READ_ONLY.

Specified by:
prepareCall in interface java.sql.Connection
Parameters:
resultSetType - a result set type; see ResultSet.TYPE_XXX
resultSetConcurrency - a concurrency type; see ResultSet.CONCUR_XXX
Returns:
a new CallableStatement object containing the pre-compiled SQL statement
Throws:
java.sql.SQLException - if a database access error occurs

getTypeMap

public java.util.Map getTypeMap()
                         throws java.sql.SQLException
JDBC 2.0 Gets the type map object associated with this connection. Unless the application has added an entry to the type map, the map returned will be empty.
Specified by:
getTypeMap in interface java.sql.Connection
Returns:
the java.util.Map object associated with this Connection object

setTypeMap

public void setTypeMap(java.util.Map map)
                throws java.sql.SQLException
JDBC 2.0 Installs the given type map as the type map for this connection. The type map will be used for the custom mapping of SQL structured types and distinct types.
Specified by:
setTypeMap in interface java.sql.Connection
Parameters:
the - java.util.Map object to install as the replacement for this Connection object's default type map

execute

jdbcResultSet execute(java.lang.String s)
                throws java.sql.SQLException
Method declaration
Parameters:
s -  
Returns:
 
Throws:
java.sql.SQLException -  

usesLocalFiles

boolean usesLocalFiles()
Method declaration
Returns:
 

getName

java.lang.String getName()
Method declaration
Returns:
 

finalize

public void finalize()
Method declaration
Overrides:
finalize in class java.lang.Object