org.tentackle.db
Interface ConnectionManager

All Known Implementing Classes:

DefaultConnectionManager, MpxConnectionManager

public interface ConnectionManager

Connection Manager for local connections.
JDBC connections are never used directly. Instead Db-instances refer to a ConnectionManager in order to use a connection. The usage of a connection is initiated by an attach operation. After completion of the task (transaction, one-shot, etc...) the Db will be detached. The connection manager as a broker in between the Db and a connection gives the opportunity to multiplex connections. This is especially useful in application servers. Note that connection managers are not used in remote Db instances.

Author:

harald

Method Summary

ManagedConnection	attach(int id) Attaches a Db to a connection. A Db must be attached before it can use any statements.
void	detach(int id) Detaches a connection from a Db. A Db must be detached to release the connection for use of other Db instances.
int	getMaxConnections() Gets the maximum number of connections.
int	getMaxLogins() Gets the maximum number of allowed logins.
int	login(Db db) Logs in a Db connection. It is up to the manager how to verify whether the Db is allowed to open, a real connection is initiated or just an application level authorization is performed.
Db	logout(int id) Logs out a Db connection.
void	shutdown() Shuts down this connection manager. All connections are closed and the threads stopped.

Method Detail

login

int login(Db db)
          throws DbRuntimeException

Logs in a Db connection.
It is up to the manager how to verify whether the Db is allowed to open, a real connection is initiated or just an application level authorization is performed. Note that the ID may be recycled by the manager after a Db is logged out.

Parameters:

db - the db to login

Returns:

the connection ID of the db (> 0)

Throws:

DbRuntimeException - if login failed.

logout

Db logout(int id)
          throws DbRuntimeException

Logs out a Db connection. The Db is not allowed to attach anymore. If the Db is still attached, a rollback of any pending tx is done and an exception thrown.

Parameters:

id - the connection ID of the db

Returns:

the logged out Db

Throws:

DbRuntimeException - if logout failed.

attach

ManagedConnection attach(int id)
                         throws DbRuntimeException

Attaches a Db to a connection.
A Db must be attached before it can use any statements. The framework will attach at the begining of a transaction or when getting a prepared statement or when getting a one-shot non-prepared statement. Note that attachments can be nested to any depth, i.e. only the first attach really binds the connection to the Db.

Parameters:

id - the connection ID of the db

Returns:

the connection attached to be used by subsequent operations

Throws:

DbRuntimeException - if attach failed.

detach

void detach(int id)
            throws DbRuntimeException

Detaches a connection from a Db.
A Db must be detached to release the connection for use of other Db instances. The framework will detach the db on every commit or rollback, after executeUpdate or after a resultset is closed for an executeQuery. Note that attachments can be nested to any depth, i.e. only the last detach really unbinds the connection from the Db.

Parameters:

id - the connection ID of the db

Throws:

DbRuntimeException - if detach failed.

getMaxLogins

int getMaxLogins()

Gets the maximum number of allowed logins.

Returns:

max. number of concurrent logins, 0 = unlimited

getMaxConnections

int getMaxConnections()

Gets the maximum number of connections.

Returns:

max. number of concurrent connections, 0 = unlimited

shutdown

void shutdown()

Shuts down this connection manager.
All connections are closed and the threads stopped. Application servers should invoke this method when shut down.