com.ibm.websphere.advanced.cm.factory
Class DataSourceFactory

java.lang.Object
  |
  +--com.ibm.websphere.advanced.cm.factory.DataSourceFactory

public class DataSourceFactory
extends java.lang.Object

DataSourceFactory is the factory used to create WebSphere DataSources programatically. This is the only supported mechanism for creating a DataSource outside of the systems management GUI.

Creating a DataSource requires creating a Properties object, setting the correct properties inside it, and creating the DataSource with the factory. Some properties are allowed on all databases; there are static attributes for each of those on this class. There are also properties that vary based on the database vendor; there are not static attributes for these properties. In the example which follows, a DataSource is created which specifies a description, user, and password which are all DataSource properties which always exist, and databaseName, which DB2 supports:

 java.util.Properties props = new java.util.Properties();
 props.setProperty(DataSourceFactory.NAME, "MyDataSource"); // required
 props.setProperty(DataSourceFactory.DATASOURCE_CLASS_NAME, // required
                   "COM.ibm.db2.jdbc.DB2ConnectionPoolDataSource");
 props.setProperty(DataSourceFactory.DESCRIPTION, "My great data source");
 props.setProperty(DataSourceFactory.USER, "db2admin");
 props.setProperty(DataSourceFactory.PASSWORD, "db2admin");
 props.setProperty("databaseName", "SAMPLEDB");
 javax.sql.DataSource dataSource = DataSourceFactory.getDataSource(props);
 DataSourceFactory.bindDataSource(dataSource);
 

Note that the NAME and DATASOURCE_CLASS_NAME properties are required. After the DataSource is created, it is bound into JNDI. By default DataSources are placed under the "jdbc" subcontext, but this can be overriden by the bind method which takes a javax.naming.Context parameter.


Inner Class Summary
static class DataSourceFactory.ResourceReferenceObjectFactory
          A javax.naming.spi.ObjectFactory implementation for re-constituting data source references that are looked up in JNDI name space.
 
Field Summary
static java.lang.String CONN_TIMEOUT
          Specifies the maximum number of seconds that an application will wait for a connection from the pool before timing out and throwing a ConnectionTimeoutException to the application.
static java.lang.String DATASOURCE_CLASS_NAME
          The name of underlying database-vendor class used to communicate to the database; it must implement javax.sql.ConnectionPoolDataSource or javax.sql.XADataSource This is a required property.
static int DEFAULT_CONN_TIMEOUT
          The default connection timeout in seconds.
static java.lang.String DEFAULT_DATASOURCE_CONTEXT_NAME
          The name of the JNDI subcontext where all DataSources are bound
static java.lang.String DEFAULT_DESCRIPTION
          The default description of the datasource.
static boolean DEFAULT_DISABLE_2PHASE
          The default setting for disabling 2-phase commit.
static boolean DEFAULT_DISABLE_AUTO_CONN_CLEANUP
          The default setting for disabling auto connection cleanup.
static java.util.Hashtable DEFAULT_ERROR_MAP
          The default error map for the datasource.
static int DEFAULT_IDLE_TIMEOUT
          The default idle timeout in seconds.
static int DEFAULT_INFORMIX_LOCK_MODE_WAIT
          The default value for informixLockModeWait.
static int DEFAULT_MAX_POOL_SIZE
          The default maximum number of connections in the connection pool.
static java.lang.String DEFAULT_MERANT_OEM_ID
          The default oemId for Merant.
static int DEFAULT_MIN_POOL_SIZE
          The default minimum number of connections in the connection pool.
static int DEFAULT_ORPHAN_TIMEOUT
          The default orphan timeout in seconds.
static java.lang.String DEFAULT_PASSWORD
          The default password to create connections with.
static int DEFAULT_STATEMENT_CACHE_SIZE
          The default prepared statement cache size.
static java.lang.String DEFAULT_USER
          The default user to create connections with.
static java.lang.String DESCRIPTION
          The description of the datasource.
static java.lang.String DISABLE_2PHASE
          If a datasource supports both 1-phase and 2-phase commit protocols, setting this property to "true" will disable 2-phase commit; by default 2-phase commit is always used with such datasources.
static java.lang.String DISABLE_AUTO_CONN_CLEANUP
          Specifies whether or not the connection will be closed at the end of a transaction.
static java.lang.String ERROR_MAP
          Not to be used by most applications.
static java.lang.String IDLE_TIMEOUT
          Specifies the number of seconds that a connection can remain free in the pool before the connection is marked to be cleansed from the pool.
