Programming WebLogic Server J2EE Connectors
|
 |
 |
|
|
 |
 |
Connection Management
The following sections introduce you to the various connection management tasks relating to WebLogic J2EE connectors.
- Configuring Connection Properties
- BEA WebLogic Server Extended Connection Management Features
- Monitoring Connections Using the Console
- Error Logging and Tracing Facility
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 Final Release, 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 Final Release, 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.
Additional ManagedConnections, configured with the capacity-increment element, are created using the known initiating principal and client request information provided by the connection request.
If the connection fails while creating additional ManagedConnections, you can configure Weblogic Server to attempt to recreate it using the connection-creation-retry-frequency-seconds elements. By default, this feature is disabled.
For more information about these elements, see weblogic-ra.xml Deployment Descriptor Elements.
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 max-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. Requests for newly allocated managed connections beyond this limit results in a ResourceAllocationException being returned to the caller.
For more information about these elements, see weblogic-ra.xml Deployment Descriptor Elements.
Reserving Connections
The connection-reserve-timeout-seconds element of the weblogic-ra.xml deployment descriptor specifies the amount of time to wait for a reserved connection call. If the time has been exceeded, the caller encounters an exception. By default, the value of this element is -1, which means that by default this element is set to not wait for a reserved connection.
When a call to reserve a connection is made, WebLogic Server attempts to obtain a connection from the pool of available connections. If none are available, it tries to create new connections using the capacity-increment element and then attempts to obtain a connection from the pool of newly created connections.
If the maximum number has been reached and there are no available connections, WebLogic Server retries until the call times out. The highest-num-waiters element controls the number of clients that can be waiting at any given time for a connection.
The weblogic-ra.xml deployment descriptor also provides a max-num-retries element. If both the connection-reserve-timeout-seconds and max-num-retries element are set, whichever of the two completes first will terminate the reserve call.
For more information about these elements, see weblogic-ra.xml Deployment Descriptor Elements.
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 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-frequency-seconds element in the weblogic-ra.xml descriptor file to identify the amount of time (in seconds) the Connection Pool Management will wait between attempts to reclaim unused Managed Connections. The default value of this element is 900 seconds.
For more information about these elements, see weblogic-ra.xml Deployment Descriptor Elements.
Detecting Connection Leaks
Connection leaks result from faulty application components, such as an Enterprise Javabean (EJB), not doing their job to close a connection after using them. As stated in the J2EE Connector Specification, Version 1.0 Final Release, 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 be exhausted of its available connections, and future connection requests can therefore fail.
WebLogic Server provides two mechanisms for preventing this scenario:
- Leveraging a garbage collector
- Tracking the usage of connection objects and detecting when the usage has become inactive
Garbage Collector Method
WebLogic Server automatically detects connection leaks by leveraging its Java Virtual Machine (JVM) garbage collector mechanism. When an application component terminates and the connections it uses become dereferenced, the garbage collector calls the connection object's finalize() method.
When the garbage collector calls the finalize() method, if WebLogic Server determines the application component has not closed the connection, the server automatically closes the connection by calling the resource adapter's ManagedConnection.cleanup() method; WebLogic Server behaves as it would had it received a CONNECTION_CLOSED event upon proper closure of the application component connection.
Connection Inactivity Detector Method
Because the garbage collector does not behave in a predictable manner and may in fact never be called, WebLogic Server provides a connection inactivity detector method. You configure this in the inactive-connection-timeout-seconds element of the weblogic-ra.xml deployment descriptor. This element identifies the amount of time (in seconds) that a connection handle can remain inactive. This element prevents leaks when an application may have not closed a connection after completing usage. Inactive connections are terminated, without hesitation, as soon as they are detected.
WebLogic Server monitors the usage of connection objects. Periodically, connection objects are tested for inactivity. If their amount of inactivity time exceeds the value specified by the inactive-connection-timeout-seconds element, these inactive connections are immediately terminated.
If the ManagedConnection associated with the connection object has no other active connection objects, WebLogic Server automatically makes the ManagedConnection available for a connection request.
For more information about these elements, see weblogic-ra.xml Deployment Descriptor Elements.
Connection Proxy Wrapper
When a connection request is made, WebLogic Server returns to the client (by way of the resource adapter) a proxy object that wraps the connection object. WebLogic Server uses this proxy to provide features that assist applications using the WebLogic Server implementation of the J2EE Connector Architecture. These features include:
- Connection leak detection capabilities.
- Late XAResource enlistment when a connection request is made before starting a global transaction that uses that connection.
If the connection object returned from a connection request is cast as a Connection class, a ClassCastException can occur. This exception is caused by one of the following:
- The resource adapter performing the cast.
- The client performing the cast during a connection request.
An attempt is made by WebLogic Server to detect the ClassCastException caused by the resource adapter. If the server detects that this cast is failing, it turns off the proxy wrapper feature and proceeds by returning the connection object during a connection request (unwrapped). The server logs a warning message to indicate that the proxy wrapper has been turned off.
When this occurs, connection leak detection and late XAResource enlistment features are also turned off . However, currently no indication of this is given in the Administration Console monitoring features.
WebLogic Server attempts to detect the ClassCastException by acting as a client using container-managed security. This requires the resource adapter to be deployed with security credentials defined.
If the client is performing the cast and receiving a ClassCastException, the customer (client) code can be modified in the following example:
Assume the client is casting the connection object to MyConnection.
Monitoring Connections Using the Console
BEA WebLogic Server implementation of the J2EE Connector Architecture provides you with monitoring capabilities in the WebLogic Server Console that show detected leaks and provides a method for looking up stacks to determine which application(s) is causing the leak. Delete buttons in the Console allow you to dynamically close leaked connections that are identified; the option to delete connections is only available for connections that have exceeded their specified idle time and are safe to delete (in other words, the connection is not involved in a transaction).
The connection-profiling-enabled element of the weblogic-ra.xml file indicates whether or not the connection pool should store the call stacks of where each connection is allocated. If you set this element value to true, you can view this information on active connections through the Console. Also, you can view the stacks for leaked and idle connections, and you can debug components that fail to close connections.
Getting Started
There are two methods for accessing monitoring tools using the Console.
Method One
Method Two
Viewing Leaked Connections
A Connection Leak Profiles column in the Console allows you to view profile information pertaining to leaked connections. This column is not to be confused with the Leaked Connections Detected column, which simply displays the number of leaked connections.
A key difference between these two columns is the Connection Leak Profiles column is controlled by use of the connection-profiling-enabled setting in the weblogic-ra.xml file. By default, this setting is false, so normally the Connection Leak Profiles column will be zero (disabled). However, the Leaked Connections Detected column is always enabled and will always display the number of leaked connections.
There are two methods for viewing leaked connections using the Console.
Method One
Method Two
Viewing Idle Connections
A Connection Idle Profiles column in the Console allows you to view profile information pertaining to idle connections. This column is not to be confused with the Idle Connections Detected column, which simply displays the number of idle connections.
A key difference between these two columns is the Connection Idle Profiles column is controlled by use of the connection-profiling-enabled setting in the weblogic-ra.xml file. By default, this setting is false, so normally the Connection Idle Profiles column will be zero (disabled). However, the Idle Connections Detected column is always enabled and will always display the number of idle connections.
There are two methods for idle connections using the Console.
Method One
Method Two
Error Logging and Tracing Facility
As stated in the J2EE Connector Specification, Version 1.0 Final Release, 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.
The weblogic-ra.xml file descriptor file supports two elements that allow configuration of logging and tracing for resource adapters deployed in WebLogic Server. These elements are as follows:
- The logging-enabled element indicates whether logging is enabled or disabled for a specific ManagedConnectionFactory at deployment time. The default value for this element is false.
- The log-filename element specifies the filename in which to write the logging information that the ManagedConnectionFactory produces.
For more information, see weblogic-ra.xml Deployment Descriptor Elements.
