Sirius.server.sql

Class DBConnectionPool

java.lang.Object

Sirius.server.AbstractShutdownable

Sirius.server.Shutdown

Sirius.server.sql.DBConnectionPool

All Implemented Interfaces:

Serializable, Shutdownable, DBBackend

public class DBConnectionPool
extends Shutdown
implements DBBackend

DOCUMENT ME!

Version:

$Revision$, $Date$

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	DBConnectionPool.CheckConnection DOCUMENT ME!

Field Summary

Fields

Modifier and Type	Field and Description
int	retriesOnError

Fields inherited from class Sirius.server.Shutdown

PRIORITY_EARLIER, PRIORITY_EARLIEST, PRIORITY_LATER, PRIORITY_LATEST, PRIORITY_NORMAL

Constructor Summary

Constructors

Constructor and Description
DBConnectionPool(DBClassifier dbc) Creates a new DBConnectionPool object.
DBConnectionPool(ServerProperties props) Creates a new DBConnectionPool object.

Method Summary

Modifier and Type	Method and Description
void	closeConnections() DOCUMENT ME!
Connection	getConnection() Returns a native JDBC Connection.
Connection	getConnection(boolean longTerm) Deprecated. Use either getConnection() or getLongTermConnection()
DBConnection	getDBConnection() Deprecated. this operation is marked as deprecated as it is discouraged to use a DBConnection directly. Use a DBBackend instead. This method is subject to be refactored to private access.
DBConnection	getDBConnection(boolean longTerm) Deprecated. this operation is marked as deprecated as it is discouraged to use a DBConnection directly. Use a DBBackend instead. This method is subject to be refactored to private access.
DBConnection	getDBConnection(boolean longTerm, boolean cleanup) Deprecated. this operation is marked as deprecated as it is discouraged to use a DBConnection directly. Use a DBBackend instead. This method is subject to be refactored to private access.
Connection	getLongTermConnection() DOCUMENT ME!
int	getRetriesOnError() Gets the current number of retries.
static boolean	isDbErrorTransient(SQLException se) Attempt to figure out whether a given database error could be transient and might be worth a retry.
void	releaseDbConnection(Connection connection) DOCUMENT ME!
void	setRetriesOnError(int noOfRetries) Sets the number of retries the backend shall perform in case of an error during execution.
ResultSet	submitInternalQuery(String descriptor, Object... parameters) This operation shall be used to execute queries that related to the tables of the underlying cids system (cs_*).
int	submitInternalUpdate(String descriptor, Object... parameters) This operation shall be used to execute updates that related to the tables of the underlying cids system (cs_*).
ResultSet	submitQuery(int sqlID, Object... parameters) DOCUMENT ME! This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.
ResultSet	submitQuery(String descriptor, Object... parameters) DOCUMENT ME! This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.
int	submitUpdate(int sqlID, Object... parameters) DOCUMENT ME! This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.
int	submitUpdate(String descriptor, Object... parameters) DOCUMENT ME! This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.

Methods inherited from class Sirius.server.Shutdown

addShutdown, addShutdown, createShutdown, internalShutdown, removeShutdown

Methods inherited from class Sirius.server.AbstractShutdownable

isDown, shutdown

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface Sirius.server.Shutdownable

isDown, shutdown

Field Detail

retriesOnError

public transient int retriesOnError

Constructor Detail

DBConnectionPool

public DBConnectionPool(DBClassifier dbc)

Creates a new DBConnectionPool object.

Parameters:

dbc - DOCUMENT ME!

Throws:

ServerExitError - DOCUMENT ME!

DBConnectionPool

public DBConnectionPool(ServerProperties props)

Creates a new DBConnectionPool object.

Parameters:

props - DOCUMENT ME!

Method Detail

getDBConnection

@Deprecated
public DBConnection getDBConnection()

Deprecated. this operation is marked as deprecated as it is discouraged to use a DBConnection directly. Use a DBBackend instead. This method is subject to be refactored to private access.

DOCUMENT ME!

Returns:

DOCUMENT ME!

getDBConnection

@Deprecated
public DBConnection getDBConnection(boolean longTerm)

Deprecated. this operation is marked as deprecated as it is discouraged to use a DBConnection directly. Use a DBBackend instead. This method is subject to be refactored to private access.

DOCUMENT ME!

Parameters:

longTerm - DOCUMENT ME!

Returns:

DOCUMENT ME!

getDBConnection

@Deprecated
public DBConnection getDBConnection(boolean longTerm,
                                                boolean cleanup)

Deprecated. this operation is marked as deprecated as it is discouraged to use a DBConnection directly. Use a DBBackend instead. This method is subject to be refactored to private access.

DOCUMENT ME!

Parameters:

longTerm - DOCUMENT ME!

cleanup - DOCUMENT ME!

Returns:

DOCUMENT ME!

releaseDbConnection

public void releaseDbConnection(Connection connection)

DOCUMENT ME!

Parameters:

connection - DOCUMENT ME!

closeConnections

public void closeConnections()

DOCUMENT ME!

setRetriesOnError

public void setRetriesOnError(int noOfRetries)

