Administration Console Online Help

JDBC DataSources

[Attributes and Console Screen Reference for JDBC Data Sources]

This section includes the following subsections:

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 creates a Tx Data Source in the config.xml file.

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 Tx Data Source to do this behind the scenes without requiring you to explicitly pass the JDBC connection from EJB to EJB.

If multiple EJBs are participating in a transaction and you do not use an XA JDBC driver for database connections, configure a Data Source with the following options:

Honor Global Transaction selected (creates a Tx Data Source)
Emulate Two-Phase Commit selected
A non-XA connection pool as the Pool Name

This configuration will force the JTS driver to internally use the same database connection for all database work within the same transaction.

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).

Note: Do not create two Tx Data Sources that point to the same connection pool. If a transaction uses two different Tx Data Sources which are both pointed to the same connection pool, you will get an XA_PROTO error when you try to access the second connection.

Read more about Data Sources in Programming WebLogic JDBC.

Note: In previous releases, Data Sources and Tx Data Sources were listed as different object types in the Administration Console. In this release, Data Sources and Tx Data Sources are listed as Data Sources in the Administration console.

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 the Emulate Two-Phase Commit for non-XA Driver option is selected (EnableTwoPhaseCommit is set to true), the non-XA JDBC resource always returns XA_OK during the XAResource.prepare() method call. The resource attempts to commit or roll back its local transaction in response to subsequent XAResource.commit() or XAResource.rollback() calls. If the resource commit or rollback fails, a heuristic error results. Application data may be left in an inconsistent state as a result of a heuristic failure.

When the Emulate Two-Phase Commit for non-XA Driver option is not selected in the Console (EnableTwoPhaseCommit is set to false), the non-XA JDBC resource causes XAResource.prepare() to fail. When there is only one resource participating in a transaction, the one phase optimization bypasses XAResource.prepare(), and the transaction commits successfully in most instances.

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.

This non-XA JDBC driver support is often referred to as the "JTS driver" because WebLogic Server uses the WebLogic JTS Driver internally to support the feature. For more information about the WebLogic JTS Driver, see "Using the WebLogic JTS Driver" in Programming WebLogic JDBC.

Limitations and Risks When Using a Non-XA Driver in Global Transactions

WebLogic Server supports the participation of non-XA JDBC resources in global transactions, but there are limitations that you must consider when designing applications to use such resources. Because a non-XA driver does not adhere to the XA/2PC contracts and only supports one-phase commit and rollback operations, WebLogic Server (through the JTS driver) has to make compromises to allow the resource to participate in a transaction controlled by the Transaction Manager.

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

Heuristic Completions and Data Inconsistency

When Emulate Two-Phase Commit is selected for a non-XA resource, (enableTwoPhaseCommit = true), the prepare phase of the transaction for the non-XA resource always succeeds. Therefore, the non-XA resource does not truly participate in the two-phase commit (2PC) protocol and is susceptible to failures. If a failure occurs in the non-XA resource after the prepare phase, the non-XA resource is likely to roll back the transaction while XA transaction participants will commit the transaction, resulting in a heuristic completion and data inconsistencies.

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

Cannot Recover Pending Transactions

Because a non-XA driver manipulates local database transactions only, there is no concept of a transaction pending state in the database with regard to an external transaction manager. When XAResource.recover() is called on the non-XA resource, it always returns an empty set of Xids (transaction IDs), even though there may be transactions that need to be committed or rolled back. Therefore, applications that use a non-XA resource in a global transaction cannot recover from a system failure and maintain data integrity.

Possible Performance Loss with Non-XA Resources in Multi-Server Configurations

Because WebLogic Server relies on the database local transaction associated with a particular JDBC connection to support non-XA resource participation in a global transaction, when the same JDBC data source is accessed by an application with a global transaction context on multiple WebLogic Server instances, the JTS driver will always route JDBC operations to the first connection established by the application in the transaction. For example, if an application starts a transaction on one server, accesses a non-XA JDBC resource, then makes a remote method invocation (RMI) call to another server and accesses a data source that uses the same underlying JDBC driver, the JTS driver recognizes that the resource has a connection associated with the transaction on another server and sets up an RMI redirection to the actual connection on the first server. All operations on the connection are made on the one connection that was established on the first server. This behavior can result in a performance loss due to the overhead associated with setting up these remote connections and making the RMI calls to the one physical connection.

Only One Non-XA Participant

