planetj.database
Class DatabaseManager

java.lang.Object
  |
  +--planetj.database.DatabaseManager

public class DatabaseManager

extends Object

Manages the Connections to one or more databases. Creating a new database connection is costly, so this class maintains a connection pool for each database. Applications use the getConnection(String) method to get a Connection object for a database, and the freeConnection() method to return a Connection to the connection pool when they are through with it. The close() method of a Connection can also be invoked to return that Connection to the connection pool.

It is important for applications to return any Connections they get from the pool. Any section of code that gets and uses a Connection should be enclosed in a try{} statement, and the Connection returned to the pool in a finally{} statement; that way the Connection will always be returned, even if an exception occurs.

Author:

PlanetJ Corporation

Field Summary

static byte	ACTION_RESTART_CONNECTION_POOL Constant for restarting a connection pool
static byte	ACTION_START_CONNECTION_POOL Constant for starting a connection pool
static byte	ACTION_STOP_CONNECTION_POOL Constant for stopping a connection pool

Constructor Summary

DatabaseManager()

Method Summary

static void	addConnectionListener(String alias, IConnectionListener listener) Adds a IConnectionListener to a connection pool
static ConnectionPoolReportDescriptor	beginReportMonitoring(ConnectionPoolReportDescriptor pReportDescriptor) Attaches a report descriptor to a connection pool.
static void	closeConnectionPool(String systemAlias) Closes a ConnectionPool, releasing all of its connections.
static void	closeConnectionPool(String systemAlias, int seconds) Waits the specified amount of time, and then closes a ConnectionPool, releasing all of its connections.
static int	connectionId(String systemURL, Connection conn) Deprecated.
static void	createConnectionPool(ConnectionRow pConnectionRow)
static void	createConnectionPool(String driver, DBSystem system, String user, String password, int minConnections, int maxConnections, int maxConnSeconds, int orphanTimeout) Creates and returns a new DataEngineConnectionPool using the given properties.
static void	createConnectionPool(String driver, DBSystem system, String user, String password, int minConnections, int maxConnections, int maxConnSeconds, int orphanTimeout, String connectionAlias) Creates and returns a new DataEngineConnectionPool using the given properties.
static void	createConnectionPool(String pSystemAlias, String pSystemAliasForLookUp) Creates a ConnectionPool with the specifed system alias.
static void	createConnectionPool(String driver, String systemURL, String urlAlias, String user, String password, int minConnections, int maxConnections, int maxConnSeconds, int orphanTimeout) Creates and returns a new DataEngineConnectionPool using the given properties.
static void	createDataSource(String JNDIName) Creates a datasource based on a given JNDI name.
static void	createDataSource(String JNDIName, Class systemClass) Creates a datasource based on a given JNDI name.
static void	createDataSource(String JNDIName, Class systemClass, String userID, String password) Creates a datasource based on a given JNDI name.
static boolean	doesConnectionPoolExist(String systemAlias) Returns whether or not a connection pool already exists for the specified system alias
static String	dump()
static String	dump(String alias)
static void	freeConnection(Connection conn) Frees up the given connection in the connection pool identified by the given key.
static void	freeConnection(String pSystemAlias, Connection pConnection) Deprecated. Use the single argument method instead
static ConnectionPoolReport	generateReport(String alias) Generates a report about a connection pool.
static Map	getAllConnectionPools() Gets all of the connection pools.
static Connection	getConnection(String pAlias) Returns a connection associated with the given alias
static int	getRetryAttempts() If the first attempt to get a connection fails, this many retry attempts will be made before giving up and throwing an exception.
static int	getRetryMillis() If the first attempt to get a connection fails, this many milliseconds will elapse between retries.
static boolean	isConnectionPoolAvailable(String pAlias) Deprecated. use isDataSourceAvailable instead
static boolean	isDataSourceAvailable(String pAlias) Tests if a datasource with the given name exists and is available.
static boolean	isUseBackgoundThreads() Tests if the DatabaseManager should use background threads to retrieve Library and Table objects before they are requested.
static boolean	performConnectionPoolAction(String alias, byte action) Performs an action on a connection pool
static void	reconnect(String pAlias) Shuts down all of the connections in the specified connection pool and restarts them.
static void	reconnect(String pAlias, int pMaxWaitMilliseconds) Shuts down all of the connections in the specified connection pool and restarts them.
static void	removeConnectionListener(String alias, IConnectionListener listener) Removes a IConnectionListener from a connection pool
static void	restartConnectionPool(String alias) If the specified connection pool is started it is shut down and restarted.
static void	setRetryAttempts(int newRetryAttempts) If the first attempt to get a connection fails, this many retry attempts will be made before giving up and throwing an exception.
static void	setRetryMillis(int newRetryMillis) If the first attempt to get a connection fails, this many milliseconds will elapse between retries.
static void	setTimeoutSeconds(String alias, int seconds) If no connections have been retrieved from the connection pool after this amount of time, then the connection pool will close itself.
static void	setUseBackgoundThreads(boolean newUseBackgoundThreads) Tests if the DatabaseManager should use background threads to retrieve Library and Table objects before they are requested.
static void	shutDownConnectionPool(String systemURL) Deprecated. Use closeConnectionPool(String) instead
static void	toggleStatus(ConnectionRow crow) Starts up the specified connection pool if it is not already started.

