Enhydra 3.1 API

com.lutris.appserver.server.sql
Class StandardDatabaseManager

java.lang.Object
  |
  +--com.lutris.appserver.server.sql.StandardDatabaseManager

public class StandardDatabaseManager
extends java.lang.Object
implements DatabaseManager

The standard database manager implementation. A database manager manages logical databases. It provides a single object from which database connections, object ids (OIDs), transactions and queries can be obtained. The configuration file specifies what logical database to create.

The configuration data is specified as follows:

For each logical database, there is a set of entry names in the form DatabaseManager.DB.dbname. Where dbname is one of the listed logical databases.

DatabaseManager.DB.dbname.ClassType - This is an optional field which specifies the class of the logical database implementation or a symbolic name if one on the standard types are selected. This is recommended because although JDBC abstracts the data access, the functionality of each database is slightly different and this parameter allows for optimised usage. The following are standard types:

Note that since a single SQL user is used to access the database by the entire application, connections maybe kept open, thus saving this overhead on each request. Connections are opened as desired until the maximum configured is reached.

If a thread needs to process a transaction, it requests a connection. If none are available, then a new connection is created up to the configured maximum. A thread is queued waiting for a connection to be returned if a new connection can't be created.

Note also that multiple logical names may map to the same actual database, making it easy to migrate databases if necessary and to provide access through multiple users.

Since:
LBS1.8
Version:
$Revision: 1.20.12.1 $

Field Summary
protected  boolean debug
          Controls debugging for Transactions and Queries.
 
Fields inherited from interface com.lutris.appserver.server.sql.DatabaseManager
debug
 
Constructor Summary
StandardDatabaseManager(Config config)
          Creates a new DatabaseManager object and configures the logical databases defined in the config file.
 
Method Summary
 DBConnection allocateConnection()
          Allocate a connection to a thread.
 DBConnection allocateConnection(java.lang.String dbName)
          Allocate a connection to a thread.
 ObjectId allocateObjectId()
          Allocate an object id from the specified logical database.
 ObjectId allocateObjectId(java.lang.String dbName)
          Allocate an object id from the specified logical database.
 DBQuery createQuery()
          Create a query object for the default logical database.
 DBQuery createQuery(java.lang.String dbName)
          Create a query object for the specified logical database.
 DBTransaction createTransaction()
          Create a transaction object for the default logical database.
 DBTransaction createTransaction(java.lang.String dbName)
          Create a transaction object for the specified logical database.
 int getActiveConnectionCount(java.lang.String dbName)
          Gets the number of currently active connections.
 java.lang.String[] getLogicalDatabaseNames()
          Returns the list of managed logical databases.
 int getMaxConnectionCount(java.lang.String dbName)
          Gets the maximum number of concurent connections that existed at any time since this object was created, or resetMaxConnectionCount() was called.
 java.util.Date getMaxConnectionCountDate(java.lang.String dbName)
          Gets the time when the maximum refered to by maxConnectionCount() occured.
 long getRequestCount(java.lang.String dbName)
          Gets the number of requests made to the database since startup time.
 java.lang.String getType(java.lang.String dbName)
          Returns a description of the logical database type.
 LogicalDatabase loadLogicalDatabase(java.lang.String dbName, Config dbConfig)
          Actually load the specified logical database.
 void resetMaxConnectionCount(java.lang.String dbName)
          Reset the maximum connection count.
 void setDebugLogging(boolean condition)
          Turn debugging on or off.
 void setDefaultDatabase(java.lang.String dbName)
          Set the default logical database.
 void shutdown()
          Shutdown the database manager.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

debug

protected boolean debug
Controls debugging for Transactions and Queries.
Constructor Detail

StandardDatabaseManager

public StandardDatabaseManager(Config config)
                        throws ConfigException,
                               DatabaseManagerException,
                               java.sql.SQLException
Creates a new DatabaseManager object and configures the logical databases defined in the config file.
Parameters:
config - The configuration data for logical databases.
Throws:
ConfigException - If there is an error in the configuration file.
DatabaseManagerException - If a logical database name is specified twice in the configuration file.
java.sql.SQLException - If a SQL error occurs.
Method Detail

