org.tentackle.dbms.ConnectionManager Maven / Gradle / Ivy
Show all versions of tentackle-database Show documentation
/**
* Tentackle - http://www.tentackle.org
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
package org.tentackle.dbms;
import java.util.Collection;
/**
* 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
*/
public interface ConnectionManager {
/**
* The manager's name.
*
* @return the name
*/
String getName();
/**
* Logs in a session.
* It is up to the manager how to verify whether the session 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
* session is logged out.
*
* @param session the session to login
* @return the unique ID of the session (> 0)
* @throws org.tentackle.session.PersistenceException if login failed.
*/
int login(Db session);
/**
* Logs out a session.
* The session is not allowed to attach anymore. If the session is still attached,
* a rollback of any pending transaction is done and an exception thrown.
*
* @param session the session to logout
* @throws org.tentackle.session.PersistenceException if logout failed.
*/
void logout(Db session);
/**
* Gets the maximum number of allowed sessions managed by this manager.
*
* @return max. number of concurrent logins, 0 = unlimited
*/
int getMaxSessions();
/**
* Gets the number of sessions.
*
* @return the number of concurrent logins
*/
int getNumSessions();
/**
* Shuts down this connection manager.
* All connections are closed and the threads stopped.
* Application servers should invoke this method when shut down.
*/
void shutdown();
/**
* Attaches a {@link 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.
*
* Upon return the the session will reference the connection.
*
* @param session the session
* @throws org.tentackle.session.PersistenceException if attach failed.
*/
void attach(Db session);
/**
* Detaches a connection from a {@link 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.
*
* @param session the session
* @throws org.tentackle.session.PersistenceException if detach failed.
*/
void detach(Db session);
/**
* Detaches but also scans for pending statements to cleanup.
*
* This will detach at any nesting level!
*
* @param session the session
*/
void forceDetach(Db session);
/**
* Gets the maximum number of connections.
*
* @return max. number of concurrent connections, 0 = unlimited
*/
int getMaxConnections();
/**
* Gets the number of open connections.
*
* @return the number of connections
*/
int getNumConnections();
/**
* Gets the connections.
*
* @return the connection
*/
Collection getConnections();
}