Methods inherited from class java.lang.Object

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

Field Detail

ACTION_START_CONNECTION_POOL

public static final byte ACTION_START_CONNECTION_POOL

Constant for starting a connection pool

See Also:

Constant Field Values

ACTION_STOP_CONNECTION_POOL

public static final byte ACTION_STOP_CONNECTION_POOL

Constant for stopping a connection pool

See Also:

Constant Field Values

ACTION_RESTART_CONNECTION_POOL

public static final byte ACTION_RESTART_CONNECTION_POOL

Constant for restarting a connection pool

See Also:

Constant Field Values

Constructor Detail

DatabaseManager

public DatabaseManager()

Method Detail

addConnectionListener

public static void addConnectionListener(String alias,
                                         IConnectionListener listener)

Adds a IConnectionListener to a connection pool

beginReportMonitoring

public static ConnectionPoolReportDescriptor beginReportMonitoring(ConnectionPoolReportDescriptor pReportDescriptor)
                                                            throws CMException

Attaches a report descriptor to a connection pool. Reports will periodically be generated as described by the descriptor. Only one report descriptor can be attached to any given connection pool, so this method will replace the previous report descriptor associated with the connection pool.

Returns:

The previous report descriptor associated with the connection pool

CMException

closeConnectionPool

public static void closeConnectionPool(String systemAlias)

Closes a ConnectionPool, releasing all of its connections. All field descriptors and related system resources are also cleared.

closeConnectionPool

public static void closeConnectionPool(String systemAlias,
                                       int seconds)

Waits the specified amount of time, and then closes a ConnectionPool, releasing all of its connections.

connectionId

public static int connectionId(String systemURL,
                               Connection conn)
                        throws DataEngineException

Deprecated.

Returns the connections id number in the connection pool associated with the specified key. If the connection pool doesn't exist or the connection doesn't exist within the pool, -1 is returned.

Parameters:

systemURL - String

conn - Connection

Returns:

int

DataEngineException

createConnectionPool

public static void createConnectionPool(String pSystemAlias,
                                        String pSystemAliasForLookUp)
                                 throws CMException

Creates a ConnectionPool with the specifed system alias. This only works if a row exists in the Connection table for that system alias.

Parameters:

pSystemAlias - The alias to use for reading the Connection table

pSystemAliasForLookUp - The alias for the ConnectionPools that will be created

CMException

createConnectionPool

public static void createConnectionPool(String driver,
                                        String systemURL,
                                        String urlAlias,
                                        String user,
                                        String password,
                                        int minConnections,
                                        int maxConnections,
                                        int maxConnSeconds,
                                        int orphanTimeout)
                                 throws CMException

