| Download Docs | Site Map | Glossary | |
|
|
|||
| bea.com | products | dev2dev | support | askBEA |
|
|
|
|||||||
 |
| e-docs > WebLogic Server > Programming WebLogic Server J2EE Connectors > Connection Management |
|
Programming WebLogic Server J2EE Connectors
|
The following sections introduce you to the various connection management tasks relating to the BEA WebLogic J2EE Connection Management Architecture.
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. 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-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 minutes.
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:
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.
Because the garbage collector does not behave in a predictable manner and may in fact never be called, WebLogic Server provides a second connection leak detection method, the idle timer. The idle timer allows WebLogic Server to track the last time each connection was used. To configure the idle timer for each connection to an EIS, refer to weblogic-ra.xml Deployment Descriptor Elements.
When an application component obtains a connection for usage but is not actively using it, the idle timer starts ticking. As a precaution against closing a connection that is actually active, when a connection has reached its configured maximum limit, WebLogic Server does not automatically close the connection. Instead, WebLogic Server waits to close the connection that has exceeded its idle time until it is absolutely necessary to do so.
If the connection pool for a resource adapter has exceeded its maximum number of allocated connections and there are no allocated connections in the free pool, a connection request fails. At times, connections exist that have been leaked and not been put back on the free pool, even though they are inactive. In this scenario, WebLogic Server closes connections that have exceeded their maximum idle time at the time of a connection request so that the request succeeds.
Monitoring Connections Using the Console
The BEA 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.
There are two methods for accessing monitoring tools using the Console.
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.
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.
To delete leaked or idle connections using the Console:
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:
For more information, see weblogic-ra.xml Deployment Descriptor Elements.
|
|
|
|
||
 |
|
|
 |
 |
 |
|
||
