com.microdeveloper.db.jndi
Class ConnectionPool

java.lang.Object
  com.microdeveloper.db.jndi.ConnectionPool

public final class ConnectionPool
extends Object

ConnectionPool is designed to ease the burden of establishing pooled connections within Servlets or JSP pages. It supports many common functions for connecting to and verifying the connections to a given database. It is intended for use with Oracle databases using the Oracle supplied JDBC drivers. Further, it is intended to work with JNDI pooled connection resources.

A typical usage would be from within a JSP page such as this:

ConnectionPoolInterface db = new ConnectionPool("test").getConnectionPoolInterface();

Where "test" would be the alias to your database in a properties file. The typical properties entry would look like this:

  #Microdeveloper development database

  test.JNDI=test

  #default test user

  test.User=scott

  #Scott's password

  test.Pw=Rq2lKFXWb2c\=

  #Driver

  test.Driver=oracle.jdbc.driver.OracleDriver

  #URL

  test.Url=jdbc\:oracle\:thin\:@oracle.microdeveloper.com\:1521\:test

the User and Pw entry would be optional, but if found, would facilitate the one line connection example shown above.

This class is dependent on the com.microdeveloper.security.encryption.DesEncrypter class for evaluating the passwords stored in the database meta-data parameters. It expects passwords to be encrypted so adding clear text to the parameter files will not work.

Revision History:
Jan 18, 2005 12:40:22 Created. Apr 06, 2005 20:21:53 Added overloaded calls for closing the database for backward compatibility with other classes

Since:

1.4

Version:

1.1

Author:

Gregg Lagnese

See Also:

DesEncrypter, Connector

Field Summary

static String	ERR_CON The constant in Connector that indicates that the connection to the database could not be opened.
static String	ERR_CTX The constant in Connector that indicates the JNDI context was not found.
static String	ERR_DS The constant in Connector that indicates the JNDI datasource was not found.
static String	ERR_NC The constant in Connector that indicates that an operation was attempted on a closed or non-existant connection.
static String	ERR_OPN The constant in Connector that indicates that an attempt was made to open a connection that was already open.
static int	ERRTYPE
static int	MYSQLTYPE
static int	ORACLETYPE
static int	OTHERTYPE

Constructor Summary

ConnectionPool()
Create a new instance of ConnectionPool.

ConnectionPool(String dbAlias)
Create a new instance of ConnectionPool and connects to the given database.

ConnectionPool(String dbAlias, String name, String pw)
Create a new instance of Connection pool and connects to the given database using username and password.

Method Summary

void	close() Closes the current pooled connection.
void	connect() Opens the connection to the database using the established properties.
void	connect(String dbAlias) Connects to the given database.
void	connect(String dbAlias, String name, String pw) Open the connection to database using name and password given.
void	disconnect() Closes the current pooled connection.
String	generateEncryptedPassword(String dbAlias, String name, String password) Generates a new encrypted password and returns the result.
Connection	getConnection() Returns the active java.sql.Connection object.
ConnectionPoolInterface	getConnectionPoolInterface() Obtain the interface to the ConnectionPool
String	getDb() Returns the currently established database name
String	getDbAlias() Returns the currently established database alias
String	getDriver() Returns the driver currently in effect from the dbnames file.
String	getJNDIDbFromAlias(String dbAlias) Returns the associated JNDI database name for the given alias name
String	getPassword() Returns the encrypted password for the current user
String	getSid() Returns the optional established sid for Oracle databases.
String	getUrl() Returns the URL to the database connection from the dbnames file.
String	getUsername() Returns the current username for the ConnectionPool
boolean	isOpen() Determines if the connection is open or not.
void	open() Opens the connection to the database using the established properties.
void	open(String dbAlias) Open the connection to database
void	open(String dbAlias, String name, String pw) Open the connection to database using name and password given
void	printEncryptedPassword(String dbAlias, String username, String password) Generates a new encrypted password and outputs the result to the console.
boolean	setDb(String dbAlias) Sets the name of the database to use for subsequent connections.
boolean	setDbAlias(String dbAlias) Sets the name of the database to use for subsequent connections.
void	setDbNamesFile(String value) Set the name and path of the database name lookup file.
void	setPassword(String pw) Sets the password for the ConnectionPool and subsequent connections.
void	setSid(String s) Sets the Oracle Sid variable but has no effect on the connection.
void	setUsername(String name) Sets the username for the ConnectionPool and subsequent connections.