Creates and returns a new DataEngineConnectionPool using the given properties. Note: if a DataEngineConnectionPool for the specified system already exists, then it is returned.

Parameters:

driver - String

systemURL - String

urlAlias - String

user - String

password - String

minConnections - int

maxConnections - int

CMException

createConnectionPool

public static void createConnectionPool(String driver,
                                        DBSystem system,
                                        String user,
                                        String password,
                                        int minConnections,
                                        int maxConnections,
                                        int maxConnSeconds,
                                        int orphanTimeout)
                                 throws CMException

Creates and returns a new DataEngineConnectionPool using the given properties. Note: if a DataEngineConnectionPool for the specified system already exists, then it is returned.

Parameters:

driver - String

system - DBSystem

user - String

password - String

minConnections - int

maxConnections - int

CMException

createConnectionPool

public static void createConnectionPool(String driver,
                                        DBSystem system,
                                        String user,
                                        String password,
                                        int minConnections,
                                        int maxConnections,
                                        int maxConnSeconds,
                                        int orphanTimeout,
                                        String connectionAlias)
                                 throws CMException

Creates and returns a new DataEngineConnectionPool using the given properties. Note: if a DataEngineConnectionPool for the specified system already exists, then it is returned.

Parameters:

driver - String

system - DBSystem

user - String

password - String

minConnections - int

maxConnections - int

CMException

createConnectionPool

public static void createConnectionPool(ConnectionRow pConnectionRow)
                                 throws CMException

CMException

createDataSource

public static void createDataSource(String JNDIName)
                             throws DataEngineException

Creates a datasource based on a given JNDI name. That JNDI name becomes the system alias for that datasource. The datasource is retrieved by first looking up the initial context using the default JNDI properties. (These properties must be in a file named "jndi.properties" located on the system classpath.) The initial context is then used to look up the specified datasource. Once this method has been invoked, Connections can be retrieved by passing the system alias (which is the JNDI name) into the getConnection() method.

DataEngineException

createDataSource

public static void createDataSource(String JNDIName,
                                    Class systemClass)
                             throws DataEngineException

Creates a datasource based on a given JNDI name. That JNDI name becomes the system alias for that datasource. The datasource is retrieved by first looking up the initial context using the default JNDI properties. (These properties must be in a file named "jndi.properties" located on the system classpath.) The initial context is then used to look up the specified datasource. Once this method has been invoked, Connections can be retrieved by passing the system alias (which is the JNDI name) into the getConnection() method.

DataEngineException

createDataSource

public static void createDataSource(String JNDIName,
                                    Class systemClass,
                                    String userID,
                                    String password)
                             throws DataEngineException

Creates a datasource based on a given JNDI name. That JNDI name becomes the system alias for that datasource. The datasource is retrieved by first looking up the initial context using the default JNDI properties. (These properties must be in a file named "jndi.properties" located on the system classpath.) The initial context is then used to look up the specified datasource. Once this method has been invoked, Connections can be retrieved by passing the system alias (which is the JNDI name) into the getConnection() method.

DataEngineException

doesConnectionPoolExist

public static boolean doesConnectionPoolExist(String systemAlias)

Returns whether or not a connection pool already exists for the specified system alias

Parameters:

systemAlias - The alias for which a connection pool may or may not exist

dump

public static String dump()

dump

public static String dump(String alias)

freeConnection

public static void freeConnection(String pSystemAlias,
                                  Connection pConnection)

Deprecated. Use the single argument method instead

Frees up the given connection in the connection pool identified by the given key.

freeConnection

public static void freeConnection(Connection conn)

Frees up the given connection in the connection pool identified by the given key.

Parameters:

conn - Connection

generateReport

public static ConnectionPoolReport generateReport(String alias)
                                           throws CMException

Generates a report about a connection pool.

CMException

getAllConnectionPools

public static Map getAllConnectionPools()

