Data source resource definition in applications

In support of the Java™ Enterprise Edition (Java EE) 6 specification, 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

Table 1. Standard properties for data source definition . Use this table to learn about standard properties for data source definitions
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 WebSphere Application Server, 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 WebSphere Application Server, 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 WebSphere Application Server, the property, transactional, controls whether the connection is enlisted in JTA transactions. When transactional=false, connections are not enlisted in JTA transactions, but you can still run transactions against the database using autocommit=true or connection.commit/rollback with autocommit=false. Equivalent to the opposite of the WebSphere Application Server 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 WebSphere Application Server 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 WebSphere Application Server:
    "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 WebSphere Application Server 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

It is recommended 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, you can update your 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.