loadLogicalDatabase

public LogicalDatabase loadLogicalDatabase(java.lang.String dbName,
                                           Config dbConfig)
                                    throws DatabaseManagerException
Actually load the specified logical database. This method provides an easy way to override the default behavour.
Returns:
The logical database.
Throws:
DatabaseManagerException - if an error occurs creating the logical database.

allocateConnection

public DBConnection allocateConnection(java.lang.String dbName)
                                throws DatabaseManagerException,
                                       java.sql.SQLException
Allocate a connection to a thread. The connection should be returned to the allocator by calling its release() function. A thread will wait if no connections are available. Interupted exceptions are converted to errors. N.B. Can't be synchronized, as connection allocator allocate may wait.
Specified by:
allocateConnection in interface DatabaseManager
Parameters:
dbName - Logical name of the database to allocate a connection to.
Returns:
The allocated connection object.
Throws:
DatabaseManagerException - If a nonexistent logical database name is supplied.
java.sql.SQLException - If a SQL error occures.

allocateConnection

public DBConnection allocateConnection()
                                throws DatabaseManagerException,
                                       java.sql.SQLException
Allocate a connection to a thread. The connection should be returned to the allocator by calling its release() function. A thread will wait if no connections are available. Interupted exceptions are converted to errors. The connection is allocated from the default logical database.
Specified by:
allocateConnection in interface DatabaseManager
Returns:
The allocated connection object.
Throws:
DatabaseManagerException - If no default logical database has been set.
java.sql.SQLException - If a SQL error occurs.
See Also:
setDefaultDatabase(java.lang.String)

allocateObjectId

public ObjectId allocateObjectId(java.lang.String dbName)
                          throws DatabaseManagerException,
                                 ObjectIdException
Allocate an object id from the specified logical database.
Specified by:
allocateObjectId in interface DatabaseManager
Parameters:
name - Logical name of the database from which to obtain an object id.
Returns:
The allocated unique OID
Throws:
DatabaseManagerException - If a nonexistent logical database name is supplied.
ObjectIdException - If a problem (e.g. SQL error) occured in obtaining the OID.

allocateObjectId

public ObjectId allocateObjectId()
                          throws DatabaseManagerException,
                                 ObjectIdException
Allocate an object id from the specified logical database.
Specified by:
allocateObjectId in interface DatabaseManager
Returns:
The allocated connection object.
Throws:
DatabaseManagerException - If a nonexistent default logical database has been set.
ObjectIdException - If a problem (e.g. SQL error) occured in obtaining the OID.
See Also:
setDefaultDatabase(java.lang.String)

createTransaction

public DBTransaction createTransaction(java.lang.String dbName)
                                throws DatabaseManagerException,
                                       java.sql.SQLException
Create a transaction object for the specified logical database.
Specified by:
createTransaction in interface DatabaseManager
Parameters:
dbName - Logical name of the database from which to obtain a transaction.
Returns:
The transaction
Throws:
DatabaseManagerException - If a nonexistent or invalid logical database name is supplied.
java.sql.SQLException - If a problem occured creating the transaction.

createTransaction

public DBTransaction createTransaction()
                                throws DatabaseManagerException,
                                       java.sql.SQLException
Create a transaction object for the default logical database.
Specified by:
createTransaction in interface DatabaseManager
Parameters:
dbName - Logical name of the database from which to obtain a transaction.
Returns:
The transaction
Throws:
DatabaseManagerException - If a nonexistent default logical database has been set.
java.sql.SQLException - If a problem occured creating the transaction.
See Also:
setDefaultDatabase(java.lang.String)

createQuery

public DBQuery createQuery(java.lang.String dbName)
                    throws DatabaseManagerException,
                           java.sql.SQLException
Create a query object for the specified logical database.
Specified by:
createQuery in interface DatabaseManager
Parameters:
dbName - Logical name of the database from which to obtain a query.
Returns:
The query
Throws:
DatabaseManagerException - If a nonexistent or invalid logical database name is supplied.
java.sql.SQLException - If a problem occured creating the query.

