com.sun.jdo.spi.persistence.support.sqlstore.connection

Class ConnectionManager

java.lang.Object

com.sun.jdo.spi.persistence.support.sqlstore.connection.ConnectionManager

public class ConnectionManager
extends Object

This class represents a connection manager, which creates a JDBC driver manager and manages established database connections. This class lets you specify the following settings for JDBC connections:

• JDBC driver type
• data source name (JDBC URL)
• user name
• password
• number of pooled connections (settable when running)
• how often to try to get a connection after failing the first time and how long to retry (settable when running)

If you define a connection manager as a component, you can define these settings when you partition the application instead of when you write the application.

You can change only the following settings when the connection manager is running:

• minimum and maximum number of pooled connections, although not whether pooling is on or off (setMinPool and setMaxPool)
• how often to try to get a connection after failing the first time and how long to retry for a connection (setMsWait and setMsInterval)

You cannot set any other setting while the connection manager is running. To change other settings, shut down the connection manager using the shutDown method, then change the settings. Then, start the connection manager using the startUp method.

If you use a connection manager to manage your database connections, the connection manager can also extend a SynerJ transaction to include JDBC database transactions. In other words, if the JDBC database transactions occur within a SynerJ transaction, the JDBC database transactions are committed or rolled back when the SynerJ transaction committed or rolled back.

You can set up your connection manager to manage database connections in the following ways:

• Start a new connection every time you request a connection. This approach is often referred to as client-based security, because the security for the connection is based on a particular database client and can be different for each client.
• Maintain a pool of connections for a given user name and password, and return one of these connections when you request a connection using the getConnection method with no parameters. This approach is often referred to as application-based security, because the security information for the pool of connections is the same and is the same for all clients of the application.
• Maintain a pool of connections for a given user name and password and start a new connection if you specify another user name and password with the getConnection method. This approach is a blend of client-based and application-based security.

You also have the choice of either defining the connection manager as a service object typed as a ConnectionManager object, or defining the connection manager by dynamically creating a ConnectionManager object in your code. If you define the connection manager as a service object, the SynerJ partitioning system can help you determine how to define partitions that contain the service object by being aware of where JDBC drivers are installed, for example. If you define the ConnectionManager object dynamically, then you need to keep such issues in mind when you define the partitions whose code defines the ConnectionManager objects; the partitioning system will not help you.

Starting a New Database Connection for Each Request (Client-based Security)

In this situation, the connection manager establishes a new connection each time you request a connection. By default, the connection manager does not establish and maintain a pool of connections. In this case, you can leave the maximum and minimum number of pooled connections set to 0. Each time you need a connection to the database, use the getConnection method. You can use the default user name, password, and database URL for the current connection manager by invoking the getConnection method with no parameters. The default settings are specified in one of the ConnectionManager constructors when you create the connection manager. You can also specify a user name, password, and database URL on the getConnection method.

Example of Using ConnectionManager without Pooling

 import java.sql.*;
 import com.sun.jdo.api.persistence.support.*;
 Connection con = myTransaction.getConnection();
 Statement stmt = con.createStatement();
 ResultSet rs = stmt.executeQuery("SELECT * FROM T1");
 

Using a Pool of Database Connections (Application-based Security)

When you create a connection manager using the ConnectionManager class, you can have the connection manager establish a pool of connections for a given user name and password to allow a thread to using an existing connection instead of waiting for a new database connection to be created.

To create a connection manager with a pool of connections using a service object:

1. Define a service object of the class ConnectionManager.
2. In the Partition Workshop, set the component properties for the component instance represented by the service object to define the driver name and the default database URL, user name, and password. You can also define the values for the minimum connections and the maximum connections for the connection pool, as well as for how often and how long to try to get a connection after an initial failure to do so.

   If you set the values for the minimum and maximum connections to 0, then no pool of connections is established. Any value greater than 0 means that a pool of connections is established. The maximum value must be equal to or greater than the value of the minimum value. If you set the maximum and minimum as equal values, the number of connections established for the pool will be constant.

   The connection manager establishes the minimum number of connections when it starts up using the default database URL, user name, and password.

To get one of the pooled connections, you can use the getConnection method with no parameters. If all the existing connections are in use, the connection manager establishes another connection with the same database URL, user name, and password and adds it to the pool, up to the specified maximum number of connections.

