public interface DatabaseConnection extends Connection
Title: Open Service Framework
Description: Base interface for reliable JDBC connection. This interface provides an
implementation outline for all database connections that are created by the
JDBCFactory
implementations. There is a strict hirarchy of ownership
that allows the creation of connection factories and subsequently all
connections only thru the management framework interface.
The JDBC database connection interface is a wrapper around a standard JDBC-compliant connection. It provides some additional functionality not found in regular connections and facilitates a reliable communication channel into a given server. Reliable implies that the connection mechanism has some logic built into it that tracks connection state and critical events, allowing developers to subscribe to such events in order to react to connection state changes when, for example, the back-end database system has been shut down or made unavailable. If a network or other communications error has prevented access to the data store the connection may (dependent on settings) automatically timeout, re-connect, abort the connection or block upstream queries from executing until the connection is re-established. Alternatively the connection may be set up to roll over to an alternate URL. While this does not facilitate a Fault Tolerant behavior at the transaction level, it does provide a level of reliability that is ideal for environments that experience sparse connection outages or require automated fail-over to Disaster Recovery sites or alternate backup databases.
The wrapper occasionally overrides the system SQLException
and makes use of standard
XOPEN SQLstate
codes when presenting SQL processing errors. Such errors are considered local in scope
from the perspective of the Service Event Fabric. However in some cases exception events may be raised as
DatabaseSQLException
objects and users may subscribe to such events thru the usage of an exception listener.
The table below provides XOPEN SQLstate
codes.
SQL State Error Codes
SQL State (SQLSTATE) Error Codes are defined by the ISO/ANSI and Open Group (X/Open) SQL Standards. Such an error code is a 5-character string consisting of a 2-character class value followed by a 3-character subclass value. A class value of "00" indicates success, a class value of "01" indicates a warning, and other class values normally indicate an exception. However, there are some special class values (e.g. "IM") that can indicate both warnings and errors. A subclass value of "000" in any class indicates that there is no subclass for that SQL state.
The following table defines the SQLSTATE error codes that may be used by the connection wrapper or the underlying connection driver and may also be returned by the SQL Access framework. A complete list of the SQLSTATE error codes can be found in the documentations of the ISO/ANSI and Open Group (X/Open) SQL Standards.
Copyright: Copyright (c) 2009
Company: StreamScape Technologies
TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE
Modifier and Type | Method and Description |
---|---|
void |
connect()
Connect to the database.
|
void |
disconnect()
Disconnects from the database.
|
void |
forceStateCheck()
Forces connection to check it's current state, e.g.
|
ExceptionEventListener |
getExceptionEventListener()
Returns the exception advisory listener for this connection.
|
java.lang.String |
getName()
Returns the name of this connection.
|
Connection |
getRawConnection()
Returns underlying connection.
|
static Connection |
getRawConnection(Connection connection) |
Logger |
getServiceLogger()
Returns the logger for this connection.
|
ConnectionState |
getState()
Returns the state of this connection.
|
StateNotificationEventListener |
getStateNotificationEventListener()
Returns the state notification advisory listener for this connection.
|
boolean |
isActive()
Returns
true is the current connection is active and connected. |
boolean |
isPrimary()
Check if this connection is a primary in a connection group.
|
void |
raiseException(DatabaseSQLException e)
Raises a user-defined exception for this connection.
|
void |
resume()
Resume a connection.
|
void |
setExceptionEventListener(ExceptionEventListener listener)
Sets the exception (advisory) event listener for this connection.
|
void |
setPrimary(boolean primary)
Sets the connection in a group to be the primary.
|
void |
setServiceLogger(Logger logger)
Sets the logger for this connection's critical log events.
|
void |
setStateNotificationEventListener(StateNotificationEventListener listener)
Sets the state notification (advisory) event listener for this connection.
|
void |
suspend()
Suspends a connection.
|
clearWarnings, close, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCatalog, getClientInfo, getClientInfo, getHoldability, getMetaData, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setClientInfo, setClientInfo, setHoldability, setReadOnly, setSavepoint, setSavepoint, setTransactionIsolation, setTypeMap
isWrapperFor, unwrap
java.lang.String getName()
JDBC Factory
are unique.void connect() throws DatabaseSQLException
getState()
to determine when a connection is in
ConnectionState.CONNECTED
state before proceeding.DatabaseSQLException
void disconnect() throws DatabaseSQLException
DatabaseSQLException
void suspend()
void resume()
void forceStateCheck()
boolean isPrimary()
void setPrimary(boolean primary)
primary
- booleanboolean isActive()
true
is the current connection is active and connected.void setServiceLogger(Logger logger)
logger
- ILoggerLogger getServiceLogger()
null
if one is not set.void setStateNotificationEventListener(StateNotificationEventListener listener)
ConnectionStateChangeAdvisory
event every time a connection state change occurs.listener
- IStateNotificationEventListenerStateNotificationEventListener getStateNotificationEventListener()
null
if a listener is not set.void setExceptionEventListener(ExceptionEventListener listener)
DatabaseSQLException
event in case of
an exception.listener
- IExceptionEventListenerExceptionEventListener getExceptionEventListener()
null
if a listener is not set.ConnectionState getState()
void raiseException(DatabaseSQLException e)
e
- DatabaseSQLExceptionConnection getRawConnection()
static Connection getRawConnection(Connection connection)
Copyright © 2015-2024 StreamScape Technologies. All rights reserved.