Methods inherited from class java.lang.Object

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

Field Detail

ERR_CON

public static final String ERR_CON

The constant in Connector that indicates that the connection to the database could not be opened.

See Also:

Constant Field Values

ERR_DS

public static final String ERR_DS

The constant in Connector that indicates the JNDI datasource was not found.

See Also:

Constant Field Values

ERR_CTX

public static final String ERR_CTX

The constant in Connector that indicates the JNDI context was not found.

See Also:

Constant Field Values

ERR_NC

public static final String ERR_NC

The constant in Connector that indicates that an operation was attempted on a closed or non-existant connection.

See Also:

Constant Field Values

ERR_OPN

public static final String ERR_OPN

The constant in Connector that indicates that an attempt was made to open a connection that was already open.

See Also:

Constant Field Values

ORACLETYPE

public static final int ORACLETYPE

See Also:

Constant Field Values

MYSQLTYPE

public static final int MYSQLTYPE

See Also:

Constant Field Values

OTHERTYPE

public static final int OTHERTYPE

See Also:

Constant Field Values

ERRTYPE

public static final int ERRTYPE

See Also:

Constant Field Values

Constructor Detail

ConnectionPool

public ConnectionPool()

Create a new instance of ConnectionPool.

ConnectionPool

public ConnectionPool(String dbAlias)
               throws SQLException,
                      NamingException

Create a new instance of ConnectionPool and connects to the given database.

Parameters:

dbAlias - the alias name of the database from the database properties file

Throws:

SQLException

NamingException

ConnectionPool

public ConnectionPool(String dbAlias,
                      String name,
                      String pw)
               throws SQLException,
                      NamingException

Create a new instance of Connection pool and connects to the given database using username and password.

Parameters:

dbAlias - the alias name of the database from the database properties file

name - database username

pw - password for the given username

Throws:

SQLException

NamingException

Method Detail

getConnectionPoolInterface

public ConnectionPoolInterface getConnectionPoolInterface()

Obtain the interface to the ConnectionPool

Returns:

ConnectionPoolInterface object

open

public void open(String dbAlias)
          throws SQLException,
                 NamingException

Open the connection to database

Parameters:

dbAlias - the alias name of the database from the database properties file

Throws:

SQLException - thrown if an error occurs while connecting to the database

NamingException - thrown if an error occurs while attempting to read the parameters for the database

See Also:

open(), (String, String, String), (String), connect()

open

public void open(String dbAlias,
                 String name,
                 String pw)
          throws SQLException,
                 NamingException

Open the connection to database using name and password given

Parameters:

dbAlias - the alias name of the database from the database properties file

name - username to connect as

pw - password for the given name

Throws:

SQLException - thrown if an error occurs while connecting to the database

NamingException - thrown if an error occurs while attempting to read the parameters for the database

See Also:

open(), (String, String, String), (String), connect()

open

public void open()
          throws SQLException,
                 NamingException

Opens the connection to the database using the established properties. If none are established the connection will fail.

Throws:

SQLException - thrown if an error occurs while connecting to the database

NamingException - thrown if an error occurs while attempting to read the parameters for the database

See Also:

connect(), (String, String, String), (String), open(String)

setDbNamesFile

public void setDbNamesFile(String value)

Set the name and path of the database name lookup file. The file contains the meta data needed to connect to the target database such as usernames and encrypted passwords. The default location for the file is:
META-INF/dbnames

Parameters:

value - the relative path the file (must be readable by server process)

getUsername

public String getUsername()

Returns the current username for the ConnectionPool

Returns:

the database username currently in use

getPassword

public String getPassword()

Returns the encrypted password for the current user

Returns:

encrypted password

getSid

public String getSid()

Returns the optional established sid for Oracle databases. This parameter is not used by the pool but may be used for other purposes.

