Data source resource definition in applications

Data source resource definition in applications

Applications can define data sources in annotations or in the deployment descriptor. This topic reviews similarities and compatibility with WebSphere Application Server data sources defined at the server, node, cluster, or cell level. Optional features in data source definition are also discussed.

Standard properties for data source definition

Annotation element Descriptor element Comments
name name JNDI name for the data source. The name must be in one of the java:global, java:app, java:module, or java:comp name spaces.
className class-name Fully qualified class name from the JDBC driver that implements javax.sql.XADataSource, javax.sql.ConnectionPoolDataSource, or javax.sql.DataSource.
databaseName database-name Value is supplied to JDBC driver.
description description Value is supplied to DataSource MBean.
initialPoolSize initial-pool-size Value of property is ignored. In WAS, initial pool size is always 0.
isolationLevel isolation-level Equivalent to WebSphere Application Server data source custom property, webSphereDefaultIsolationLevel. This is a default transaction isolation level for new connections.
loginTimeout login-timeout Value is supplied to JDBC driver.
maxIdleTime max-idle-time Equivalent to WebSphere Application Server connection pooling property, unusedTimeout. This property is ignored in the client container where connection pooling is not provided.
maxPoolSize max-pool-size Equivalent to WebSphere Application Server connection pooling property, maxConnections. This property is ignored in the client container where connection pooling is not provided.
maxStatements max-statements Defines the maximum number of statements for the connection pool. In WAS, each pooled connection has its own statement cache. Consequently, maxStatements is divided (equally, rounding down) between the maxPoolSize for the pool. If maxPoolSize is unlimited, then statement pooling is disabled.
minPoolSize min-pool-size Equivalent to WebSphere Application Server connection pooling property, minConnections. This property is ignored in the client container where connection pooling is not provided.
password password Default password for connection requests that do not specify a password. Consider using an authentication alias instead of hard-coding the user name and password into the application.
portNumber port-number Value is supplied to JDBC driver.
serverName server-name Value is supplied to JDBC driver.
transactional transactional In WAS, the property, transactional, controls whether the connection is enlisted in JTA transactions. When transactional=false, connections are not enlisted in JTA transactions, but we can still run transactions against the database using autocommit=true or connection.commit/rollback with autocommit=false. Equivalent to the opposite of the WAS data source custom property, nonTransactionalDataSource.
url url Value is supplied to the JDBC driver. When URL is specified, databaseName, serverName, portNumber values are ignored.
user user Default user name for connection requests that do not specify a user name. Consider using an authentication alias instead of hard-coding the user name and password into the application.

Vendor properties and custom properties

JDBC driver vendor properties can be included in the data source definition. Most of the WAS custom properties can also be included in the data source definition.

With annotations, this is done through the properties element; for example,
@DataSourceDefinition
(
  name="java:app/env/myDataSource",
  className="org.apache.derby.jdbc.EmbeddedXADataSource40",
  databaseName="myDB",
  properties=
  {
    // Vendor properties for Derby Embedded JDBC driver:
    "createDatabase=create",
    "connectionAttributes=upgrade=true",

    // Custom properties for WAS:
    "connectionTimeout=60",
    "dataStoreHelperClass=com.ibm.websphere.rsadapter.DerbyDataStoreHelper",
    "validateNewConnection=true",
    "validateNewConnectionRetryCount=5"
  },
  serverName=""
)
The following example illustrates how the data source definition is included in the deployment descriptor:
<data-source>
 <name>java:app/env/myDataSource</name>
 <class-name>org.apache.derby.jdbc.EmbeddedXADataSource40</class-name>
 <database-name>myDB</database-name>
 <property><name>createDatabase</name><value>create</value></property>
 <property><name>connectionAttributes</name><value>upgrade=true</value></property>
 <property><name>connectionTimeout</name><value>60</value></property>
 <property><name>dataStoreHelperClass</name><value>com.ibm.websphere.rsadapter.DerbyDataStoreHelper</value></property>
 <property><name>validateNewConnection</name><value>true</value></property>
 <property><name>validateNewConnectionRetryCount</name><value>5</value></property>
 <server-name/>
</data-source>
The following is a list of WAS custom properties that can be configured in this manner:

Connection pooling properties:

agedTimeout
authDataAlias
authMechanismPreference
connectionTimeout
defaultConnectionTypeOverride
globalConnectionTypeOverride
mappingConfigAlias
purgePolicy
reapTime
stuckThreshold
stuckTime
stuckTimerTime
surgeCreationInterval
surgeThreshold
testConnection
testConnectionInterval
XA_RECOVERY_AUTH_ALIAS

Data source custom properties:

beginTranForResultSetScrollingAPIs
beginTranForVendorAPIs
connectionSharing
enableMultithreadedAccessDetection
errorDetectionModel
freeResourcesOnClose
oracleRACXARecoveryDelay (Oracle only)
preTestSQLString
userDefinedErrorMap
validateNewConnection
validateNewConnectionRetryCount
validateNewConnectionRetryInterval
validateNewConnectionTimeout

Resource references

IBM recommends for applications to always use resource references when accessing data sources, which makes it easier for the deployer to override.

Connection sharing

By default, for data source definition, a connection request can share an existing in-use connection if it matches the originally requested settings for that connection (connectionSharing=MatchOriginalRequest). Alternately, connection sharing can be done by matching the connection request against the current state of the connection (connectionSharing=MatchCurrentState).

Life cycle

The life cycle of a data source definition is tied to the life cycle of the applications that define it. Consequently, we can update the application to change the data source definition without needing to restart the server. If multiple applications include the same data source definition, for example, both data source definitions have identical java:global names, identical set of properties configured, and identical values for properties, then all of the applications must be uninstalled before updating the data source definition and reinstalling the applications.

Conflicts between data source definitions

Applications, modules, and components should take care not to define data sources with the same java:global name as another application, because that process makes it impossible for the applications to coexist. Within an application, modules and components should take care not to define data sources with the same java:app name as another module or component. The conflict causes the application installation to fail. Within a module, components should take care not to define data sources with the same java:module name as other components. The conflict causes the application installation to fail. Within the web module, components should take care not to define data sources with the same java:comp name as other components. The conflict causes the application installation to fail.

Annotation element	Descriptor element	Comments
name	name	JNDI name for the data source. The name must be in one of the java:global, java:app, java:module, or java:comp name spaces.
className	class-name	Fully qualified class name from the JDBC driver that implements javax.sql.XADataSource, javax.sql.ConnectionPoolDataSource, or javax.sql.DataSource.
databaseName	database-name	Value is supplied to JDBC driver.
description	description	Value is supplied to DataSource MBean.
initialPoolSize	initial-pool-size	Value of property is ignored. In WAS, initial pool size is always 0.
isolationLevel	isolation-level	Equivalent to WebSphere Application Server data source custom property, webSphereDefaultIsolationLevel. This is a default transaction isolation level for new connections.
loginTimeout	login-timeout	Value is supplied to JDBC driver.
maxIdleTime	max-idle-time	Equivalent to WebSphere Application Server connection pooling property, unusedTimeout. This property is ignored in the client container where connection pooling is not provided.
maxPoolSize	max-pool-size	Equivalent to WebSphere Application Server connection pooling property, maxConnections. This property is ignored in the client container where connection pooling is not provided.
maxStatements	max-statements	Defines the maximum number of statements for the connection pool. In WAS, each pooled connection has its own statement cache. Consequently, maxStatements is divided (equally, rounding down) between the maxPoolSize for the pool. If maxPoolSize is unlimited, then statement pooling is disabled.
minPoolSize	min-pool-size	Equivalent to WebSphere Application Server connection pooling property, minConnections. This property is ignored in the client container where connection pooling is not provided.
password	password	Default password for connection requests that do not specify a password. Consider using an authentication alias instead of hard-coding the user name and password into the application.
portNumber	port-number	Value is supplied to JDBC driver.
serverName	server-name	Value is supplied to JDBC driver.
transactional	transactional	In WAS, the property, transactional, controls whether the connection is enlisted in JTA transactions. When transactional=false, connections are not enlisted in JTA transactions, but we can still run transactions against the database using autocommit=true or connection.commit/rollback with autocommit=false. Equivalent to the opposite of the WAS data source custom property, nonTransactionalDataSource.
url	url	Value is supplied to the JDBC driver. When URL is specified, databaseName, serverName, portNumber values are ignored.
user	user	Default user name for connection requests that do not specify a user name. Consider using an authentication alias instead of hard-coding the user name and password into the application.