3 Using DataSource Resource Definitions

This chapter provides information on how to create and use Java EE DataSource resource definitions.

Using Java EE DataSources Resource Definitions
Implementation Considerations When Using DataSource Resource Definitions
Using Data Sources in Clients
Additional Resources

Using Java EE DataSources Resource Definitions

DataSource resources are used to define a set of properties required to identify and access a database through the JDBC API. These properties include information such as the URL of the database server, the name of the database, and the network protocol to use to communicate with the server. DataSource objects are registered with the Java Naming and Directory Interface (JNDI) naming service so that applications can use the JNDI API to access a DataSource object to make a connection with a database.

Prior to Java EE 6, DataSource resources were created administratively as described in "Configuring WebLogic JDBC Resources" in Configuring and Managing JDBC Data Sources for Oracle WebLogic Server. Java EE 6 provides the option to programmatically define DataSource resources for a more flexible and portable method of database connectivity.

The name element uniquely identifies a DataSource and is registered with JNDI. The value specified in the name element begins with a namespace scope. Java EE 6 includes the following scopes:

java:comp—Names in this namespace have per-component visibility.
java:module—Names in this namespace are shared by all components in a module, for example, the EJB components defined in an a ejb-jar.xml file.
java:app—Names in this namespace are shared by all components and modules in an application, for example, the application-client, web, and EJB components in an .ear file.
java:global—Names in this namespace are shared by all the applications in the server.

You can programmatically declare DataSource definitions using one of the following methods:

Creating DataSource Resource Definitions Using Annotations
Creating DataSource Resource Definition Using Deployment Descriptors

Creating DataSource Resource Definitions Using Annotations

The javax.annotation.sql package provides @DataSourceDefinition and @DataSourceDefinitions for defining DataSource resource definitions in application component classes such as application clients, servlets, or Enterprise JavaBeans (EJB).

When the DataSource resource is injected, a DataSource object is created and registered with JNDI. Use annotation elements to configure the DataSource object. You can specify additional Java EE and WebLogic configuration attributes in the properties element of the annotation. See Using WebLogic Configuration Attributes.

Use @DataSourceDefinition to create a single datasource definition. For example:

. . .