static java.lang.String INFORMIX_LOCK_MODE_WAIT
          This property is only used for Informix at the moment.
static java.lang.String MAX_POOL_SIZE
          Specifies the maximum number of connections the connection pool can hold.
static java.lang.String MIN_POOL_SIZE
          Specifies the minimum number of connections the connection pool will hold.
static java.lang.String NAME
          The name of the DataSource; used to determine where the DataSource is bound into JNDI.
static java.lang.String OEM_ID
          For Merant only, the oemId to be set on the Connection object.
static java.lang.String ORPHAN_TIMEOUT
          Specifies the number of seconds that an application is allowed to hold an inactive connection.
static java.lang.String PASSWORD
          The password to create connections with if not supplied on the getConnection call; must be set if the user is also set.
static java.lang.String STATEMENT_CACHE_SIZE
          Specifies the number of cached preparedStatements to keep for an entire connection pool.
static java.lang.String USER
          The user to create connections with if not supplied on the getConnection call.
 
Constructor Summary
DataSourceFactory()
           
 
Method Summary
static void bindDataSource(javax.naming.Context ctx, javax.sql.DataSource ds)
          Binds the given DataSource into caller provided JNDI Context.
static void bindDataSource(javax.sql.DataSource ds)
          Binds the given DataSource into the given JNDI Context.
 javax.sql.DataSource createJDBCDataSource(Attributes a)
          Deprecated. As of Websphere Release 4.0 applications should use getDataSource(java.util.Properties) to create a DataSource
 javax.sql.DataSource createJTADataSource(Attributes a)
          Deprecated. As of Websphere Release 4.0 applications should use getDataSource(java.util.Properties) to create a DataSource
static javax.naming.Referenceable getBindableObject(java.util.Properties properties)
          Constructs a representation of a data source that is suitable for binding into a JNDI name space.
static javax.sql.DataSource getDataSource(com.ibm.ejs.cm.CMProperties cmProps)
          Returns a datasource with the properties which are given.
static javax.sql.DataSource getDataSource(java.util.Properties properties)
          Returns a datasource with the properties which are given.
static boolean isJTAEnabled(com.ibm.ejs.cm.CMProperties cmProps)
          Determines if the datasource which is created from the given properties object is JTA-enabled or not.
static boolean isJTAEnabled(java.util.Properties props)
          Determines if the datasource which is created from the given properties object is JTA-enabled or not.
static void rebindDataSource(javax.naming.Context ctx, javax.sql.DataSource ds)
          Rebinds the given DataSource into caller provided JNDI Context.
static void rebindDataSource(javax.sql.DataSource ds)
          Rebinds the given DataSource into the given JNDI Context.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_DATASOURCE_CONTEXT_NAME

public static final java.lang.String DEFAULT_DATASOURCE_CONTEXT_NAME
The name of the JNDI subcontext where all DataSources are bound

NAME

public static final java.lang.String NAME
The name of the DataSource; used to determine where the DataSource is bound into JNDI. This is a required property.

The value of this constant is "name".


DATASOURCE_CLASS_NAME

public static final java.lang.String DATASOURCE_CLASS_NAME
The name of underlying database-vendor class used to communicate to the database; it must implement javax.sql.ConnectionPoolDataSource or javax.sql.XADataSource This is a required property.

The value of this constant is "dataSourceClassName".


DESCRIPTION

public static final java.lang.String DESCRIPTION
The description of the datasource.

The value of this constant is "description".


DEFAULT_DESCRIPTION

public static final java.lang.String DEFAULT_DESCRIPTION
The default description of the datasource.

The value of this constant is null.


MIN_POOL_SIZE

public static final java.lang.String MIN_POOL_SIZE
Specifies the minimum number of connections the connection pool will hold. By default, this value is 1. The minimum pool size can affect the performance of an application. Smaller pools will require less overhead when the demand is low because fewer connections are being held open to the database. On the other hand, when the demand is high, the first applications will experience a slow response because new connections will have to be created if all others in the pool are in use.

The value of this constant is "minimumPoolSize".


DEFAULT_MIN_POOL_SIZE

public static final int DEFAULT_MIN_POOL_SIZE
The default minimum number of connections in the connection pool.

The value of this constant is 1.


MAX_POOL_SIZE

public static final java.lang.String MAX_POOL_SIZE
Specifies the maximum number of connections the connection pool can hold. By default, this value is 10. The maximum pool size can affect the performance of an application. Larger pools will require more overhead when demand is high because there are more connections open to the database at peak demand. These connections persist until they are idled out of the pool (see DS_IDLE_TIMEOUT for more information). On the other hand, if the maximum is smaller, then there might be longer wait times or possible connection timeout errors during peak times.