createQuery

public DBQuery createQuery()
                    throws DatabaseManagerException,
                           java.sql.SQLException
Create a query object for the default logical database.
Specified by:
createQuery in interface DatabaseManager
Parameters:
dbName - Logical name of the database from which to obtain a query.
Returns:
The query
Throws:
DatabaseManagerException - If a nonexistent default logical database has been set.
java.sql.SQLException - If a problem occured creating the query.
See Also:
setDefaultDatabase(java.lang.String)

setDefaultDatabase

public void setDefaultDatabase(java.lang.String dbName)
                        throws DatabaseManagerException
Set the default logical database. This should only be called after the logical database ( has been established.
Specified by:
setDefaultDatabase in interface DatabaseManager
Parameters:
dbName - The default logical database.
Throws:
DatabaseManagerException - if the logical database name is invalid or not found.

shutdown

public void shutdown()
Shutdown the database manager. All logical databases will be shutdown and all connections closed.
Specified by:
shutdown in interface DatabaseManager

getLogicalDatabaseNames

public java.lang.String[] getLogicalDatabaseNames()
Returns the list of managed logical databases.
Specified by:
getLogicalDatabaseNames in interface DatabaseManager
Returns:
List of logical database names.

getType

public java.lang.String getType(java.lang.String dbName)
                         throws DatabaseManagerException
Returns a description of the logical database type.
Specified by:
getType in interface DatabaseManager
Parameters:
dbName - The logical database name.
Returns:
A text description of the logical database type.
Throws:
DatabaseManagerException - If a nonexistent logical database name is supplied.

getRequestCount

public long getRequestCount(java.lang.String dbName)
                     throws DatabaseManagerException
Gets the number of requests made to the database since startup time.
Specified by:
getRequestCount in interface DatabaseManager
Parameters:
The - name of the logical database.
Returns:
The number of database requests since the server started.
Throws:
DatabaseManagerException - If a nonexistent logical database name is supplied.

getActiveConnectionCount

public int getActiveConnectionCount(java.lang.String dbName)
                             throws DatabaseManagerException
Gets the number of currently active connections.
Specified by:
getActiveConnectionCount in interface DatabaseManager
Parameters:
dbName - The name of the logical database.
Returns:
The number of currently active connections.
Throws:
DatabaseManagerException - If a nonexistent logical database name is supplied.

getMaxConnectionCount

public int getMaxConnectionCount(java.lang.String dbName)
                          throws DatabaseManagerException
Gets the maximum number of concurent connections that existed at any time since this object was created, or resetMaxConnectionCount() was called. This is a historical highwater mark. If you do not implement this feature, return -1.
Specified by:
getMaxConnectionCount in interface DatabaseManager
Parameters:
dbName - The name of the logical database.
Returns:
The highwater mark for number of connections, or -1.
Throws:
DatabaseManagerException - If a nonexistent logical database name is supplied.

getMaxConnectionCountDate

public java.util.Date getMaxConnectionCountDate(java.lang.String dbName)
                                         throws DatabaseManagerException
Gets the time when the maximum refered to by maxConnectionCount() occured.
Specified by:
getMaxConnectionCountDate in interface DatabaseManager
Parameters:
dbName - The name of the logical database.
Returns:
The Date of when the maximum number of connections occured.
Throws:
DatabaseManagerException - If a nonexistent logical database name is supplied.

resetMaxConnectionCount

public void resetMaxConnectionCount(java.lang.String dbName)
                             throws DatabaseManagerException
Reset the maximum connection count. See maxConnectionCount(). The highwater mark should be reset to the current number of connections.
Specified by:
resetMaxConnectionCount in interface DatabaseManager
Parameters:
dbName - The name of the logical database.
Throws:
DatabaseManagerException - If a nonexistent logical database name is supplied.

setDebugLogging

public void setDebugLogging(boolean condition)
Turn debugging on or off.
Parameters:
condition - on of off.

Enhydra 3.1 API