Administration Console Online Help
![]() |
![]() |
![]() |
![]() |
![]() |
[Attributes and Console Screen Reference for JDBC Data Sources]
This section includes the following subsections:
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.
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.
When not to enable global transactions:
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:
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
name1;name2;name3
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.
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.
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.
See Application-Scoped JDBC Data Sources and Connection Pools.
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:
![]() ![]() |
![]() |
![]() |