com.northgateis.reality.realsql
Class RealSQLConnection

java.lang.Object
 |
 +--com.northgateis.reality.realsql.RealSQLConnection

public class RealSQLConnection

extends java.lang.Object

implements java.sql.Connection

The RealSQLConnection class is an implementation of the JDBC 2.0 Connection interface.

See Also:

Connection, DriverManager.getConnection(java.lang.String)

RealSQLConnection

public RealSQLConnection(java.lang.String url,
 java.lang.String host,
 int port,
 java.lang.String dbase,
 java.util.Properties info)
 throws java.sql.SQLException

Constructs a new connection object and attempts to establish a connection to the specified Reality database URL.

Parameters:

url - a database url of the form jdbc:realsql://host:port/database.

host - remote system name.

dbase - remote database name as defined in the ROUTE-FILE or equivalent.

info - a list of string tag/value pairs containg "user", "password", "account", "accountpwd", and "logging" properties.

clearWarnings

public void clearWarnings()
 throws java.sql.SQLException

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

Throws:

java.sql.SQLException - never thrown.

close

public void close()
 throws java.sql.SQLException

Close's the connection to the database and release's any JDBC resources immediately instead of waiting for them to be automatically released.

Specified by:

close in interface java.sql.Connection

Throws:

java.sql.SQLException - if a database access error occurs.

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.

createStatement

public java.sql.Statement createStatement()
 throws java.sql.SQLException

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 is more efficient to use a Prepared Statement.

Reality only supports ResultSets having a type of FORWARD_ONLY, and a concurrency of READ_ONLY.

Specified by:

createStatement in interface java.sql.Connection

Returns:

new Statement object

Throws:

java.sql.SQLException - if a database access error occurs.

createStatement

public java.sql.Statement createStatement(int type,
 int concur)
 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.

Reality only supports ResultSets having a type of FORWARD_ONLY, and a concurrency of READ_ONLY. Attempting to create a statement with any other type or concurrancy will throw an exception.

Specified by:

createStatement in interface java.sql.Connection

Parameters:

type - a result set type; see ResultSet.TYPE_XXX

concur - a concurrency type; see ResultSet.CONCUR_XXX

Returns:

new Statement object

Throws:

java.sql.SQLException - if a database access error occurs.

getAutoCommit

public boolean getAutoCommit()
 throws java.sql.SQLException

Get the current AutoCommit state.

Specified by:

getAutoCommit in interface java.sql.Connection

Returns:

true auto-commit enabled; false auto-commit disabled.

Throws:

java.sql.SQLException - if error detected.

getCatalog

public java.lang.String getCatalog()
 throws java.sql.SQLException

Returns the Connection's current catalog name.

Specified by:

getCatalog in interface java.sql.Connection

Returns:

the current catalog name or null.

Throws:

java.sql.SQLException - if error detected.

getMetaData

public java.sql.DatabaseMetaData getMetaData()
 throws java.sql.SQLException

Gets the metadata from this connection's Reality database. The database is able to provide information describing its tables, its supported SQL, grammar 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:

DatabaseMetaData object for this connection.

Throws:

java.sql.SQLException - if a database access error occurs.

getTransactionIsolation

public int getTransactionIsolation()
 throws java.sql.SQLException

Gets this Connection's current transaction isolation level.

Reality supports the following transaction isolation levels:

TRANSACTION_READ_UNCOMMITTED

TRANSACTION_READ_COMMITTED

TRANSACTION_REPEATABLE_READ

Specified by:

getTransactionIsolation in interface java.sql.Connection

Returns:

current transaction isolation mode value.

Throws:

java.sql.SQLException - if error detected.

getWarnings

public java.sql.SQLWarning getWarnings()
 throws java.sql.SQLException

Returns the first warning reported by calls on this Connection.

Specified by:

getWarnings in interface java.sql.Connection

Returns:

the first SQLWarning or null.

Throws:

java.sql.SQLException - never thrown.

isClosed

public boolean isClosed()

Tests to see if this connection is closed.

Specified by:

