JDBC DataSources

 

---

Configuring JDBC DataSources

A Data Source object enables JDBC applications to obtain a DBMS connection from a connection pool. Each Data Source object binds to the JNDI tree and points to a connection pool or MultiPool. Applications look up the Data Source on the JNDI tree and then request a connection from the Data Source. Data Source objects can be defined with support for global transactions (enables support for JTA). Support for global transactions is required if your applications use distributed transactions. See When to Enable Global Transactions in a Data Source for more information about using Data Sources and transaction-enabled Data Sources.

When to Enable Global Transactions in a Data Source

If your applications or environment meet any of the following criteria, you should enable global transactions in the Data Source (select Honor Global Transactions during configuration). This is equivalent to using a Tx Data Source in previous releases of WebLogic Server.

• Use the Java Transaction API (JTA)
• Use the EJB container in WebLogic Server to manage transactions
• Include multiple database updates within a single transaction
• Access multiple resources, such as a database and the Java Messaging Service (JMS), during a transaction
• Use the same connection pool on multiple servers

When not to enable global transactions:

• The underlying connection pool uses a non-XA JDBC driver
• You don't plan to use distributed transactions in your applications.
• You plan to use database definition language (DDL) SQL commands through this data source (only applies to some DBMSs or JDBC drivers)

With an EJB architecture, it is common for multiple EJBs that are doing database work to be invoked as part of a single transaction. Without XA, the only way for this to work is if all transaction participants use the exact same database connection. WebLogic Server uses the JTS driver and a TxDataSource to do this behind the scenes without requiring you to explicitly pass the JDBC connection from EJB to EJB. With XA (requires an XA driver), you can use a Tx Data Source in WebLogic Server for distributed transactions with two-phase commit so that EJBs can use a different database connection for each part of the transaction. In either case (with or without XA), you should use a Tx Data Source (a data source with Honor Global Transactions selected).

Read more about Data Sources in Programming WebLogic JDBC.

Emulating Two-Phase Commit

If you need to support distributed transactions with a JDBC connection pool, but there is no available XA-compliant driver for your DBMS, you can select the Emulate Two-Phase Commit for non-XA Driver option for a data source to emulate two-phase commit for the transactions in which the connection pool participates. This option is an advanced option on the Data Source—>Configuration tab.

When you enable the Emulate Two-Phase Commit for non-XA Driver option, The WebLogic server Transaction Manager allows the non-XA resource to enlist in the transaction as the last agent in the transaction. At the end of the Prepare phase of the two-phase commit process, the Transaction Manager issues the commit message (one-phase) to the non-XA resource first. The result of the commit operation on the non-XA resource determines the message to send during the second phase of the transaction, commit or rollback, and determines the outcome of the transaction. XA participants are informed of the outcome in the second phase of the 2PC protocol as usual. See Configuring Non-XA JDBC Drivers for Distributed Transactions for more information.

Note: There are risks to data integrity when using the Emulate Two-Phase Commit for non-XA Driver option. BEA recommends that you use an XA-compliant JDBC driver rather than use this option. Make sure you consider the risks below before enabling this option.

Limitations and Risks

Consider the following limitations and risks before using the Emulate Two-Phase Commit for non-XA Driver option.

Only One Non-XA Participant

Use the Emulate Two-Phase Commit for non-XA Driver option if the JDBC connection is the only non-XA participant in the transaction and there is no XA compliant JDBC driver available. With more than one non-XA resource participating in a transaction and more than one of the non-XA resources are emulating an XA resource, you may see heuristic failures.

If the DataSource is associated with a connection pool that uses an XA-compliant JDBC driver, or if there is only one resource participating in the distributed transaction, then this setting is ignored.

Data Inconsistency Risk

When you use the Emulate Two-Phase Commit for non-XA Driver option, the non-XA participant does not completely participate in the two-phase commit process. During the commit phase, it is possible for server or network failures to cause heuristic completions and possible data inconsistencies. Because the WebLogic Server Transaction Manager presumes abort on resource or communication failure, a network failure after the commit message was sent to a remote non-XA resource will likely cause a heuristic completion: the Transaction Manager will send a roll back message to the XA resources after losing contact with the remote resource, which cannot roll back after committing the changes.

Because of the data integrity risks, the Emulate Two-Phase Commit for non-XA Driver option should only be used in applications that can tolerate heuristic conditions.

Creating and Configuring a JDBC Data Source