When a non-XA resource (with Emulate Two-Phase Commit selected) is registered with the WebLogic Server Transaction Manager, it is registered with the name of the class that implements the XAResource interface. Since all non-XA resources with Emulate Two-Phase Commit selected use the JTS driver for the XAResource interface, all non-XA resources (with Emulate Two-Phase Commit selected) that participate in a global transaction are registered with the same name. If you use more than one non-XA resource in a global transaction, you will see naming conflicts or possible heuristic failures.

Creating and Configuring a JDBC Data Source

In the left pane, click to expand the JDBC node.

Click the Data Sources node. The Data Sources table displays in the right pane showing all the data sources defined in your domain.

Click the Configure a New JDBC Data Source text link. The JDBC Data Source Assistant opens in the right pane.

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. You can specify multiple names separated by semi-colons (;).
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.
Emulate Two-Phase Commit for non-XA Driver—Select this check box to enable connections from the associated non-XA connection pool to participate in global transactions by emulating two-phase commit. Use caution when selecting this option. See Limitations and Risks When Using a Non-XA Driver in Global Transactions.
Click Next to continue.

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.

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.

Click Create.

Binding a Data Source to the JNDI Tree with Multiple Names

In WebLogic Server 8.1SP3 and later releases, you can configure a data source so that it binds to the JNDI tree with multiple names. You can use a multi-named data source in place of configuring multiple data sources that point to a single JDBC connection pool. BEA does not support configuring multiple data sources to point to a single JDBC connection pool.

To add JNDI names to an existing data source, add names to the JNDI Name attribute separated by semi-colons. You must either restart the system after making your change or undeploy the data source before making the change, and then redeploy after making the change. Follow the instructions below.

To specify multiple JNDI names for a new data source, follow the instructions in Creating and Configuring a JDBC Data Source.

In the left pane, click to expand the JDBC and Data Sources nodes.

Click the data source you want to change. A dialog displays in the right pane showing the tabs with attributes for the data source.

Click the Targets tab and clear the check boxes for the servers and clusters on which the data source is deployed.

Click Apply to save your changes.

Click the Configuration tab. In JNDI Name, enter the names you want to use to bind the data source to the JDNI tree separated by semi-colons (;). For example:

name1;name2;name3

Click Apply to save your changes.

Click the Targets tab and select the servers and clusters on which you want to re-deploy the data source. You should deploy the data source to the same servers and clusters on which the underlying connection pool is deployed.

Click Apply to save your changes.

The data source configuration in the config.xml file changes to:

<JDBCTxDataSource 
    JNDIName="name1;name2;name3"
    Name="My Data Source" 
    PoolName="demoXAPool" 
    Targets="examplesServer"
    />

Note: Line breaks added for readability.

Cloning a JDBC Data Source

In the left pane, click to expand the JDBC node.

Click Data Sources to view any configured data sources for your domain.

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.

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.

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.

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

In the left pane, click to expand the JDBC and Data Sources nodes.

Click the data source you want to deploy. A dialog displays in the right pane showing the tabs with attributes for the data source.

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.

Click Apply to save your changes.

Adding a Note to a Data Source

In the left pane, click to expand the JDBC node.

Click the Data Sources node to expand it and show the list of data sources defined in your domain.

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.

Click the Notes tab. Type the note in the Notes field.

Click Apply to save your changes.

Deleting a Data Source

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.

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.

Click Yes to delete the data source.

JDBC Data Source Factories

An application-scoped JDBC connection pool relies on a JDBC data source factory to provide default connection pool values. You must create a data source factory before you deploy an enterprise application that includes an application-scoped connection pool. The weblogic-application.xml supplemental deployment descriptor for the application must reference the data source factory by the factory name that you specify in the Administration Console.

For more information about application-scoped JDBC connection pools, see Application-Scoped JDBC Data Sources and Connection Pools.

For more information about resource factories, see Programming WebLogic Enterprise JavaBeans.

Creating and Configuring a JDBC Data Source Factory

In the left pane, click Services and expand JDBC.

Select JDBC Data Source Factory, and in the right pane click the Configure a New JDBC Data Source Factory text link.

Enter values in the attribute fields to use as the default values for application-scoped connection pools that reference this data source factory.

Click Create to create the JDBC Data Source Factory. The new Data Source Factory is added under the Data Source Factories node in the left pane.

Application-Scoped JDBC Data Sources

See Application-Scoped JDBC Data Sources and Connection Pools.

Monitoring Data Sources

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 Connections in a JDBC Connection Pool

Monitoring Transactions