isClosed in interface java.sql.Connection

Returns:

true if the connection is closed; else false.

Throws:

none. -  

isReadOnly

public boolean isReadOnly()
 throws java.sql.SQLException

Tests to see if the connection is in READ_ONLY mode.

The driver always returns false.

Specified by:

isReadOnly in interface java.sql.Connection

Returns:

false

Throws:

java.sql.SQLException - if a database access error occurs.

nativeSQL

public java.lang.String nativeSQL(java.lang.String sql)
 throws java.sql.SQLException

Converts the given SQL statement into the system's native SQL grammar. A driver may 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.

The driver does not perform any conversions prior to passing it onto the Reality SQL Server.

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

Throws:

java.sql.SQLException - never thrown.

prepareCall

public java.sql.CallableStatement prepareCall(java.lang.String sql)
 throws java.sql.SQLException

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.

Stored Procedures in a Reality database are implemented using Databasic Subroutines. They are deemed to invoke an update query, although an update does not actually have to occur. Consequntly a ResultSet cannot be returned by executing a stored procedure on a Reality database.

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

Throws:

java.sql.SQLException -  

prepareCall

public java.sql.CallableStatement prepareCall(java.lang.String sql,
 int type,
 int concur)
 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.

Stored Procedures in a Reality database are implemented using Databasic Subroutines. They are deemed to invoke an update query, although an update does not actually have to occur. Consequntly a ResultSet cannot be returned by executing a stored procedure on a Reality database.

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:

SQLException. -  

getTypeMap

public java.util.Map getTypeMap()
 throws java.sql.SQLException

Not supported by the RealSQL-JDBC driver.

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.

Throws:

java.sql.SQLException - IM001 - "Driver does not support this function".

setTypeMap

public void setTypeMap(java.util.Map map)
 throws java.sql.SQLException

Not supported by the RealSQL-JDBC driver.

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

Throws:

java.sql.SQLException - IM001 - "Driver does not support this function".

prepareStatement

public java.sql.PreparedStatement prepareStatement(java.lang.String sql)
 throws java.sql.SQLException

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.

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.

Throws:

java.sql.SQLException -  

prepareStatement

public java.sql.PreparedStatement prepareStatement(java.lang.String sql,
 int type,
 int concur)
 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.

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 -  

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.

setAutoCommit

public void setAutoCommit(boolean b)
 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.

Reality does not support the returning of multiple ResultSets.

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.

setCatalog

public void setCatalog(java.lang.String name)
 throws java.sql.SQLException

Sets a catalog name in order to select a subspace of this Connection's database in which to work. The driver does not support catalogs, and silently ignores this request.

Specified by:

setCatalog in interface java.sql.Connection

Parameters:

catalogName - catalog name.

Throws:

java.sql.SQLException - never thrown.

setReadOnly

public void setReadOnly(boolean b)
 throws java.sql.SQLException

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

The driver does not support read-only connections.

Specified by:

setReadOnly in interface java.sql.Connection

Parameters:

b - true enables read-only mode; false disables read-only mode.

Throws:

java.sql.SQLException - J1017 - "Read-Only connections not supported."

setTransactionIsolation

public void setTransactionIsolation(int level)
 throws java.sql.SQLException

Attempts to change the transaction isolation level to the one given. The constants defined in the interface connection are the possible transaction isolation levels.

Reality supports the following transaction isolation levels:

TRANSACTION_READ_UNCOMMITTED

TRANSACTION_READ_COMMITTED

TRANSACTION_REPEATABLE_READ

Specified by:

setTransactionIsolation in interface java.sql.Connection

Parameters:

level - one of the supported transaction isolation values with the exception of TRANSACTION_NONE

Throws:

java.sql.SQLException - if a database access error occurs.

getServer

protected RealServer getServer()

Get the Server object associated with this connection.

Returns:

the server object

getServerVersion

protected int getServerVersion()

Get the server version number.

Returns:

server version number.

getUserName

protected java.lang.String getUserName()

getUrl

protected java.lang.String getUrl()