1. In the left pane, click to expand the JDBC node.
2. Click the Data Sources node. The Data Sources table displays in the right pane showing all the data sources defined in your domain.
3. Click the Configure a New JDBC Data Source text link. The JDBC Data Source Assistant opens in the right pane.
4. In Step 1, enter the following information:

   Name—Enter a name for this JDBC data source. This name is used in the configuration file (config.xml) and throughout the Administration Console whenever referring to this data source.

   JNDI Name—Enter the JNDI path to where this JDBC data source will be bound.

   Honor Global Transactions—Select this check box (the default) to enable global transactions using this data source. Clear this check box to disable (ignore) global transactions using this data source. In most cases, you should leave the option selected. See When to Enable Global Transactions in a Data Source.

   Click Next to continue.

5. In Step 2, select the connection pool to which the data source will point. Applications get a connection from the underlying connection pool by looking up the data source on the JNDI tree and then requesting a connection from the data source. The pool you select will be used to provide the connection when applications request a connection from this data source.

   Click Next to continue.

6. In Step 3, select the servers and clusters on which you want to create and deploy the new data source. You should deploy the data source to the same servers and clusters on which the underlying connection pool is deployed. By default, the JDBC Data Source Assistant selects the deployment targets on which the underlying connection pool is deployed. In almost all cases, you should accept the default selections.
7. Click Create.

Cloning a JDBC Data Source

1. In the left pane, click to expand the JDBC node.
2. Click Data Sources to view any configured data sources for your domain.
3. Right-click the data source you want to clone and select Clone Data Source name. A dialog displays in the right pane showing the tabs associated with cloning a data source.
4. Enter values in the Name and JNDI Name attribute fields. Optionally, you can modify the other attribute values on the Configuration tab.

   Note: You must specify a new JNDI Name for the new data source. The new data source cannot use the same JNDI Name as the original data source.

   For more information about the attributes on the Configuration tab, see Attributes.

5. Click Clone to create a data source with the attributes you specified on the Configuration tab and with cloned values on all other tabs. The new data source is added under the Data Sources node in the left pane.
6. Optionally, click the remaining tabs for the data source and change the attribute fields or accept the current values. Click Apply to save any changes you make.

Deploying a JDBC Data Source to a Server or Cluster

1. In the left pane, click to expand the JDBC and Data Sources nodes.
2. Click the data source you want to assign. A dialog displays in the right pane showing the tabs with attributes for the data source.
3. Click the Targets tab and select the servers and clusters on which you want to create and deploy the new data source. You should deploy the data source to the same servers and clusters on which the underlying connection pool is deployed. By default, the JDBC Data Source Assistant selects the deployment targets on which the underlying connection pool is deployed.
4. Click Apply to save your changes.

Adding a Note to a Data Source

1. In the left pane, click to expand the JDBC node.
2. Click the Data Sources node to expand it and show the list of data sources defined in your domain.
3. Click the data source to which you want to add a note. A dialog displays in the right pane showing tabs with attributes for the selected object.
4. Click the Notes tab. Type the note in the Notes field.
5. Click Apply to save your changes.

Deleting a Data Source

1. In the left pane, click to expand the JDBC node, then click to expand the Data Sources node to display the list of data sources in the current domain.
2. Right-click the object you want to delete and select Delete object name. A dialog displays in the right pane asking you to confirm your deletion request.
3. Click Yes to delete the data source.

 

---

JDBC Data Source Factories

In WebLogic Server, you can bind a JDBC DataSource resource into the WebLogic Server JNDI tree as a resource factory. You can then map a resource factory reference in the EJB deployment descriptor to an available resource factory in a running WebLogic Server to get a connection from a connection pool.

For details about creating and using a JDBC Data Source factory, see Resource Factories in Programming WebLogic Enterprise JavaBeans.

Creating and Configuring a JDBC Data Source Factory

1. Set up a JDBC connection pool in the Administration Console. See Creating and Configuring a JDBC Connection Pool.
2. In the left pane, click Services and expand JDBC.
3. Select JDBC Data Source Factory and in the right pane click the Configure a New JDBC Data Source Factory text link.
4. Enter values in the Name, User Name, URL, Driver Class Name, and Factory Name, attribute fields.
5. Enter any connection properties in the Properties attribute field.
6. Click Create to create the JDBC Data Source Factory. The new Data Source Factory is added under the JDBC Data source Node in the left pane.
7. Click Apply to save your changes.
8. See Resource Factories in Programming Enterprise Java Beans for more information on using the data source factory.

 

---

Monitoring

There are no monitoring options for data sources in WebLogic Server. However, you can monitor connection pools and transactions. See the following sections for more information:

Monitoring a JDBC Connection Pool

Monitoring Transactions