The value of this constant is "maximumPoolSize".


DEFAULT_MAX_POOL_SIZE

public static final int DEFAULT_MAX_POOL_SIZE
The default maximum number of connections in the connection pool.

The value of this constant is 10.


CONN_TIMEOUT

public static final java.lang.String CONN_TIMEOUT
Specifies the maximum number of seconds that an application will wait for a connection from the pool before timing out and throwing a ConnectionTimeoutException to the application. The default value is 180 seconds. The ConnectionTimeoutException is something that the application should program to and will be discussed in a later section.

The value of this constant is "connectionTimeout".


DEFAULT_CONN_TIMEOUT

public static final int DEFAULT_CONN_TIMEOUT
The default connection timeout in seconds.

The value of this constant is 180.


IDLE_TIMEOUT

public static final java.lang.String IDLE_TIMEOUT
Specifies the number of seconds that a connection can remain free in the pool before the connection is marked to be cleansed from the pool. The default value is 1800 seconds. Once it is marked for cleanup, it will be cleaned out of the pool after another idleTimeout amount of seconds. Therefore, from the time a connection is returned to the free pool by an application and the time that it actually is removed from the pool and closed can be two times the idleTimeout amount. Connections need to be idled out of the pool because keeping connections open to the database can cause memory problems with the database in some cases. Note that not all connections will be idled out of the pool, even if they are older than the idleTimeout amount. A connection will not be idled if removing this connection would cause the pool to shrink below its minimum value.

The value of this constant is "idleTimeout".


DEFAULT_IDLE_TIMEOUT

public static final int DEFAULT_IDLE_TIMEOUT
The default idle timeout in seconds.

The value of this constant is 1800.


ORPHAN_TIMEOUT

public static final java.lang.String ORPHAN_TIMEOUT
Specifies the number of seconds that an application is allowed to hold an inactive connection. The default is 1800 seconds. If there has been no activity on an allocated connection for longer than the orphan timeout amount, the connection is marked for orphaning. After another orphanTimeout amount of seconds, if the connection still has had no activity, the connection is returned to the pool. If the application tries to use the connection again, it will be thrown a StaleConnectionException. Note that connections that are enlisted in a transaction will not be orphaned.

The value of this constant is "orphanTimeout".


DEFAULT_ORPHAN_TIMEOUT

public static final int DEFAULT_ORPHAN_TIMEOUT
The default orphan timeout in seconds.

The value of this constant is 1800.


STATEMENT_CACHE_SIZE

public static final java.lang.String STATEMENT_CACHE_SIZE
Specifies the number of cached preparedStatements to keep for an entire connection pool. The default value is 100. When a statement is cached, it helps performance as a statement will be retrieved from the cache if a matching statement is found instead of creating a new preparedStatement, which is a more costly operation. The statementCacheSize does not change the programming model, only the performance of the application.

The value of this constant is "statementCacheSize".


DEFAULT_STATEMENT_CACHE_SIZE

public static final int DEFAULT_STATEMENT_CACHE_SIZE
The default prepared statement cache size.

The value of this constant is 100.


USER

public static final java.lang.String USER
The user to create connections with if not supplied on the getConnection call.

The value of this constant is "user".


DEFAULT_USER

public static final java.lang.String DEFAULT_USER
The default user to create connections with.

The value of this constant is null.


PASSWORD

public static final java.lang.String PASSWORD
The password to create connections with if not supplied on the getConnection call; must be set if the user is also set.

The value of this constant is "password".


DEFAULT_PASSWORD

public static final java.lang.String DEFAULT_PASSWORD
The default password to create connections with.

The value of this constant is null.


DISABLE_AUTO_CONN_CLEANUP

public static final java.lang.String DISABLE_AUTO_CONN_CLEANUP
Specifies whether or not the connection will be closed at the end of a transaction. The default is "false", which indicates that when a transaction is completed, WebSphere will close the connection and return it to the pool. This means that any use of the connection after the transaction has ended will result in a StaleConnectionException because the connection will have been closed and returned to the pool. This mechanism is in place to ensure that connections are not held indefinately by the application. If the value is set to "true", then the connection will not be returned to the pool at the end of a transaction by WebSphere. In this case, the application must return the connection to the pool by calling close(). If the application does not close the connection, then the pool will run out of connections for other applications to use.

The value of this constant is "disableAutoConnectionCleanup".


DEFAULT_DISABLE_AUTO_CONN_CLEANUP

