BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT

Connection Management

The following sections introduce you to the various connection management tasks relating to the BEA WebLogic J2EE Connection Management Architecture.

- Error Logging and Tracing Facility

- Configuring Connection Properties

- BEA WebLogic Server Extended Connection Management Features

- Monitoring Connection Pools Using the Console

Error Logging and Tracing Facility

As stated in the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2, one of the requirements for application servers is use of ManagedConnectionFactory.set/getLogWriter to provide an error logging and tracing facility for the resource adapter.

Two elements are provided in the weblogic-ra.xml descriptor file to configure this feature in BEA WebLogic Server:

- The logging-enabled element indicates whether logging is turned on or off. The default value for this element is false.

- The log-filename element specifies the filename in which to write the logging information.

For more information, see weblogic-ra.xml Deployment Descriptor Elements.

Configuring Connection Properties

The ra.xml deployment descriptor file contains a config-property element to declare a single configuration setting for a ManagedConnectionFactory instance. The resource adapter provider typically sets these configuration properties. However, if a configuration property is not set, the person deploying the resource adapter is responsible for providing a value for the property.

WebLogic Server allows you to set configuration properties through the use of the map-config-property element in the weblogic-ra.xml deployment descriptor file. To configure a set of configuration properties for a resource adapter, you specify a map-config-property-name and map-config-property-value pair for each configuration property to declare.

You can also use the map-config-property element to override the values specified in the ra.xml deployment descriptor file. At startup, WebLogic Server compares the values of map-config-property against the values of config-property in the ra.xml file. If the configuration property names match, WebLogic Server uses the map-config-property-value for the corresponding configuration property name.

BEA WebLogic Server Extended Connection Management Features

In addition to the connection management requirements stated in the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2, BEA WebLogic Server provides optional settings and services to configure and automatically maintain the size of the connection pool.

Minimizing the Run-Time Performance Cost Associated with Creating ManagedConnections

Creating ManagedConnections can be expensive depending on the complexity of the Enterprise Information System (EIS) that the ManagedConnection is representing. As a result, you may decide to populate the connection pool with an initial number of ManagedConnections upon startup of WebLogic Server and therefore avoid creating them at run time. You can configure this setting using the initial-capacity element in the weblogic-ra.xml descriptor file. The default value for this element is 1 ManagedConnection.

As stated in the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2, when an application component requests a connection to an EIS through the resource adapter, WebLogic Server first tries to match the type of connection being requested with any existing and available ManagedConnection in the connection pool. However, if a match is not found, a new ManagedConnection may be created to satisfy the connection request.

WebLogic Server provides a setting to allow a number of additional ManagedConnections to be created automatically when a match is not found. This feature provides you with the flexibility to control connection pool growth over time and the performance hit on the server each time this growth occurs. You can configure this setting using the capacity-increment element in the weblogic-ra.xml descriptor file. The default value is 1 ManagedConnection.

Since no initiating security principal or request context information is known at WebLogic Server startup, the initial ManagedConnections, configured with initial-capacity, are created with a default security context containing a default subject and a client request information of null. When additional ManagedConnections—configured with capacity-increment—are created, the first ManagedConnection is created with the known initiating principal and client request information of the connection request. The remaining ManagedConnections—up to the capacity-increment limit—are created using the same default security context used when creating the initial ManagedConnections.

For more information about configuring the default Resource Principal, refer to Security.

Controlling Connection Pool Growth

As more ManagedConnections are created over time, the amount of system resources—such as memory and disk space—that each ManagedConnection consumes increases. Depending on the Enterprise Information System (EIS), this amount may affect the performance of the overall system. To control the effects of ManagedConnections on system resources, WebLogic Server allows you to configure a setting for the allowed maximum number of allocated ManagedConnections.

You configure this setting using the maximum-capacity element in the weblogic-ra.xml descriptor file. If a new ManagedConnection (or more than one ManagedConnection in the case of capacity-increment being greater than one) needs to be created during a connection request, WebLogic Server ensures that no more than the maximum number of allowed ManagedConnections are created. If the maximum number is reached, WebLogic Server attempts to recycle a ManagedConnection from the connection pool. However, if there are no connections to recycle, a warning is logged indicating that the attempt to recycle failed and that the connection request can only be granted for the amount of connections up to the allowed maximum amount. The default value for maximum-capacity is 10 ManagedConnections.

Controlling System Resource Usage

Although setting the maximum number of ManagedConnections prevents the server from becoming overloaded by more allocated ManagedConnections than it can handle, it does not control the efficient amount of system resources needed at any given time. WebLogic Server provides a service that monitors the activity of ManagedConnections in the connection pool during the deployment of a resource adapter. If the usage decreases and remains at this level over a period of time, the size of the connection pool is reduced to an efficient amount necessary to adequately satisfy ongoing connection requests.

This system resource usage service is turned on by default. However, to turn off this service, you can set the shrinking-enabled element in the weblogic-ra.xml descriptor file to false. Use the shrink-period-minutes element in the weblogic-ra.xml descriptor file to set the frequency with which WebLogic Server calculates the need for connection pool size reduction, and if reduction is needed, selectively removes unused ManagedConnections from the pool. The default value of this element is 15 minutes.

Detecting Connection Leaks

As stated in the J2EE Connector Specification, Version 1.0, Proposed Final Draft 2, once the application component has completed its use of the EIS connection, it sends a close connection request. At this point, WebLogic Server is responsible for any necessary cleanup and making the connection available for a future connection request. However, if the application component fails to close the connection, the connection pool can exhausted of its available connections, and future connection requests can therefore fail.

WebLogic Server provides a service to prevent the above scenario by automatically closing a ManagedConnection that has exhausted its usage time. You can set the usage time using the connection-duration-time element in the weblogic-ra.xml descriptor file. You can also use the connection-cleanup-frequency element to set the frequency with which WebLogic Server calculates the usage time of the currently used ManagedConnections and closes those that have exceeded their usage time.

To turn off the connection leak detection service, set the connection-cleanup-frequency element to -1. By default, this service is turned off. The unit used in these element values is seconds.

Monitoring Connection Pools Using the Console

To monitor all connection pool run times for a connector using the BEA WebLogic Server Administrative Console, proceed as follows:

1. Select a connector to monitor in the left pane of the Console.

2. Right-click with your mouse, and select Monitor all Connector Connection Pool Runtimes from the pop-up menu.

   Connection pool run-time information is provided in the right pane for the selected connector.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.