Returns:

the sid of the current Oracle database, if any or null if not set

getDriver

public String getDriver()

Returns the driver currently in effect from the dbnames file.

Returns:

the fully qualified driver as defined in the dbnames file (not the JNDI configuration).

getUrl

public String getUrl()

Returns the URL to the database connection from the dbnames file.

Returns:

full URL as defined in the dbnames file (not the JNDI configuration).

setUsername

public void setUsername(String name)

Sets the username for the ConnectionPool and subsequent connections.

Parameters:

name - database username

setPassword

public void setPassword(String pw)

Sets the password for the ConnectionPool and subsequent connections. This password is not saved with the connection meta-data and is only in effect while the object persists. The password should be given in clear text, not encrypted.

Parameters:

pw - clear text password for the current user

setSid

public void setSid(String s)

Sets the Oracle Sid variable but has no effect on the connection.

Parameters:

s - SID to set for this connection

setDb

public boolean setDb(String dbAlias)

Sets the name of the database to use for subsequent connections. The name should be given as the Database alias name, not the JNDI name.

Parameters:

dbAlias - database alias name from the dbnames properties file.

Returns:

true if the operation is successful

See Also:

setDbAlias(String)

setDbAlias

public boolean setDbAlias(String dbAlias)

Sets the name of the database to use for subsequent connections. The name should be given as the Database alias name, not the JNDI name. Same as setDb.

Parameters:

dbAlias - the database name alias to be looked up in the properties file.

Returns:

true if the alias was found, otherwise false.

See Also:

setDb(String)

getDb

public String getDb()

Returns the currently established database name

Returns:

name of the current database

getDbAlias

public String getDbAlias()

Returns the currently established database alias

Returns:

name of the current database alias

getJNDIDbFromAlias

public String getJNDIDbFromAlias(String dbAlias)

Returns the associated JNDI database name for the given alias name

Parameters:

dbAlias - alias name of the database to lookup

Returns:

corresponding JNDI database name

isOpen

public boolean isOpen()

Determines if the connection is open or not.

Returns:

true if the database connection is open, otherwise false

close

public void close()

Closes the current pooled connection. If the connection is not open, no error is thrown.

See Also:

disconnect()

disconnect

public void disconnect()

Closes the current pooled connection. If the connection is not open, no error is thrown.

See Also:

close()

printEncryptedPassword

public void printEncryptedPassword(String dbAlias,
                                   String username,
                                   String password)

Generates a new encrypted password and outputs the result to the console. Use this method to create a new encrypted password for an account so it can be stored in the database properties configuration file.

Parameters:

username - name of the user account to be stored or set

password - associated to the user that will be encrypted

dbAlias - alias to associate with this password

See Also:

generateEncryptedPassword(String,String,String)

generateEncryptedPassword

public String generateEncryptedPassword(String dbAlias,
                                        String name,
                                        String password)

Generates a new encrypted password and returns the result. Use this method to create a new encrypted password for an account so it can be stored in the database properties configuration file.

Parameters:

name - name of the user account to be stored or set

password - associated to the user that will be encrypted

dbAlias - alias to associate with this password

See Also:

generateEncryptedPassword(String,String,String)

connect

public void connect(String dbAlias)
             throws SQLException,
                    NamingException

Connects to the given database.

Parameters:

dbAlias - alias name of the database to connect to

Throws:

SQLException

NamingException

connect

public void connect(String dbAlias,
                    String name,
                    String pw)
             throws SQLException,
                    NamingException

Open the connection to database using name and password given.

Parameters:

dbAlias - the alias name of the database from the database properties file

name - username to connect as

pw - password for the given name

Throws:

SQLException

NamingException

connect

public void connect()
             throws SQLException,
                    NamingException

Opens the connection to the database using the established properties. If none are established the connection will fail.

Throws:

SQLException - thrown if an error occurs while connecting to the database

NamingException - thrown if an error occurs while attempting to read the parameters for the database

See Also:

open(), (String, String, String), (String), open(String)

getConnection

public Connection getConnection()

Returns the active java.sql.Connection object.

Returns:

current Connection object