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)

Constructor Summary
RealSQLConnection(java.lang.String url, java.lang.String host, int port, java.lang.String dbase, java.util.Properties info)
          Constructs a new connection object and attempts to establish a connection to the specified Reality database URL.
 
Method Summary
 voidclearWarnings()
          Clears all warnings reported for this Connection object.
 voidclose()
          Close's the connection to the database and release's any JDBC resources immediately instead of waiting for them to be automatically released.
 voidcommit()
          Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the connection.
 java.sql.StatementcreateStatement()
          Creates a Statement object for sending SQL statements to the database.
 java.sql.StatementcreateStatement(int type, int concur)
          JDBC 2.0 Creates a Statement object that will generate ResultSet objects with the given type and concurrency.
 booleangetAutoCommit()
          Get the current AutoCommit state.
 java.lang.StringgetCatalog()
          Returns the Connection's current catalog name.
 java.sql.DatabaseMetaDatagetMetaData()
          Gets the metadata from this connection's Reality database.
protected  RealServergetServer()
          Get the Server object associated with this connection.
protected  intgetServerVersion()
          Get the server version number.
 intgetTransactionIsolation()
          Gets this Connection's current transaction isolation level.
 java.util.MapgetTypeMap()
          Not supported by the RealSQL-JDBC driver.
protected  java.lang.StringgetUrl()
           
protected  java.lang.StringgetUserName()
           
 java.sql.SQLWarninggetWarnings()
          Returns the first warning reported by calls on this Connection.
 booleanisClosed()
          Tests to see if this connection is closed.
 booleanisReadOnly()
          Tests to see if the connection is in READ_ONLY mode.
 java.lang.StringnativeSQL(java.lang.String sql)
          Converts the given SQL statement into the system's native SQL grammar.
 java.sql.CallableStatementprepareCall(java.lang.String sql)
          Creates a CallableStatement object for calling database stored procedures.
 java.sql.CallableStatementprepareCall(java.lang.String sql, int type, int concur)
          JDBC 2.0 Creates a CallableStatement object that will generate ResultSet objects with the given type and concurrency.
 java.sql.PreparedStatementprepareStatement(java.lang.String sql)
          Creates a PreparedStatement object for sending parameterized SQL statements to the database.
 java.sql.PreparedStatementprepareStatement(java.lang.String sql, int type, int concur)
          JDBC 2.0 Creates a PreparedStatement object that will generate ResultSet objects with the given type and concurrency.
 voidrollback()
          Drops all changes made since the previous commit/rollback and releases any database locks currently held by this Connection.
 voidsetAutoCommit(boolean b)
          Sets this connection's auto-commit mode.
 voidsetCatalog(java.lang.String name)
          Sets a catalog name in order to select a subspace of this Connection's database in which to work.
 voidsetReadOnly(boolean b)
          Puts this connection in read-only mode as a hint to enable database optimizations.
 voidsetTransactionIsolation(int level)
          Attempts to change the transaction isolation level to the one given.
 voidsetTypeMap(java.util.Map map)
          Not supported by the RealSQL-JDBC driver.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

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.

Method Detail

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