@DataSourceDefinition(
name = "java:module/ExampleDS",
     className = "org.apache.derby.jdbc.ClientDataSource",
     portNumber = 1527,
     serverName = "localhost",
     databaseName = "exampleDB",
     user = "examples",
     password = "examples",
     properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"})

@WebServlet("/dataSourceServlet")
public class DataSourceServlet extends HttpServlet {
 
 . . .
 
  @Resource(lookup = "java:module/ExampleDS")

. . .

Use the @DataSourceDefinitions to create multiple datasource definitions. For example:

. . .

@DataSourceDefinitions(
      value = {
 
        @DataSourceDefinition(name = "java:app/env/DS1",
           minPoolSize = 0,
           initialPoolSize = 0,
           className = "org.apache.derby.jdbc.ClientXADataSource",
           portNumber = 1527,
           serverName = "localhost",
           user = "examples",
           password = "examples",
           databaseName = "exampleDB",
           properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"}
                   ),
 
        @DataSourceDefinition(name = "java:comp/env/DS2",
           minPoolSize = 0,
           initialPoolSize = 0,
           className = "org.apache.derby.jdbc.ClientDataSource",
           portNumber = 1527,
           serverName = "localhost",
           user = "examples",
           password = "examples",
           databaseName = "examplesDB",
           properties={"create=true", "weblogic.TestTableName=SQL SELECT 1 FROM SYS.SYSTABLES"}
        )
      }
   )

. . .

For a complete example, see the "Creating a DataSource using the @DataSourceDefinition Annotation" in the WebLogic Server Code Examples.

Creating DataSource Resource Definition Using Deployment Descriptors

You can create DataSource resource definitions using deployment descriptors in application.xml, application-client.xml, web.xml, and ejb-jar.xml files. For example:

. . .

 <data-source>
     <name>java:module/ExampleDS</name>
     <class-name>org.apache.derby.jdbc.ClientDataSource</class-name>
     <server-name>localhost</server-name>
     <port-number>1527</port-number>
     <database-name>exampleDB</database-name>
     <user>examples</user>
     <password>examples</password>
     <property>
       <name>create</name>
       <value>true</value>
     </property>
     <property>
       <name>weblogic.TestTableName</name>
       <value>SQL SELECT 1 FROM SYS.SYSTABLES</value>
     </property>
   </data-source>
. . .

Implementation Considerations When Using DataSource Resource Definitions

The following sections provide implementation details to consider when creating and using DataSource resource definitions:

Naming Conventions
Mapping the Java EE DataSource Resource Definition to WebLogic Data Source Resources
Using WebLogic Configuration Attributes
Configuring GridLink DataSource Resource Definitions
Additional Considerations

Naming Conventions

This section provides information on Data Source naming conventions:

Note:

Pre-WebLogic Server 12.1.1 and Java EE Data Source naming conventions are compatible. Existing applications do not need to change naming conventions to upgrade from previous releases.

WebLogic Data Source Naming Conventions

The following conventions are used for name Data Sources in releases prior to WebLogic Server 12.1.1:

dsname - The system resource JDBC descriptor (config/jdbc/*-jdbc.xml)
module@dsname - standalone app-scoped JDBC descriptor
application@module@dsname - app-scoped JDBC descriptor in EAR

Java EE Data Source Naming Conventions

The following conventions are used to name Java EE Data Sources:

appname@modulename@componentname@dsname - Component level
appname@modulename@dsname - Module level
appname@dsname - Application level
dsname – Global

Mapping the Java EE DataSource Resource Definition to WebLogic Data Source Resources

Table 3-1 provides information on how to map Java EE DataSource Resource definition elements to WebLogic Server resources.

Table 3-1 Mapping a DataSource Resource Definition to WebLogic Server Resources

DataSourceBean	Default Value	WebLogic Resource
String name()	Required	JDBCDataSourceParamsBean.setJndiName
String className()	Required	JDBCDriverParamsBean.setDriverName
String description()	""	Not Used
String url()	""	JDBCDriverParamsBean.setUrl
String user()	""	Added to JDBCDriverParamsBean.getProperties()
String password()	""	JDBCDriverParamsBean.setPassword
String databaseName()	""	Used to generate URL; added to `properties`
int portNumber()	-1	Used to generate URL; added to `properties`
String serverName()	"localhost"	Used to generate URL; added to `properties`
int isolationLevel()	-1	Sets `desiredtxisolevel` property which WebLogic Server uses to call `Connection.setTransactionIsolation()`
boolean transactional()	true	Used to generate URL
int initialPoolSize()	-1	JDBCConnectionPoolParamsBean.setInitialCapacity
int maxPoolSize()	-1	JDBCConnectionPoolParamsBean.setMaxCapacity
int minPoolSize()	-1	JDBCConnectionPoolParamsBean.setMinCapacity (new)
int maxIdleTime()	-1	JDBCConnectionPoolParamsBean.setShrinkFrequencySeconds
int maxStatements()	-1	JDBCConnectionPoolParamsBean.setStatementCacheSize
String[] properties()	{}	JDBCPropertiesBean
int loginTimeout()	0	Not Used

Using WebLogic Configuration Attributes

The Java EE 6 @DataSourceDefinition provides a basic standard set of configuration attributes. Oracle extends support for WebLogic Server's rich set of configuration attributes by supporting all WebLogic Server proprietary attributes by mapping Weblogic. Attributeproperty values into WebLogic configuration elements. For an example of a DataSource resource definition using WebLogic configuration elements, see Configuring GridLink DataSource Resource Definitions.

Note:

Consider the following limitations when using WebLogic Server proprietary attributes in the property element. WebLogic Server proprietary attributes:

Are not supported with Multi data sources.
Do not overlap @DataSourceDefinition annotation elements. See Mapping the Java EE DataSource Resource Definition to WebLogic Data Source Resources.
Do not include the data source level attributes name and version.

Configuring GridLink DataSource Resource Definitions

A GridLink Data Source is defined by using the following name/value pair within the DataSource resource definition:

FanEnabled is set to true
OnsNodeList is a non-null value. A comma-separate list of ONS daemon listen addresses and ports for receiving ONS-based FAN events. See "Configuring an ONS Client" in Configuring and Managing JDBC Data Sources for Oracle WebLogic Server.

The following is an example of a DataSource resource definition for a GridLink Data Source using deployment descriptors:

. . .

 <data-source>
    <name>java:global/DSD2</name>
    <class-name>oracle.jdbc.OracleDriver</class-name>
    <url>jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=lcr01155-r)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=mydb)))</url>
    <user>lefty123</user>
    <password>welcome1</password>
    <property><name>weblogic.CapacityIncrement</name><value>2</value></property>
 <property><name>weblogic.HighestNumWaiters</name><value>2147483647</value></property>
    <property><name>weblogic.ConnectionCreationRetryFrequencySeconds</name><value>0</value></property>
    <property><name>weblogic.ConnectionReserveTimeoutSeconds</name><value>10</value></property>
    <property><name>weblogic.TestFrequencySeconds</name><value>120</value></property>
    <property><name>weblogic.TestConnectionsOnReserve</name><value>false</value></property>
    <property><name>weblogic.ProfileHarvestFrequencySeconds</name><value>300</value></property>
    <property><name>weblogic.IgnoreInUseConnectionsEnabled</name><value>true</value></property>
    <property><name>weblogic.InactiveConnectionTimeoutSeconds</name><value>0</value></property>
    <property><name>weblogic.TestTableName</name><value></value></property>
    <property><name>weblogic.LoginDelaySeconds</name><value>0</value></property>
    <property><name>weblogic.InitSql</name><value></value></property>
    <property><name>weblogic.StatementCacheType</name><value>LRU</value></property>
    <property><name>weblogic.RemoveInfectedConnections</name><value>true</value></property>
    <property><name>weblogic.SecondsToTrustAnIdlePoolConnection</name><value>10</value></property>
    <property><name>weblogic.StatementTimeout</name><value>-1</value></property>
    <property><name>weblogic.ProfileType</name><value>0</value></property>
    <property><name>weblogic.JDBCXADebugLevel</name><value>10</value></property>
    <property><name>weblogic.CredentialMappingEnabled</name><value>false</value></property>
    <property><name>weblogic.DriverInterceptor</name><value></value></property>
    <property><name>weblogic.PinnedToThread</name><value>false</value></property>
    <property><name>weblogic.IdentityBasedConnectionPoolingEnabled</name><value>false</value></property>
    <property><name>weblogic.WrapTypes</name><value>true</value></property>
    <property><name>weblogic.ConnectionLabelingCallback</name><value></value></property>
    <property><name>weblogic.FatalErrorCodes</name><value></value></property>
    <property><name>weblogic.Scope</name><value>Global</value></property>
    <property><name>weblogic.RowPrefetch</name><value>false</value></property>
    <property><name>weblogic.RowPrefetchSize</name><value>48</value></property>
    <property><name>weblogic.StreamChunkSize</name><value>256</value></property>
    <property><name>weblogic.AlgorithmType</name><value>Failover</value></property>
    <property><name>weblogic.ConnectionPoolFailoverCallbackHandler</name><value></value></property>
    <property><name>weblogic.FailoverRequestIfBusy</name><value>false</value></property>
    <property><name>weblogic.GlobalTransactionsProtocol</name><value>OnePhaseCommit</value></property>
    <property><name>weblogic.KeepConnAfterLocalTx</name><value>true</value></property>
    <property><name>weblogic.KeepConnAfterGlobalTx</name><value>false</value></property>
    <property><name>weblogic.UseXaDataSourceInterface</name><value>true</value></property>
    <property><name>weblogic.UsePasswordIndirection</name><value>false</value></property>
    <property><name>weblogic.FanEnabled</name><value>true</value></property>
    <property><name>weblogic.OnsNodeList</name><value>lcr01155-r:6200</value></property>
    <property><name>weblogic.OnsWalletFile</name><value></value></property>
    <property><name>weblogic.OnsWalletPassword</name><value></value></property>
    <property><name>weblogic.OracleEnableJavaNetFastPath</name><value>false</value></property>
    <property><name>weblogic.OracleOptimizeUtf8Conversion</name><value>false</value></property>
    <property><name>weblogic.ConnectionInitializationCallback</name><value></value></property>
    <property><name>weblogic.AffinityPolicy</name><value>Session</value></property>
    <property><name>weblogic.OracleProxySession</name><value>false</value></property>
    <property><name>weblogic.KeepXaConnTillTxComplete</name><value>true</value></property>
    <property><name>weblogic.NeedTxCtxOnClose</name><value>false</value></property>
    <property><name>weblogic.XaEndOnlyOnce</name><value>false</value></property>
    <property><name>weblogic.NewXaConnForCommit</name><value>false</value></property>
    <property><name>weblogic.KeepLogicalConnOpenOnRelease</name><value>false</value></property>
    <property><name>weblogic.ResourceHealthMonitoring</name><value>true</value></property>
    <property><name>weblogic.RecoverOnlyOnce</name><value>false</value></property>
    <property><name>weblogic.XaSetTransactionTimeout</name><value>false</value></property>
    <property><name>weblogic.XaTransactionTimeout</name><value>0</value></property>
    <property><name>weblogic.RollbackLocalTxUponConnClose</name><value>false</value></property>
    <property><name>weblogic.XaRetryDurationSeconds</name><value>0</value></property>
    <property><name>weblogic.XaRetryIntervalSeconds</name><value>60</value></property>
  </data-source>
. . .

For additional information, see "Using GridLink Data Sources" in Configuring and Managing JDBC Data Sources for Oracle WebLogic Server.

Additional Considerations

Consider the following when using a Java EE DataSource resource definition with WebLogic Server:

If an annotation and a descriptor have the same DataSource name in the same scope, the attributes are merged with values specified in the deployment descriptor. The deployment descriptor value takes precedence over values specified in a annotation.
A DataSource is not a module, it is a resource created as part of a module.
A DataSource is not a JDBCSystemResources object associated with a domain and is not in the WebLogic Server configuration bean tree.
You can use the JSR88 API's to view applications that include Java EE 6 Data Sources.

Using Data Sources in Clients

You can implement Java EE Data Sources in a Java EE client. However:

Transactional=true is not supported. The transaction protocol is set to NONE.
Data Sources that are global or application in scope are visible (created) both on the client and the server. This has the downside of using more connections.
No permission checking is performed on a Data Source. Operations such as reserve and shrink can be used on a local Data Source.

Additional Resources

This section provides additional resources for review when implementing DataSource resource definitions:

Section EE.5.17 "DataSource Resource Definition" in the Java EE 6 Specification at http://jcp.org/en/jsr/detail?id=316.
The Java EE 6 Tutorial at http://docs.oracle.com/javaee/6/tutorial/doc/.
WebLogic Server Code Examples.