When you have finished using a connection, you can use the close() method to return the connection to the pool of available connections. The connection manager periodically checks its pool of connections, and can reduce the number of established connections to the minimum number, if enough connections are not in use. At runtime, you can change the maximum and minimum number of connections, because the ConnectionManager is a component.

Using a Pool of Connections and Starting New Connections

You can have the connection manager establish and maintain a pool of connections and have the connection manager establish new connections on a request-by-request basis.

Example of Using ConnectionManager with Pooling

 import com.sun.jdo.api.persistence.support.*;
 void getT1Data() {
        // The following connection is from the connection pool.
        Connection myConn = myTransaction.getConnection();
        Statement myStatement = myConn.createStatement();
        ResultSet myResults = myStatement.executeQuery(
                "SELECT * FROM T1);
        // Free the connection; it is returned to the connection pool.
        myConn.close();

        // The connection manager creates a new connection for the
        // following request.
        Connection yourConn = myConnMgr.getConnection(
                "data:oracle:thin:@CUSTOMERDB:1521:ORCL", "paul", "omni8");
        Statement yourStatement = yourConn.createStatement();
        ResultSet yourResults = yourStatement.executeQuery(
        "SELECT Customer, Date, Amount FROM Orders");
        .
        .
        .
 }
 

Constructor Summary

Constructors

Constructor and Description
ConnectionManager() Default constructor.
ConnectionManager(String driverName) Creates a new connection manager and loads the named JDBC driver.
ConnectionManager(String driverName, String url) Creates a new connection manager, loads the named JDBC driver, and sets the default database URL for the new connection manager.
ConnectionManager(String driverName, String url, String userName) Creates a new connection manager, loads the named JDBC driver, and sets the default database URL and user name for the new connection manager.
ConnectionManager(String driverName, String url, String userName, char[] password) Creates a new connection manager, loads the named JDBC driver, and sets the default database URL, user name, and password for the new connection manager.
ConnectionManager(String driverName, String url, String userName, char[] password, int minPool, int maxPool) Creates a new connection manager, loads the named JDBC driver, and sets the default database URL, user name, password and minimum and maximum connection pool sizes for the new connection manager.
ConnectionManager(String driverName, String url, String userName, char[] password, int minPool, int maxPool, int msWait) Creates a new connection manager, loads the named JDBC driver, and defines the default values for the database URL, user name, password, minimum and maximum connection pool sizes, and the length of time to wait for a database connection.
ConnectionManager(String driverName, String url, String userName, char[] password, int minPool, int maxPool, int msWait, int msInterval) Creates a new connection manager, loads the named JDBC driver, and defines the default values for the database URL, user name, password, minimum and maximum connection pool sizes, the length of time to wait for a database connection, and how frequently to try again to get a database connection.

Method Summary

Modifier and Type	Method and Description
protected void	finalize() Disconnects all free database connections managed by the current connection manager and sets the shutDownPending flag to true.
Connection	getConnection() Establishes a connection to the default database URL using the default user name and password.
Connection	getConnection(String userName, char[] password) Establishes a connection to the database at the default database URL using the specified user name and password.
Connection	getConnection(String url, String userName, String password) Establishes a connection to the specified database URL using the specified user name and password.
String	getDriverName() Gets the name of the JDBC driver.
int	getLoginTimeout()
int	getMaxPool() Gets the maximum number of pooled connections for the current connection manager.
int	getMinPool() Gets the minimum number of pooled connections for the current connection manager.
int	getMsInterval() Gets the amount of time, in milliseconds, between the connection manager's attempts to get a pooled connection.
int	getMsWait() Gets the amount of time, in milliseconds, the connection manager should spend trying to get a pooled connection, which is the amount of time a requester might wait.
char[]	getPassword() Gets the default database password for the current connection manager.
String	getURL() Gets the default database URL for the data source.
String	getUserName() Gets the default database user name for the current connection manager.
protected void	replaceFreeConnection(ConnectionImpl c) Called by ConnectionImpl to save a connection when it is no longer used.
void	setDriverName(String driverName) Sets the name of the JDBC driver.
void	setLoginTimeout(int seconds)
void	setMaxPool(int maxPool) Sets the maximum number of pooled connections for the current connection manager.
void	setMinPool(int minPool) Sets the minimum number of pooled connections for the current connection manager.
void	setMsInterval(int msInterval) Sets the amount of time, in milliseconds, between the connection manager's attempts to get a pooled connection.
void	setMsWait(int msWait) Sets the amount of time, in milliseconds, the connection manager should spend trying to get a pooled connection, which is the amount of time a requester might wait.
void	setPassword(char[] password) Sets the default database password for the current connection manager.
void	setURL(String url) Sets the default database URL for the data source.
void	setUserName(String userName) Sets the default database user name for the current connection manager.
void	shutDown() Disconnects all free database connections managed by the current connection manager and sets the shutDownPending flag to true.
void	startUp() Starts up this ConnectionManager by loading the proper JDBC driver class and initializing the pool if necessary.
String	toString() Returns a string representation of the current ConnectionManager object.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionManager

public ConnectionManager()

Default constructor. Creates a new connection manager and loads the generic JDBC driver. You should typically use one of the other constructors, because you cannot change JDBC drivers after the connection manager has been created.

ConnectionManager

public ConnectionManager(String driverName)
                  throws ClassNotFoundException,
                         SQLException

Creates a new connection manager and loads the named JDBC driver.

Parameters:

driverName - name of JDBC driver.

Throws:

ClassNotFoundException - if the driver cannot be found.

SQLException - if a SQL error is encountered.

ConnectionManager

public ConnectionManager(String driverName,
                         String url)
                  throws ClassNotFoundException,
                         SQLException

Creates a new connection manager, loads the named JDBC driver, and sets the default database URL for the new connection manager.

Parameters:

driverName - the name of JDBC driver.

url - the database URL for the data source.

Throws:

ClassNotFoundException - if the driver cannot be found.

SQLException - if a SQL error is encountered.

ConnectionManager

public ConnectionManager(String driverName,
                         String url,
                         String userName)
                  throws ClassNotFoundException,
                         SQLException

Creates a new connection manager, loads the named JDBC driver, and sets the default database URL and user name for the new connection manager.

Parameters:

driverName - the name of JDBC driver.

url - the default database URL for the data source.

userName - the default user name for database connections.

Throws:

ClassNotFoundException - if the driver cannot be found.

SQLException - if a SQL error is encountered.

ConnectionManager

public ConnectionManager(String driverName,
                         String url,
                         String userName,
                         char[] password)
                  throws ClassNotFoundException,
                         SQLException

Creates a new connection manager, loads the named JDBC driver, and sets the default database URL, user name, and password for the new connection manager.

Parameters:

driverName - the name of JDBC driver.

url - the default database URL for the data source.

userName - the default user name for database connections.

password - the default password for database connections.

Throws:

ClassNotFoundException - if the driver cannot be found.

SQLException - if a SQL error is encountered.

ConnectionManager

public ConnectionManager(String driverName,
                         String url,
                         String userName,
                         char[] password,
                         int minPool,
                         int maxPool)
                  throws ClassNotFoundException,
                         SQLException

Creates a new connection manager, loads the named JDBC driver, and sets the default database URL, user name, password and minimum and maximum connection pool sizes for the new connection manager.

If minPool and maxPool are 0, connection pooling is disabled. If minPool is greater than 0 and maxPool is greater than or equal to minPool, this constructor creates a connection pool containing minPool connections.

Parameters:

driverName - the name of JDBC driver.

url - the default database URL for the data source.

userName - the default user name for database connections.

password - the default password for database connections.

minPool - the default minimum size of the connection pool.

maxPool - the default maximum size of the connection pool.

Throws:

ClassNotFoundException - if the driver cannot be found.

SQLException - if a SQL error is encountered or if the specified value of minPool is not less than or equal to the specified value of maxPool.

ConnectionManager

public ConnectionManager(String driverName,
                         String url,
                         String userName,
                         char[] password,
                         int minPool,
                         int maxPool,
                         int msWait)
                  throws ClassNotFoundException,
                         SQLException

Creates a new connection manager, loads the named JDBC driver, and defines the default values for the database URL, user name, password, minimum and maximum connection pool sizes, and the length of time to wait for a database connection.

If minPool and maxPool are 0, connection pooling is disabled. If minPool is greater than 0 and maxPool is greater than or equal to minPool, this constructor creates a connection pool containing minPool connections.

If msWait is set to 0, the connection manager does not try again to create or return a database connection if the first try fails. For any other value, the connection manager waits 1000 milliseconds (ms) (1 second) before trying again. If the msWait value is less than 1000 ms, the connection manager waits 1000 ms before trying. The connection manager continues trying until the value specified by msWait is met or exceeded.

If you want to set the interval length yourself, you can use the ConnectionManager constructor that specifies the msInterval parameter or the setInterval method.

Parameters:

driverName - the name of JDBC driver.

url - the default database URL for the data source.

userName - the default user name for database connections.

password - the default password for database connections.

minPool - the default minimum size of the connection pool.

maxPool - the default maximum size of the connection pool.

msWait - the total number of milliseconds to wait for a successful connection.

Throws:

ClassNotFoundException - if the driver cannot be found.

SQLException - if a SQL error is encountered or if the specified value of minPool is not less than or equal to the specified value of maxPool.

ConnectionManager

public ConnectionManager(String driverName,
                         String url,
                         String userName,
                         char[] password,
                         int minPool,
                         int maxPool,
                         int msWait,
                         int msInterval)
                  throws ClassNotFoundException,
                         SQLException

Creates a new connection manager, loads the named JDBC driver, and defines the default values for the database URL, user name, password, minimum and maximum connection pool sizes, the length of time to wait for a database connection, and how frequently to try again to get a database connection.

If minPool and maxPool are 0, connection pooling is disabled. If minPool is greater than 0 and maxPool is greater than or equal to minPool, this constructor creates a connection pool containing minPool connections.

If msWait or msInterval is set to 0, the connection manager does not try again to create or return a database connection if the first try fails.

For any other values greater than 0, the The connection manager continues trying after every specified value for msInterval until the value specified by msWait is met or exceeded. If the value for msInterval is greater than the value for msWait, the connection manager tries again to return a connection once, then fails if it could get a connection.

Parameters:

driverName - the name of JDBC driver.

url - the default database URL for the data source.

userName - the default user name for database connections.

password - the default password for database connections.

minPool - the default minimum size of the connection pool.

maxPool - the default maximum size of the connection pool.

msWait - the total number of milliseconds to wait to get a connection.

msInterval - the number of milliseconds to wait before trying again to get a connection.

Throws:

ClassNotFoundException - if the driver cannot be found.

SQLException - if a SQL error is encountered or if the specified value of minPool is not less than or equal to the specified value of maxPool.

Method Detail

getConnection

public Connection getConnection()
                         throws SQLException

Establishes a connection to the default database URL using the default user name and password.

If the current connection manager maintains a connection pool, this method returns a pooled connection instead of establishing a new connection. If all pooled connections are in use, and the total wait time (msWait) for the connection manager and the retry interval (msInterval) are not 0, then the connection manager tries to get a database connection after the retry interval. The connection manager continues to try until a pooled connection becomes available or until the total time equals or exceeds the wait time. If the wait time expires before the connection manager returns a database connection, this method throws a SQLException exception with SQLState = "08006".

If the current connection manager is not set to try again for connections (the wait time is 0) and no pooled connections are available, this method throws a SQLException exception with SQLState = "08006".

If the current connection manager is being shut down, this method throws a SQLException exception with SQLState = "08003".

Returns:

A new or pooled database connection.

Throws:

SQLException - if no database connection is available.

getConnection

public Connection getConnection(String userName,
                                char[] password)
                         throws SQLException

Establishes a connection to the database at the default database URL using the specified user name and password.

Parameters:

userName - the database user name.

password - the database password.

Returns:

A new database connection.

Throws:

SQLException - if the connection fails.

getConnection

public Connection getConnection(String url,
                                String userName,
                                String password)
                         throws SQLException

Establishes a connection to the specified database URL using the specified user name and password.

Parameters:

url - the database URL for the database.

userName - the database user name.

password - the database password.

Returns:

A new database connection.

Throws:

SQLException - if the connection fails.

startUp

public void startUp()
             throws ClassNotFoundException,
                    SQLException

Starts up this ConnectionManager by loading the proper JDBC driver class and initializing the pool if necessary.

You need to call this method if you are using the ConnectionManager as a component, or if you use the default constructor and set the attributes via the setXXX methods.

Throws:

ClassNotFoundException - if the driver cannot be found.

SQLException - if a SQL error is encountered.

shutDown

public void shutDown()
              throws SQLException

Disconnects all free database connections managed by the current connection manager and sets the shutDownPending flag to true. All busy connections that are not participating in a transaction will be closed when a yieldConnection() is performed. If a connection is participating in a transaction, the connection will be closed after the transaction is commited or rolledback.

Throws:

SQLException

finalize

protected void finalize()

Disconnects all free database connections managed by the current connection manager and sets the shutDownPending flag to true. All busy connections that are not participating in a transaction will be closed when a yieldConnection() is performed. If a connection is participating in a transaction, the connection will be closed after the transaction is commited or rolledback.

Overrides:

finalize in class Object

getDriverName

public String getDriverName()

Gets the name of the JDBC driver.

Returns:

Name of the JDBC driver.

See Also:

setDriverName(java.lang.String)

setDriverName

public void setDriverName(String driverName)
                   throws SQLException

Sets the name of the JDBC driver.

Parameters:

driverName - the name of the JDBC driver.

Throws:

SQLException - if the driverName is NULL.

See Also:

getDriverName()

getURL

public String getURL()

Gets the default database URL for the data source. This default is only for the current connection manager and was set by the ConnectionManager constructor. This default is used if you don't specify another database URL with a getConnection method. To change this default value, use the setURL method.

Returns:

The name of the default database URL.

See Also:

getConnection(), setURL(java.lang.String)

setURL

public void setURL(String url)
            throws SQLException

Sets the default database URL for the data source. This default is only for the current connection manager. To get a connection using a different data source than the default, use the getConnection method that specifies a database URL as a parameter.

Parameters:

url - URL for this connection manager.

Throws:

SQLException - if the URL is NULL.

See Also:

getConnection(), getURL()

getUserName

public String getUserName()

Gets the default database user name for the current connection manager. This default was set by the ConnectionManager constructor, and is used if you don't specify another user name with a getConnection method. To change this default value, use the setUserName method.

Returns:

The default database user name.

See Also:

getConnection(), setUserName(java.lang.String)

setUserName

public void setUserName(String userName)
                 throws SQLException

Sets the default database user name for the current connection manager.

Parameters:

userName - the default user name for the current connection manager.

Throws:

SQLException

See Also:

getUserName()

getPassword

public char[] getPassword()

Gets the default database password for the current connection manager. This default was set by the ConnectionManager constructor, and is used if you don't specify another password with a getConnection method. To change this default value, use the setPassword method.

Returns:

The default database password.

See Also:

getConnection(), setPassword(char[])

setPassword

public void setPassword(char[] password)
                 throws SQLException

Sets the default database password for the current connection manager.

Parameters:

password - the default password for the current connection manager.

Throws:

SQLException

See Also:

getPassword()

getMinPool

public int getMinPool()

Gets the minimum number of pooled connections for the current connection manager. If this value is 0, the connection manager does not maintain a connection pool until a connection is requested using the getConnection method with no parameters.

To change the minimum number of pooled connections, use the setMinPool method.

Returns:

The minimum number of pooled connections.

See Also:

getConnection(), setMinPool(int)

setMinPool

public void setMinPool(int minPool)
                throws SQLException

Sets the minimum number of pooled connections for the current connection manager. The default minimum number of pooled connections is 0, which means that no connections are pooled until a pooled connection is requested.

The specified value of the minPool parameter must be:

• greater than or equal to 0.
• greater than or equal to the current minimum number of pooled connections
• less than or equal to the maximum number of pooled connections

Otherwise, this method throws a SQLException.

Parameters:

minPool - the minimum number of pooled connections.

Throws:

SQLException - if the connection manager is being shut down or if the minPool value is not valid.

See Also:

getMaxPool(), getMinPool(), setMaxPool(int)

getMaxPool

public int getMaxPool()

Gets the maximum number of pooled connections for the current connection manager. If this value is 0, the connection manager does not maintain a connection pool. When you request a connection with the getConnection method, the getConnection method always returns a new connection.

To change the maximum number of pooled connections, use the setMaxPool method.

Returns:

The maximum number of pooled connections the current connection manager maintains.

See Also:

setMaxPool(int)

setMaxPool

public void setMaxPool(int maxPool)
                throws SQLException

Sets the maximum number of pooled connections for the current connection manager. The default maximum number of pooled connections is 0, which means that no connections are pooled.

The specified value of the maxPool parameter must be:

• greater than or equal to 0.
• greater than or equal to the current maximum number of pooled connections
• greater than or equal to the minimum number of pooled connections

Otherwise, this method throws a SQLException.

Parameters:

maxPool - the maximum number of pooled connections.

Throws:

SQLException - if the connection manager is being shut down or if the maxPool value is not valid.

See Also:

getMaxPool(), getMinPool(), setMinPool(int)

getMsWait

public int getMsWait()

Gets the amount of time, in milliseconds, the connection manager should spend trying to get a pooled connection, which is the amount of time a requester might wait.

This value is only meaningful when you use the getConnection to get a pooled connection, which means that no database URL, user name, or password is specified.

Returns:

The wait time in milliseconds.

See Also:

getConnection(), setMsInterval(int)

setMsWait

public void setMsWait(int msWait)
               throws SQLException

Sets the amount of time, in milliseconds, the connection manager should spend trying to get a pooled connection, which is the amount of time a requester might wait. Setting this value to 0 means that the connection manager does not try again to get a database connection if it fails on the first try.

This value is only meaningful when you use the getConnection to get a pooled connection, which means that no database URL, user name, or password is specified.

The connection manager retries after the set interval until the total wait time is equal to or greater than the specified wait time. You can determine the total number of tries for a connection based on wait time and interval settings using the following formula, where msWait is the wait time, msInterval is the time between attempts to get a connection:

 tries = msWait/msInterval + 2
 

For example, if msWait is set to 2000 ms and msInterval is set to 1500 ms, then the connection manager will try to get a database connection 3 times before throwing an exception if it has failed.

If the wait time value is less than the set value for the interval between retries, but not zero, the connection manager waits the amount of time specified by the interval, tries once, then returns an exception if it still could not get a connection.

Parameters:

msWait - the wait time in milliseconds.

Throws:

SQLException

See Also:

getConnection(), getMsInterval(), getMsWait(), setMsInterval(int)

getMsInterval

public int getMsInterval()

Gets the amount of time, in milliseconds, between the connection manager's attempts to get a pooled connection.

This value is only meaningful when you use the getConnection to get a pooled connection, which means that no database URL, user name, or password is specified.

Returns:

The length of the interval between tries in milliseconds.

See Also:

getConnection(), setMsInterval(int)

setMsInterval

public void setMsInterval(int msInterval)
                   throws SQLException

Sets the amount of time, in milliseconds, between the connection manager's attempts to get a pooled connection.

This value is only meaningful when you use the getConnection to get a pooled connection, which means that no database URL, user name, or password is specified.

The connection manager retries after the specified interval until the total wait time is equal to or greater than the set wait time. You can determine the total number of tries for a connection based on wait time and interval settings using the following formula, where msWait is the wait time, msInterval is the time between attempts to get a connection:

 tries = msWait/msInterval + 2
 

For example, if msWait is set to 2000 ms and msInterval is set to 1500 ms, then the connection manager will try to get a database connection 3 times before throwing an exception if it has failed.

If the wait time value is greater than 0 but less than the set value for the interval between retries, the connection manager waits the amount of time specified by the interval, tries once, then returns an exception if it still could not get a connection.

Parameters:

msInterval - the interval between attempts to get a database connection, in milliseconds.

Throws:

SQLException

See Also:

getConnection(), getMsInterval(), getMsWait(), setMsWait(int)

toString

public String toString()

Returns a string representation of the current ConnectionManager object.

Overrides:

toString in class Object

Returns:

A String decribing the contents of the current ConnectionManager object.

setLoginTimeout

public void setLoginTimeout(int seconds)
                     throws SQLException

Throws:

SQLException

getLoginTimeout

public int getLoginTimeout()
                    throws SQLException

Throws:

SQLException

replaceFreeConnection

protected void replaceFreeConnection(ConnectionImpl c)

Called by ConnectionImpl to save a connection when it is no longer used. Previous free connection can be released (closed) when a new one becomes available.