Gets all of the connection pools. This is an internal DataEngine method and should not be invoked by applications

getConnection

public static Connection getConnection(String pAlias)
                                throws DataEngineException

Returns a connection associated with the given alias

Parameters:

pAlias - The alias for the system to connect to

Returns:

A Connection to that system

DataEngineException

getRetryAttempts

public static int getRetryAttempts()

If the first attempt to get a connection fails, this many retry attempts will be made before giving up and throwing an exception. The default is 9.

getRetryMillis

public static int getRetryMillis()

If the first attempt to get a connection fails, this many milliseconds will elapse between retries. The default is 2000.

isConnectionPoolAvailable

public static boolean isConnectionPoolAvailable(String pAlias)

Deprecated. use isDataSourceAvailable instead

Tests if a datasource with the given name exists and is available.

isDataSourceAvailable

public static boolean isDataSourceAvailable(String pAlias)

Tests if a datasource with the given name exists and is available.

isUseBackgoundThreads

public static boolean isUseBackgoundThreads()

Tests if the DatabaseManager should use background threads to retrieve Library and Table objects before they are requested.

performConnectionPoolAction

public static boolean performConnectionPoolAction(String alias,
                                                  byte action)
                                           throws CMException

Performs an action on a connection pool

Parameters:

alias - The alias of the connection pool on which the action should be performed

action - The action that should be taken

Returns:

true if the action succeeded. false is returned if the action could not be taken (for example stopping a connection pool that is already stopped)

Throws:

CMException - Thrown if an error occurs while performing the action

reconnect

public static void reconnect(String pAlias)
                      throws CMException

Shuts down all of the connections in the specified connection pool and restarts them. Connections which are in use when this method is invoked are given 10 seconds to be freed by the application using them before they are forcibly shut down.

Parameters:

pAlias - The alias of the connection pool to reconnect to

CMException

reconnect

public static void reconnect(String pAlias,
                             int pMaxWaitMilliseconds)
                      throws CMException

Shuts down all of the connections in the specified connection pool and restarts them.

Parameters:

pAlias - The alias of the connection pool to reconnect to

pMaxWaitMilliseconds - The maximum time to wait for connections which are in use to be freed. After this amount of time, any connections still in use are forcibly shut down.

CMException

removeConnectionListener

public static void removeConnectionListener(String alias,
                                            IConnectionListener listener)

Removes a IConnectionListener from a connection pool

restartConnectionPool

public static void restartConnectionPool(String alias)
                                  throws CMException

If the specified connection pool is started it is shut down and restarted. If it is stopped it is started. The connection information must be in the CONNECTIONS table

CMException

setRetryAttempts

public static void setRetryAttempts(int newRetryAttempts)

If the first attempt to get a connection fails, this many retry attempts will be made before giving up and throwing an exception. The default is 9.

setRetryMillis

public static void setRetryMillis(int newRetryMillis)

If the first attempt to get a connection fails, this many milliseconds will elapse between retries. The default is 2000.

setTimeoutSeconds

public static void setTimeoutSeconds(String alias,
                                     int seconds)

If no connections have been retrieved from the connection pool after this amount of time, then the connection pool will close itself. (The exact amount of inactive time that must pass before the pool is shutdown will vary, but it will be equal to or greater than this value.) A negative value indicates that the connection pool will not shut down due to inactivity.

setUseBackgoundThreads

public static void setUseBackgoundThreads(boolean newUseBackgoundThreads)

Tests if the DatabaseManager should use background threads to retrieve Library and Table objects before they are requested.

shutDownConnectionPool

public static void shutDownConnectionPool(String systemURL)
                                   throws DataEngineException

Deprecated. Use closeConnectionPool(String) instead

Closes all the connections for the given system.

Parameters:

systemURL - String

DataEngineException

toggleStatus

public static void toggleStatus(ConnectionRow crow)
                         throws CMException

Starts up the specified connection pool if it is not already started. If it is already started, then it is closed.

CMException