public static final boolean DEFAULT_DISABLE_AUTO_CONN_CLEANUP
The default setting for disabling auto connection cleanup.

The value of this constant is false.


ERROR_MAP

public static final java.lang.String ERROR_MAP
Not to be used by most applications. This is only to be used in the case that it is necessary to map an additional SQLException to an internal WebSphere exception. Before using this property, support should be contacted for additional information.

The value of this constant is "errorMap".


DEFAULT_ERROR_MAP

public static final java.util.Hashtable DEFAULT_ERROR_MAP
The default error map for the datasource.

The value of this constant is null.


OEM_ID

public static final java.lang.String OEM_ID
For Merant only, the oemId to be set on the Connection object. This property is ignored if not connecting to a database with a Merant driver.

The value of this constant is "oemId".


DEFAULT_MERANT_OEM_ID

public static final java.lang.String DEFAULT_MERANT_OEM_ID
The default oemId for Merant.

The value of this constant is "WebSphereSequeLinkClient".


INFORMIX_LOCK_MODE_WAIT

public static final java.lang.String INFORMIX_LOCK_MODE_WAIT
This property is only used for Informix at the moment. By default, Informix connections will not wait for a lock. If the resource the connection wants is locked, Informix will immediately throw an error. There is a way to change the behavior, but only on a per connection basis. Setting this property will allow users to define how long they'd like all the connections in an Informix DataSource Connection Pool to wait for a lock. This value is measured in seconds and must be either a positive integer, a negative integer, which will enable indefinate waiting or 0, which will disable waiting. Be default, this value is zero, which will enable Informix's default behavior of not waiting at all. If this property is set for any type of datasource other than Informix, it will be ignored.

DEFAULT_INFORMIX_LOCK_MODE_WAIT

public static final int DEFAULT_INFORMIX_LOCK_MODE_WAIT
The default value for informixLockModeWait.

The default value is 0.


DISABLE_2PHASE

public static final java.lang.String DISABLE_2PHASE
If a datasource supports both 1-phase and 2-phase commit protocols, setting this property to "true" will disable 2-phase commit; by default 2-phase commit is always used with such datasources.

The value of this constant is "disable2Phase".


DEFAULT_DISABLE_2PHASE

public static final boolean DEFAULT_DISABLE_2PHASE
The default setting for disabling 2-phase commit.

The value of this constant is false.

Constructor Detail

DataSourceFactory

public DataSourceFactory()
Method Detail

createJDBCDataSource

public javax.sql.DataSource createJDBCDataSource(Attributes a)
Deprecated. As of Websphere Release 4.0 applications should use getDataSource(java.util.Properties) to create a DataSource

Create a DataSource for accessing a JDBC database. The DataSource will have the properties specified in the given Attributes object. DataSources created with the same Attributes will map to the same underlying connection pool, though there is no guarantee that the same DataSource instance will be returned.
Parameters:
a - A properly-initialized Attributes object specifiying the desired properties for the DataSource.
Returns:
A DataSource mapping to a connection pool

createJTADataSource

public javax.sql.DataSource createJTADataSource(Attributes a)
Deprecated. As of Websphere Release 4.0 applications should use getDataSource(java.util.Properties) to create a DataSource

Create a DataSource for accessing a JTA-enabled database. The DataSource will have the properties specified in the given Attributes object. DataSources created with the same Attributes will map to the same underlying connection pool, though there is no guarantee that the same DataSource instance will be returned.
Parameters:
a - A properly-initialized Attributes object specifiying the desired properties for the DataSource.
Returns:
A DataSource mapping to a connection pool

bindDataSource

public static void bindDataSource(javax.sql.DataSource ds)
                           throws javax.naming.NamingException
Binds the given DataSource into the given JNDI Context. A DataSource instance obtained from createJDBCDataSource() or createJTADataSource() is not guaranteed to be suitable for binding directly into JNDI from application code. Applications should use this method to perform the binding instead.
Parameters:
ds - A DataSource instance obtained from createJDBCDataSource() or createJTADataSource().
Throws:
javax.naming.NamingException - bind failed.

bindDataSource

public static void bindDataSource(javax.naming.Context ctx,
                                  javax.sql.DataSource ds)
                           throws javax.naming.NamingException
Binds the given DataSource into caller provided JNDI Context. A DataSource instance obtained from createJDBCDataSource() or createJTADataSource() is not guaranteed to be suitable for binding directly into JNDI from application code. Applications should use this method to perform the binding instead.
Parameters:
ctx - A JNDI binding context.
ds - A DataSource instance obtained from createJDBCDataSource() or createJTADataSource().
Throws:
javax.naming.NamingException - bind failed.

