BEA Logo BEA WebLogic Server Release 6.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

   BEA WebLogic Server Administration Guide:   Previous topic   |   Next topic   |   Contents   |  Index

 

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:

Overview of JDBC Administration

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:

About the Administrative Console

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

JDBC and WebLogic jDrivers

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.

Transactions (JTA)

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:

Table 14-1 Summary of JDBC Configuration Guidelines

Description/Object

Local Transactions

Distributed Transactions

XA Driver

Distributed Transactions

Non-XA Driver

JDBC driver

  • WebLogic jDriver for Oracle, Microsoft SQL Server, and Informix.

  • Compliant third-party drivers.

  • WebLogic jDriver for Oracle/XA.

  • Compliant third-party drivers.

  • WebLogic jDriver for Oracle, Microsoft SQL Server, and Informix.

  • Compliant third-party drivers.

Data Source

Data Source object
recommended. (If there is no Data Source, use the JDBC API.)

Tx Data Source
required.

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

Drivers Supported for Distributed Transactions

Configuring JDBC Drivers

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.

Table 14-2 WebLogic jDriver for Oracle: Connection Pool Configuration

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.

Table 14-3 WebLogic jDriver for Oracle: Data Source Configuration

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.

Table 14-4 WebLogic jDriver for Microsoft SQL Server: Connection Pool Configuration

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.

Table 14-5 WebLogic jDriver for Microsoft SQL Server: Data Source Configuration

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.

Table 14-6 WebLogic jDriver for Informix: Connection Pool Configuration

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.

Table 14-7 WebLogic jDriver for Informix: Data Source Configuration

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.

Table 14-8 WebLogic jDriver for Oracle/XA: Connection Pool Configuration

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.

Table 14-9 WebLogic jDriver for Oracle/XA: Tx Data Source

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.

Table 14-10 Oracle Thin Driver: Connection Pool Configuration

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;
url=jdbc:oracle:thin:@baybridge:1521:bay817

The following attributes are an example of a Tx Data Source configuration using the Oracle Thin Driver.

Table 14-11 Oracle Thin Driver: Tx Data Source Configuration

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.

Table 14-12 Cloudscape: Connection Pool Configuration

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.

Table 14-13 Cloudscape: Tx Data Source Configuration

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.

Table 14-14 Data Source Properties for WebLogic jDriver for Oracle/XA

Property Name

Type

Description

JDBC 2.0

Op-
tional

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.

Table 14-15 Mapping of xa_open String Names to JDBC 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.

Table 14-16 WebLogic jDriver for Oracle: Connection Pool Configuration

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.

Table 14-17 WebLogic j Driver for Oracle: Tx Data Source Configuration

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.

Table 14-18 Configuration and Assignment Scenarios

Scenario #

Associate. . .

Assign . . . .

Target Description

1

Data Source A with
Connection Pool A

  1. Data Source A to Managed Server 1, and

  2. Connection Pool A to Managed Server 1.

Data Source and Connection Pool assigned to the same target.

2

Data Source B with
Connection Pool B

  1. Data Source B to Cluster X, then

  2. Connection Pool B to Managed Server 2 in Cluster X.

Data Source and Connection assigned to related server/cluster targets.

3

Data Source C with

Connection Pool C

  • Data Source A and Connection Pool A to Managed Server 1.

    - AND -

  • Data Source a to Cluster X; then assign Connection Pool A to Managed Server 2 in Cluster X.

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:

  1. Start the Administration Console.

  2. Locate the Services node in the left pane, then expand the JDBC node.

  3. Select the tab specific to the component you want to configure or manage- Connection Pools, MultiPools, Data Source, or Tx Data Source.

  4. Follow the instructions in the Online Help. For links to the Online Help, see Table 14-19.

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.

Table 14-19 JDBC Configuration Tasks


Task #

JDBC Component/ Task

Description

1

Configure a Connection Pool

On the Configuration tabs, you set the attributes for the Connection Pool, such as Name, URL, and database Properties.

2

Clone a Connection Pool (Optional)

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

Configure a MultiPool (Optional)

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

Configure a Data Source (and Associate with a Pool)

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

Assign a Connection Pool to the Servers/Clusters

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

Assign the MultiPool to Servers or Clusters

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.

Table 14-20 Setting Connectivity-Dynamic

If you want to . . .

Then use the . . .

Create a dynamic Connection Pool

  • Command line- CREATE_POOL, or

  • API-see "Configuring WebLogic JDBC Features" in Programming WebLogic JDBC

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:

Table 14-21 JDBC Management Tasks

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

  1. Select the MultiPools node in the left pane. The MultiPools table displays in the right pane showing all the MultiPools defined in your domain.

  2. Click the Delete icon in the row of the MultiPool you want to delete. A dialog displays in the right pane asking you to confirm your deletion request.

  3. Click Yes to delete the MultiPools. The MultiPool icon under the MultiPools node is deleted.

Delete a Data Source

  1. Select the Data Sources node in the left pane. The Data Sources table displays in the right pane showing all the Data Sources defined in your domain.

  2. Click the Delete icon in the row of the Data Source you want to delete. A dialog displays in the right pane asking you to confirm your deletion request.

  3. Click Yes to delete the Data Source. The Data Source icon under the DataSources node is deleted.

Monitor a Connection Pool

  1. Select the pool in the left pane.

  2. Select the Monitoring tab in the right pane, then select the Monitor All Active Pools link.

Modify an Attribute for a Connection Pool, MultiPool, or DataSource

  1. Select the JDBC object-Connection Pool, MultiPool, or DataSource-in the left pane.

  2. Select the Target tab in the right pane, and unassign the object from each server (move the object from the Chosen column to the Available column.) Then click Apply. This stops the JDBC object-Connection Pool, MultiPool, or DataSource-on the corresponding server(s).

  3. Select the tab you want to modify and change the attribute.

  4. Select the Target tab and reassign the object to the server(s).This starts the JDBC object-Connection Pool, MultiPool, or DataSource-on the corresponding server(s).

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.

Table 14-22 Managing Connection Pools with the Command-Line Interface

If you want to . . .

Then use this command . . .

Disable a Connection Pool

DISABLE_POOL

Enable a Connection Pool that has been disabled

ENABLE_POOL

Delete a Connection Pool

DESTROY_POOL

Confirm if a Connection Pool was created

EXISTS_POOL

Reset a Connection Pool

RESET_POOL

 

Back to Top