Description copied from interface: DBBackend

Sets the number of retries the backend shall perform in case of an error during execution. A negative integer will be interpreted as 0. The retry shall only take place if the underlying error indicates that the retry could be senseful (e.g. connection drop, db restart ...).

Specified by:

setRetriesOnError in interface DBBackend

Parameters:

noOfRetries - the number of retries that shall be performed in case of an error during execution

See Also:

DBBackend.getRetriesOnError()

getRetriesOnError

public int getRetriesOnError()

Description copied from interface: DBBackend

Gets the current number of retries. 0 or a negative int means that the operation will be performed exactly once, 1 means that the operation will be executed up to two times, 2 up to three times and so on. The retry shall only take place if the underlying error indicates that the retry could be senseful (e.g. connection drop, db restart ...).

Specified by:

getRetriesOnError in interface DBBackend

Returns:

the current number of retries

getConnection

public Connection getConnection(boolean longTerm)
                         throws SQLException

Deprecated. Use either getConnection() or getLongTermConnection()

DOCUMENT ME!

Parameters:

longTerm - true, iff a long term connectionn should be returned. Caution: Long term connections must be released after use.

Returns:

DOCUMENT ME!

Throws:

SQLException - DOCUMENT ME!

getLongTermConnection

public Connection getLongTermConnection()
                                 throws SQLException

DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

SQLException - DOCUMENT ME!

getConnection

public Connection getConnection()
                         throws SQLException

Description copied from interface: DBBackend

Returns a native JDBC Connection.

Specified by:

getConnection in interface DBBackend

Returns:

a native JDBC Connection

Throws:

SQLException - if any error occurs while acquiring the Connection

submitInternalQuery

public ResultSet submitInternalQuery(String descriptor,
                                     Object... parameters)
                              throws SQLException

Description copied from interface: DBBackend

This operation shall be used to execute queries that related to the tables of the underlying cids system (cs_*). The available query descriptors are defined within this interface. Any other given descriptor String results in a SQLException.
The number of given parameters must match the parameter count of the statement described by the given descriptor. If the number of the parameters mismatch a SQLException is thrown.

This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.

Specified by:

submitInternalQuery in interface DBBackend

Parameters:

descriptor - one of the descriptors defined in this interface

parameters - the parameters the underlying query will take

Returns:

the ResultSet of the executed query

Throws:

SQLException -

• if the given descriptor is invalid
• if the parameter count mismatches
• if any other error occurs during execution
• if shutdown has been called

submitInternalUpdate

public int submitInternalUpdate(String descriptor,
                                Object... parameters)
                         throws SQLException

Description copied from interface: DBBackend

This operation shall be used to execute updates that related to the tables of the underlying cids system (cs_*). The available query descriptors are defined within this interface. Any other given descriptor String results in a SQLException.
The number of given parameters must match the parameter count of the statement described by the given descriptor. If the number of the parameters mismatch a SQLException is thrown.

This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.

Specified by:

submitInternalUpdate in interface DBBackend

Parameters:

descriptor - one of the descriptors defined in this interface

parameters - the parameters the underlying query will take

Returns:

the row count affected by the executed update

Throws:

SQLException -

• if the given descriptor is invalid
• if the parameter count mismatches
• if any other error occurs during execution
• if shutdown has been called

submitQuery

public ResultSet submitQuery(String descriptor,
                             Object... parameters)
                      throws SQLException

Description copied from interface: DBBackend

DOCUMENT ME!

This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.

Specified by:

submitQuery in interface DBBackend

Parameters:

descriptor - DOCUMENT ME!

parameters - DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

SQLException - DOCUMENT ME!

submitQuery

public ResultSet submitQuery(int sqlID,
                             Object... parameters)
                      throws SQLException

Description copied from interface: DBBackend

DOCUMENT ME!

This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.

Specified by:

submitQuery in interface DBBackend

Parameters:

sqlID - DOCUMENT ME!

parameters - DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

SQLException - DOCUMENT ME!

submitUpdate

public int submitUpdate(String descriptor,
                        Object... parameters)
                 throws SQLException

Description copied from interface: DBBackend

DOCUMENT ME!

This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.

Specified by:

submitUpdate in interface DBBackend

Parameters:

descriptor - DOCUMENT ME!

parameters - DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

SQLException - DOCUMENT ME!

submitUpdate

public int submitUpdate(int sqlID,
                        Object... parameters)
                 throws SQLException

Description copied from interface: DBBackend

DOCUMENT ME!

This operation shall throw a SQLException if the Shutdownable.shutdown() has already been called.

Specified by:

submitUpdate in interface DBBackend

Parameters:

sqlID - DOCUMENT ME!

parameters - DOCUMENT ME!

Returns:

DOCUMENT ME!

Throws:

SQLException - DOCUMENT ME!

isDbErrorTransient

public static boolean isDbErrorTransient(SQLException se)

Attempt to figure out whether a given database error could be transient and might be worth a retry. Detects things like network timeouts, transaction deadlocks, serialization failures, connection drops, etc.

Parameters:

se - Exception thrown by persistence provider

Returns:

True if the error might be transient