rebindDataSource

public static void rebindDataSource(javax.sql.DataSource ds)
                             throws javax.naming.NamingException
Rebinds the given DataSource into the given JNDI Context. A DataSource instance obtained from createJDBCDataSource() or createJTADataSource() is not guaranteed to be suitable for binding directly into JNDI from application code. Applications should use this method to perform the rebinding instead.
Parameters:
ds - A DataSource instance obtained from createJDBCDataSource() or createJTADataSource().
Throws:
javax.naming.NamingException - rebind failed.

rebindDataSource

public static void rebindDataSource(javax.naming.Context ctx,
                                    javax.sql.DataSource ds)
                             throws javax.naming.NamingException
Rebinds the given DataSource into caller provided JNDI Context. A DataSource instance obtained from createJDBCDataSource() or createJTADataSource() is not guaranteed to be suitable for binding directly into JNDI from application code. Applications should use this method to perform the binding instead.
Parameters:
ctx - A JNDI binding context.
ds - A DataSource instance obtained from createJDBCDataSource() or createJTADataSource().
Throws:
javax.naming.NamingException - rebind failed.

getBindableObject

public static javax.naming.Referenceable getBindableObject(java.util.Properties properties)
Constructs a representation of a data source that is suitable for binding into a JNDI name space.
Parameters:
properties - - a Properties object that describes the attributes of the data source.
Returns:
Object an object that is suitable for binding into JNDI (e.g. a javax.naming.Reference).
See Also:
getDataSource for a list of properties

getDataSource

public static javax.sql.DataSource getDataSource(java.util.Properties properties)
                                          throws java.lang.ClassNotFoundException,
                                                 CMFactoryException
Returns a datasource with the properties which are given. The properties DataSourceFactory.NAME and DataSourceFactory.DATASOURCE_CLASS_NAME are required. If a datasource with the same NAME has already been created in this JVM, it will be returned. If a datasource with the same NAME has not yet been created a new datasource is created and returned.

Note that all applications using the same datasource share a connection pool and so benefit from reusing connections.

Parameters:
cmProps - a set of properties that defines the data source
Returns:
a datasource with the properties specified
Throws:
java.lang.ClassNotFoundException - if the DATASOURCE_CLASS_NAME property cannot be loaded
MissingRequiredPropertyException - if a required property has not been provided
CMFactoryException - if any other problem occurred

getDataSource

public static javax.sql.DataSource getDataSource(com.ibm.ejs.cm.CMProperties cmProps)
                                          throws java.lang.ClassNotFoundException,
                                                 CMFactoryException
Returns a datasource with the properties which are given. The properties DataSourceFactory.NAME and DataSourceFactory.DATASOURCE_CLASS_NAME are required. If a datasource with the same NAME has already been created in this JVM, it will be returned. If a datasource with the same NAME has not yet been created a new datasource is created and returned.

Note that all applications using the same datasource share a connection pool and so benefit from reusing connections.

Parameters:
cmProps - a set of properties that defines the data source
Returns:
a datasource with the properties specified
Throws:
java.lang.ClassNotFoundException - if the DATASOURCE_CLASS_NAME property cannot be loaded
MissingRequiredPropertyException - if a required property has not been provided
CMFactoryException - if any other problem occurred

isJTAEnabled

public static boolean isJTAEnabled(java.util.Properties props)
                            throws java.lang.ClassNotFoundException,
                                   CMFactoryException
Determines if the datasource which is created from the given properties object is JTA-enabled or not.
Parameters:
props - a list of Properties for the datasource
Returns:
true if the datasource is JTA-enabled, false otherwise
Throws:
java.lang.ClassNotFoundException - if the class specified by the CMProperties' dataSourceClassName could not be found
MissingRequiredPropertyException - if a required property is missing
CMFactoryException - if any other CM exception occurs

isJTAEnabled

public static boolean isJTAEnabled(com.ibm.ejs.cm.CMProperties cmProps)
                            throws java.lang.ClassNotFoundException,
                                   CMFactoryException
Determines if the datasource which is created from the given properties object is JTA-enabled or not.
Parameters:
cmProps - a list of CMProperties for the datasource
Returns:
true if the datasource is JTA-enabled, false otherwise
Throws:
java.lang.ClassNotFoundException - if the class specified by the CMProperties' dataSourceClassName could not be found
MissingRequiredPropertyException - if a required property is missing
CMFactoryException - if any other CM exception occurs