![]() |
![]() |
|
Managing JDBC Connectivity
The following sections provide guidelines for configuring and managing database connectivity through the JDBC components-Data Sources, Connection Pools and MultiPools-for both local and distributed transactions:
The Administration Console provides an interface to the tools that allow you to configure and manage WebLogic Server features, including JDBC (database connectivity with Java). For most JDBC administrative functions, which include creating, managing and monitoring connectivity, systems administrators use the Administrative Console or the command-line interface. Application developers may want to use the JDBC API.
Frequently performed tasks to set and manage connectivity include:
Your primary way to set and manage JDBC connectivity is through the Administration Console. Using the Administration Console, you set connectivity statically prior to starting the server. For more information, see Starting the Administration Console.
In addition to setting connectivity, the Administration Console allows you to manage and monitor established connectivity.
About the Command-Line Interface
The command-line interface provides a way to dynamically create and manage Connection Pools. For information on how to use the command-line interface, see WebLogic Server Command-Line Interface Reference.
About the JDBC API
For information on setting and managing connectivity programatically, see Programming WebLogic JDBC.
Related Information
The JDBC drivers, used locally and in distributed transactions, interface with many WebLogic Server components and information appears in several documents. For example, information about JDBC drivers is included in the documentation sets for JDBC, JTA and WebLogic jDrivers.
Here is a list of additional resources for JDBC, JTA and Administration:
Administration and Management
The following documentation is written primarily for application developers. Systems Administrators may want to read the introductory material as a supplement to the material in this document.
The following documentation is written primarily for application developers. Systems Administrators may want to read the following as supplements to the material in this section.
JDBC Components-Connection Pools, Data Sources, and MultiPools
The following sections provide a brief overview of the JDBC connectivity components-Connection Pools, MultiPools, and Data Sources:
Connection Pools
A Connection Pool contains named groups of JDBC connections that are created when the Connection Pool is registered, usually when starting up WebLogic Server. Your application borrows a connection from the pool, uses it, then returns it to the pool by closing it. Read more about Connection Pools in Programming WebLogic JDBC at
All of the settings you make with the Administration Console are static; that is, all settings are made before WebLogic Server starts. You can create dynamic Connection Pools-after the server starts-using the command line (see WebLogic Server Command-Line Interface Reference) or programatically using the API (see Creating a Dynamic Connection Pool in Programming WebLogic JDBC).
MultiPools
Used in local (non distributed) transactions on single-server WebLogic Server configurations, MultiPools aid in either:
All of the connections in a particular Connection Pool are identical; that is, they are attached to a single database. The Connection Pools within a MultiPool may, however, be associated with different DBMS. Read more about MultiPools in Programming WebLogic JDBC#programming008.
Data Sources
A Data Source object enables JDBC clients to obtain a DBMS connection. Each Data Source object points to a Connection Pool or MultiPool. Data Source objects can be defined with or without JTA, which provides support for distributed transactions. Read more about Data Sources in Programming WebLogic JDBC.
Note: Tx Data Sources cannot point to MultiPools, only Connection Pools, because MultiPools are not supported in distributed transactions.
JDBC Configuration Guidelines for Connection Pools, MultiPools and DataSources
This section describes JDBC configuration guidelines for local and distributed transactions.
Overview of JDBC Configuration
To set up JDBC connectivity, you configure Connection Pools, Data Source objects (always recommended, but optional in some cases), and MultiPools (optional) by defining attributes in the Administration Console and, for dynamic connection pools, at the command line. There are three types of transactions:
The following table describes how to use these objects in local and distributed transactions:
Description/Object |
Local Transactions
|
Distributed Transactions XA Driver |
Distributed Transactions Non-XA Driver |
---|---|---|---|
JDBC driver |
|
|
|
Data Source |
Data Source object |
Tx Data Source |
Tx Data Source required. Set enable two-phase commit=true if more than one resource. See Configuring Non-XA JDBC Drivers for Distributed Transactions. |
Connection Pool |
Requires Data Source object when configuring in the Administration Console. |
Requires TXData Source. |
Requires TXData Source. |
MultiPool |
Connection Pool and Data Source required. Used in single-server configurations only. |
Not supported in distributed transactions. |
Not supported in distributed transactions. |
Note: Distributed transactions use the WebLogic jDriver for Oracle/XA, the transaction mode for WebLogic jDriver for Oracle.
Drivers Supported for Local Transactions
This section explains how to configure drivers for local and distributed transactions.
Configuring JDBC Drivers for Local Transactions
To configure JDBC drivers for local transactions, set up the JDBC Connection Pool as follows:
For more information on WebLogic two-tier JDBC drivers, refer to the BEA documentation for the specific driver you are using: Installing and Using WebLogic jDriver for Oracle, Installing and Using WebLogic jDriver for Microsoft SQL Server, or Installing and Using WebLogic jDriver for Informix. If you are using a third-party driver, refer to Using Third-Party JDBC XA Drivers with WebLogic Server in Programming WebLogic JTA and the vendor-specific documentation. The following tables show sample JDBC Connection Pool and Data Source configurations using the WebLogic jDrivers.
The following table shows a sample Connection Pool configuration using the WebLogic jDriver for Oracle.
Attribute Name |
Attribute Value |
---|---|
Name |
myConnectionPool |
Targets |
myserver |
DriverClassname |
weblogic.jdbc.oci.Driver |
Initial Capacity |
0 |
MaxCapacity |
5 |
CapacityIncrement |
1 |
Properties |
user=scott;server=localdb |
The following table shows a sample Data Source configuration using the WebLogic jDriver for Oracle.
Attribute Name |
Attribute Value |
---|---|
Name |
myDataSource |
Targets |
myserver |
JNDIName |
myconnection |
PoolName |
myConnectionPool |
The following table shows a sample Connection Pool configuration using the WebLogic jDriver for Microsoft SQL Server.
Attribute Name |
Attribute Value |
---|---|
Name |
myConnectionPool |
Targets |
myserver |
DriverClassname |
weblogic.jdbc.mssqlserver4.Driver |
Initial Capacity |
0 |
MaxCapacity |
5 |
CapacityIncrement |
1 |
Properties |
user=sa;password=secret;db=pubs;server=myHost:1433;appname=MyApplication;hostname=myhostName |
The following table shows a sample Data Source configuration using the WebLogic jDriver for Microsoft SQL Server.
Attribute Name |
Attribute Value |
---|---|
Name |
myDataSource |
Targets |
myserver |
JNDIName |
myconnection |
PoolName |
myConnectionPool |
The following table shows a sample Connection Pool configuration using the WebLogic jDriver for Informix.
Attribute Name |
Attribute Value |
---|---|
Name |
myConnectionPool |
Targets |
myserver |
DriverClassname |
weblogic.jdbc.informix4.Driver |
Initial Capacity |
0 |
MaxCapacity |
5 |
CapacityIncrement |
1 |
Properties |
user=informix;password=secret;server=myDBHost;port=1493;db=myDB |
The following table shows a sample Data Source configuration using the WebLogic jDriver for Informix.
Attribute Name |
Attribute Value |
---|---|
Name |
myDataSource |
Targets |
myserver |
JNDIName |
myconnection |
PoolName |
myConnectionPool |
Configuring XA JDBC Drivers for Distributed Transactions
To allow XA JDBC drivers to participate in distributed transactions, configure the JDBC Connection Pool as follows:
The following attributes are an example of a JDBC Connection Pool configuration using the WebLogic jDriver for Oracle in XA mode.
Attribute Name |
Attribute Value |
---|---|
Name |
fundsXferAppPool |
Targets |
myserver |
DriverClassname |
weblogic.jdbc.oci.xa.XADataSource |
Initial Capacity |
0 |
MaxCapacity |
5 |
CapacityIncrement |
1 |
Properties |
user=scott;password=tiger;server=localdb |
The following attributes are an example of a Tx Data Source configuration using the WebLogic jDriver for Oracle in XA mode.
Attribute Name |
Attribute Value |
---|---|
Name |
fundsXferData Source |
Targets |
myserver |
JNDIName |
myapp.fundsXfer |
PoolName |
fundsXferAppPool |
You can also configure the JDBC Connection Pool to use a third-party vendor's driver in XA mode. In such cases, the data source properties are set via reflection on the XADataSource instance using the JavaBeans design pattern. In other words, for property abc, the XADataSource instance must support get and set methods with the names getAbc and setAbc, respectively.
The following attributes are an example of a JDBC Connection Pool configuration using the Oracle Thin Driver.
Attribute Name |
Attribute Value |
---|---|
Name |
jtaXAPool |
Targets |
myserver,server1 |
DriverClassname |
oracle.jdbc.xa.client.OracleXADataSource |
Initial Capacity |
1 |
MaxCapacity |
20 |
CapacityIncrement |
2 |
Properties |
user=scott;password=tiger; |
The following attributes are an example of a Tx Data Source configuration using the Oracle Thin Driver.
Attribute Name |
Attribute Value |
---|---|
Name |
jtaXADS |
Targets |
myserver,server1 |
JNDIName |
jtaXADS |
PoolName |
jtaXAPool |
Configure the JDBC Connection Pool for use with a Cloudscape driver as follows.
Attribute Name |
Attribute Value |
---|---|
Name |
jtaXAPool |
Targets |
myserver,server1 |
DriverClassname |
COM.cloudscape.core.XADataSource |
Initial Capacity |
1 |
MaxCapacity |
10 |
CapacityIncrement |
2 |
Properties |
databaseName=CloudscapeDB |
SupportsLocalTransaction |
true |
Configure the Tx Data Source for use with a Cloudscape driver as follows.
Attribute Name |
Attribute Value |
---|---|
Name |
jtaZADS |
Targets |
myserver,myserver1 |
JNDIName |
JTAXADS |
PoolName |
jtaXAPool |
WebLogic jDriver for Oracle/XA Data Source Properties
Table 14-14 lists the data source properties supported by the WebLogic jDriver for Oracle. The JDBC 2.0 column indicates whether a specific data source property is a JDBC 2.0 standard data source property (Y) or a WebLogic Server extension to JDBC (N).
The Optional column indicates whether a particular data source property is optional or not. Properties marked with Y* are mapped to the corresponding fields of the Oracle xa_open string (value of the openString property) as listed in Table 14-14. If they are not specified, their default values are taken from the openString property. If they are specified, their values should match those specified in the openString property. If the properties do not match, a SQLException is thrown when you attempt to make an XA connection.
Mandatory properties marked with N* are also mapped to the corresponding fields of the Oracle xa_open string. Specify these properties when specifying the Oracle xa_open string. If they are not specified or if they are specified but do not match, an SQLException is thrown when you attempt to make an XA connection.
Property Names marked with ** are supported, but not used, by WebLogic Server.
Property Name |
Type |
Description |
JDBC 2.0 |
Op- |
Default Value |
---|---|---|---|---|---|
databaseName** |
String |
Name of a particular database on a server. |
Y |
Y |
None |
dataSourceName |
String |
A data source name; used to name an underlying XADataSource. |
Y |
Y |
Connection Pool Name |
description |
String |
Description of this data source. |
Y |
Y |
None |
networkProtocol** |
String |
Network protocol used to communicate with the server. |
Y |
Y |
None |
password |
String |
A database password. |
Y |
N* |
None |
portNumber** |
Int |
Port number at which a server is listening for requests. |
Y |
Y |
None |
roleName** |
String |
The initial SQL role name. |
Y |
Y |
None |
serverName |
String |
Database server name. |
Y |
Y* |
None |
user |
String |
User's account name. |
Y |
N* |
None |
openString |
String |
Oracle's XA open string. |
N |
Y |
None |
oracleXATrace |
String |
Indicates whether XA tracing output is enabled. If enabled (true), a file with a name in the form of xa_poolnamedate.trc is placed in the directory in which the server is started. |
N |
Y |
true |
Table 14-15 lists the mapping between Oracle's xa_open string fields and data source properties.
Oracle xa_open String Field Name |
JDBC 2.0 Data Source Attribute |
Optional |
---|---|---|
acc |
user, password |
N |
sqlnet |
ServerName |
Note also that users must specify Threads=true in Oracle's xa_open string. For complete description of Oracle's xa_open string fields, see your Oracle documentation.
Configuring Non-XA JDBC Drivers for Distributed Transactions
When configuring the JDBC Connection Pool to allow non-XA JDBC drivers to participate with other resources in distributed transactions, specify the Enable Two-Phase Commit attribute for the JDBC Tx Data Source. (This parameter is ignored by resources that support the XAResource interface.) Note that only one non-XA connection pool at a time may participate in a distributed transaction.
Non-XA Driver/Single Resource
If you are using only one non-XA driver and it is the only resource in the transaction, leave the Enable Two-Phase Commit option unselected in the Console (accept the default enableTwoPhaseCommit = false). In this case, the Transaction Manager performs a one-phase optimization.
Non-XA Driver/Multiple Resources
If you are using one non-XA JDBC driver with other XA resources, select Enable Two-Phase Commit in the Console (enableTwoPhaseCommit = true).
When 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 Enable Two-Phase Commit is not selected in the Console (enableTwoPhaseCommit is set to false), the non-XA JDBC resource causes XAResource.prepare() to fail. This mechanism ensures that there is only one participant in the transaction, as commit() throws a SystemException in this case. 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.
The following shows configuration attributes for a sample JDBC Connection Pool using a non-XA JDBC driver.
Attribute Name |
Attribute Value |
---|---|
Name |
fundsXferAppPool |
Targets |
myserver |
DriverClassname |
weblogic.jdbc.oci.Driver |
Initial Capacity |
0 |
MaxCapacity |
5 |
CapacityIncrement |
1 |
Properties |
jdbc:weblogic:oracle |
The following table shows configuration attributes for a sample Tx Data Source using a non-XA JDBC driver.
Attribute Name |
Attribute Value |
---|---|
Name |
fundsXferDataSource |
Targets |
myserver,server1 |
JNDIName |
myapp.fundsXfer |
PoolName |
fundsXferAppPool |
EnableTwoPhaseCommit |
true |
Setting and Managing JDBC Connection Pools, MultiPools, and DataSources
The following sections discuss how to set database connectivity
Once connectivity is established, you use either the Administration Console or command-line interface to manage and monitor connectivity. See Table 14-19 for descriptions of the configuration tasks and links to the Administration Console Online Help.
JDBC Configuration and Assignment
Using the Administration Console, you statically set connectivity by specifying attributes and database properties for the JDBC components-Connection Pools, Data Sources, and MultiPools. See Configuring JDBC Connectivity Using the Administration Console.
Data Sources are associated with Connection Pools or MultiPools ("pool")-each Data Source is commonly associated with a specific pool. The associated Data Source and pool are then assigned to the same target-either the same server or related server/cluster. You cannot assign a Data Source to one server, then the Connection Pool to another.
Refer to the following table for more information.
Scenario # |
Associate. . . |
Assign . . . . |
Target Description |
---|---|---|---|
1 |
Data Source A with |
Data Source and Connection Pool assigned to the same target. |
|
2 |
Data Source B with |
Data Source and Connection assigned to related server/cluster targets. |
|
3 |
Data Source C with Connection Pool C |
- AND -
|
Data Source and Connection Pool assigned as a unit to two different targets. |
(You can assign more than one Data Source to a pool, but there is no practical purpose for this.) You can assign these Data Source/pool combinations to more than one server or cluster, but they must be assigned in combination. For example, you can't assign a DataSource to Managed Server A if its associated Connection Pool is assigned only to Server B.
You can configure dynamic Connection Pools (after the server starts) using the command-line interface. See JDBC Configuration Tasks Using the Command-Line Interface. You can also configure dynamic Connection Pools programatically using the API (see Creating a Dynamic Connection Pool in Programming WebLogic JDBC).
JDBC Configurations for Servers or Clusters
Once you configure and associate the Data Source and Connection Pool (or MultiPool), you then assign each object to the same server or server/cluster. Some common scenarios are as follows:
See Configuring JDBC Connectivity Using the Administration Console for a description of the tasks you perform.
Configuring JDBC Connectivity Using the Administration Console
The Administration Console allows you to configure, manage, and monitor JDBC connectivity. To display the tabs that you use to perform these tasks, complete the following procedure:
The following table shows the connectivity tasks, listed in typical order in which you perform them. You may change the order; just remember you must configure an object before associating or assigning it.
|
JDBC Component/ Task |
Description |
---|---|---|
1 |
On the Configuration tabs, you set the attributes for the Connection Pool, such as Name, URL, and database Properties. |
|
2 |
This task copies a Connection Pool. On the Configuration tabs, you change Name of pool to a unique name; and accept or change the remaining attributes. This a useful feature when you want to have identical pool configurations with different names. For example, you may want to have each database administrator use a certain pool to track individual changes to a database. |
|
3 |
On the MultiPool tabs, you set the attributes for the name and algorithm type, either High Availability or Load Balancing. On the Pool tab, you assign the Connection Pools to this MultiPool. |
|
4 |
Using the Data Source tab, set the attributes for the Data Source, including the Name, JNDI Name, and Pool Name (this associates, or assigns, the Data Source with a specific pool-Connection Pool or MultiPool.) |
|
5 |
Configure a Tx Data Source (and Associate with a Connection Pool) |
Using the Tx Data Source tab, set the attributes for the Tx Data Source, including the Name, JNDI Name, and Connection Pool Name (this associates, or assigns, the Data Source with a specific pool). Note: Do not associate a Tx Data Source with a MultiPool; MultiPools are not supported in distributed transactions. |
6 |
Using the Target tab, you assign the Connection Pool to one or more Servers or Clusters. See Table 14-18 Configuration and Assignment Scenarios. |
|
7 |
Using the Target tab, you assign the configured MultiPool to Servers or Clusters. |
JDBC Configuration Tasks Using the Command-Line Interface
The following table shows what methods you use to create a dynamic Connection Pool.
If you want to . . . |
Then use the . . . |
---|---|
Create a dynamic Connection Pool |
|
For more information, see WebLogic Server Command-Line Interface Reference, and "Creating a Dynamic Connection Pool" in Programming WebLogic JDBC.
Managing and Monitoring Connectivity
Managing connectivity includes enabling, disabling, and deleting the JDBC components once they have been established.
JDBC Management Using the Administration Console
To manage and monitor JDBC connectivity, refer to the following table:
If you want to . . . |
Do this . . . in the Administration Console |
---|---|
Reassign a Connection Pool to a Different Server or Cluster |
Using the instructions in Assign a Connection Pool to the Servers/Clusters, on the Target tab deselect the target (move target from Chosen to Available) and assign a new target. |
Reassign a MultiPool to a Different Cluster |
Using the instructions in Assign the MultiPool to Servers or Clusters, on the Target tab deselect the target (move target from Chosen to Available) and assign a new target. |
Delete a Connection Pool |
See Delete a Connection Pool in the Online Help. |
Delete a MultiPool |
|
Delete a Data Source |
|
Monitor a Connection Pool |
|
Modify an Attribute for a Connection Pool, MultiPool, or DataSource |
|
JDBC Management Using the Command-Line Interface
The following table describes the Connection Pool management using the command-line interface. Select the command for more information.
For information on using the Connection Pool commands, see WebLogic Server Command-Line Interface Reference.
If you want to . . . |
Then use this command . . . |
---|---|
Disable a Connection Pool |
|
Enable a Connection Pool that has been disabled |
|
Delete a Connection Pool |
|
Confirm if a Connection Pool was created |
|
Reset a Connection Pool |
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|