WebLogic-Specific Configuration Options

The weblogic-ra.xml descriptor file allows you to specify additional configurations for the resource adapter that are specific to the WebLogic platform. For instance, you must use the weblogic-ra.xml descriptor to specify a logical name for the connection factory associated with the J2EE connector, and the JNDI name to which the ConnectionFactory object will be bound:

 XADsWithTx
 myapp.XADsWithTx
 ...

If the resource adapter includes any native libraries needed for establishing a connection to the EIS, you can use the native-libdir element to specify the location of the folder where the native libraries will be copied. Sun's XADataSource connector doesn't require any native libraries, and therefore we can ignore this setting. The weblogic-ra.xml descriptor also holds values for configurable properties defined earlier in the standard ra.xml descriptor file. You need to define a map-config-property element for each property whose default value needs to be overridden. The following XML fragment shows the values we've chosen when using Sun's XADataSource resource adapter to wrap access to Microsoft's JDBC Driver for SQL Server 2000:

 ...
 
 ConnectionURL
 
 jdbc:microsoft:sqlserver://
 
 
 
 ServerName
 10.0.10.10
 
 
 PortNumber
 1433
 
 
 User
 sa
 
 
 Password
 tiger123
 
 
 DatabaseName
 MASTER
 
 
 ClassName
 
 com.microsoft.jdbcx.sqlserver.SQLServerDataSource
 
 
 
 DriverProperties
 
 setSelectMethod#cursor##
 
 
 ...

The value for the DriverProperties setting is specified using some proprietary format for invoking methods on the XADataSource object, and is needed to set custom properties not identified by the JDBC specification. In case of Microsoft's JDBC Driver for SQL Server 2000, if the data source supports distributed transactions, you need to enable server-side cursors by setting SelectMethod=cursor. Remember, all these configurable properties are used by the ConnectionFactory instance when establishing managed connections with the target EIS in this case, the master database on SQL Server 2000.

7.3.1 Managing Connection Pools

The weblogic-ra.xml descriptor file also encapsulates optional settings to configure and automatically maintain the size of the connection pool. A ready pool of connections to the EIS can enhance the performance of your application, especially if creating a managed connection is a costly operation. The configuration settings for this connection pool are almost identical to those that apply to JDBC connection pools, as described earlier in Chapter 5. You need to use the pool-params element within the XML descriptor file to define the various configuration settings that control the behavior of the pool of managed connections. Table 7-1 lists the pool parameters available for the connection factory.

Table 7-1. Configuration settings for the pool of managed connections

Setting	Description	Default
initial-capacity	This option identifies the initial number of connections created when the resource adapter is deployed.	1
max-capacity	This option identifies the maximum number of connections created during the lifetime of the connection pool.	10
capacity-increment	This option identifies the number of connections created when the pool needs to be resized.	1
connection-reserve-timeout-seconds	This option determines the maximum amount of time WebLogic waits while trying to reserve a connection from a pool at maximum capacity. If this timeout is set to -1, WebLogic will not wait.	-1
highest-num-waiters	This option determines the maximum number of connection requests that may wait for an available connection once the pool has reached maximum capacity.	MAX-INT
connection-creation-retry-frequency-seconds	This option determines how often WebLogic should retry to create connections. This setting is used, for example, if a failure is detected while creating additional connections for a pool.	0
shrinking-enabled	If this option is set to false, unused managed connections are not reclaimed by WebLogic.	true
shrink-period-minutes	This option determines the amount of time (in minutes) that the pool manager waits before reclaiming unused connections.	15
inactive-connection-timeout-seconds	This option identifies the amount of time (in seconds) that a connection can remain idle. The setting detects and prevents connection leaks, in case managed connections have not been properly released once their use is complete.	0
connection-profiling-enabled	If this option is set to true, using the Administration Console you can view the call stacks of where each connection was allocated. The same information is available for idle and leaked connections. Typically, you will enable this feature for debugging purposes only.	false

All the configuration settings for controlling the behavior of the connection pool listed in Table 7-1 are optional. You need to set values for specific pool settings only if you need to override the default pool behavior. The following XML fragment shows how to configure the pool parameters for a resource adapter:

 ...
 
 5
 15 
 2
 true
 120
 
 ...

7.3.1.1 Connection reservation

Let's examine how these pool parameters determine the way in which WebLogic services client requests for a managed connection from the resource adapter's pool of connections. Assume a client attempts to reserve a connection from the pool. If there is an available connection in the pool, it is simply returned to the client. If there are no available connections and the pool's size is not yet at max-capacity, WebLogic increases the size of the pool by capacity-increment new connections before returning a connection to the client.

If the pool's size is at max-capacity and cannot grow any further, WebLogic waits for, at most, connection-reserve-timeout-seconds in case a connection does become available. No more than highest-num-waiters requests may wait for a connection to become available. WebLogic will refuse further connection requests while the pool's size is at max-capacity and highest-num-waiters requests are already waiting for a connection to become available. While a client waits for an available connection, WebLogic attempts to reserve connections every connection-creation-retry-frequency-seconds, before the client's request times out.

7.3.1.2 Detecting connection leaks

Ideally, once a J2EE component (servlet, EJB, etc.) has completed using a connection to the EIS, it sends a close( ) connection request that enables WebLogic to perform any necessary cleanup and return the managed connection to the pool. However, a J2EE component may erroneously fail to close a connection. In this case, the configured pool will soon peak to its maximum capacity and run out of available connections to the EIS. WebLogic is able to avoid this situation by incorporating two mechanisms for detecting connection leaks:

Using the garbage collector

Suppose an EJB method fails to close a connection before completion. When the method completes, the connection object will no longer be referenced. The JVM will at some point invoke the garbage collector, which then invokes the object's finalize( ) method. If the connection object hasn't been closed, this method will automatically close the connection by simply invoking the cleanup( ) method on the actual ManagedConnection object, thereby releasing the object as if the user had closed it.

Using an idle timer

A JVM cannot guarantee when an unreferenced object will be garbage-collected, so WebLogic cannot efficiently manage the connection pool simply by relying on the garbage collector. For this reason, WebLogic also supports an idle timer, which tracks the last time a connection was used. The timer starts ticking when a client obtains a connection from the pool but doesn't actively use it. To minimize the chance that the connection is still being used, WebLogic will release only those connections that have exceeded their maximum time limit. Typically, this will happen when the connection pool is at maximum capacity and a client makes another connection request. You can specify the maximum idle time allowed for a managed connection using the inactive-connection-timeout-seconds subelement in the weblogic-ra.xml descriptor file.

By using a combination of these two approaches, the garbage collector and the idle timer, WebLogic is able to provide robust detection of connection leaks and thereby efficiently manage the pool of connections associated with the resource adapter.

7.3.1.3 Connection proxy wrappers

In order to implement the connection pool and transactional features, WebLogic augments the ordinary connection objects with proxy wrappers. Thus, when a client requests a managed connection associated with the resource adapter, WebLogic doesn't return the physical connection to the client, but instead returns the augmented proxy wrapper. Thus, if you cast the object returned from a connection pool to the actual Connection class, a ClassCastException will occur. This can happen either in your client code or in the resource adapter code itself. We recommend that you change your client code to avoid this situation.

When such an exception is thrown in the resource adapter code, or in client code that is using container-managed security, WebLogic tries to catch the exception and return the underlying Connection object instead of the proxy, thereby allowing the cast to succeed. WebLogic also logs a warning message when this happens. However, because the client is no longer using the proxy wrapper itself, WebLogic cannot detect connection leaks or enlist non-XA connectors in distributed transactions. Even though the Administration Console lets you monitor deployed resource adapters and associated connections, it provides no indication of which connections are proxy objects and which connections are unwrapped objects.

7.3.2 Error Logging and Tracing

Every ManagedConnectionFactory instance or ManagedConnection object supports the getLogWriter( ) and setLogWriter( ) methods, which provide error-logging and tracing facility for the resource adapter. The weblogic-ra.xml descriptor file provides two configuration settings that deal with error logging for a resource adapter deployed to WebLogic Server:

• A logging-enabled element that indicates whether logging is enabled for the connection factory.
• A log-filename element that specifies the location of the file to which all log messages generated by the resource adapter are written. This option needs to be supplied only if the logging-enabled element has been set to true.

The following XML fragment shows how to enable error logging for a resource adapter:

 ...
 true
 logs/eis.log
 ...

By default, error logging and tracing is disabled for the connection factory.

7.3.3 Secure Access

All resources within WebLogic can be protected by a security policy, as explained in Chapter 17. Resource adapters are no exception, and WebLogic insists that only authenticated and authorized users are permitted to use them. This security has to be applied at two levels. You need to define which calling principals are permitted to use the resource, and which principals the resource should run under when communicating with the EIS.

This section shows how WebLogic allows you to set up secure access to the underlying EIS using the resource adapter as the conduit. We look at the various sign-on and authentication mechanisms supported by WebLogic, and at how to map WebLogic users to credentials of a valid user on the remote EIS.

7.3.3.1 Sign-on mechanisms

WebLogic's JCA framework supports two sign-on mechanisms:

Application-managed sign-on

Here, the client component is responsible for providing the credentials when it attempts to obtain a connection from the resource adapter. WebLogic simply passes these credentials on to the resource adapter.

Container-managed sign-on

Here, the client component doesn't offer any security information. Instead, WebLogic provides the security information based on the client initiating the call, and a mapping between the calling and resource principals. This mapping is made using the Administration Console, and stored along with other security data in WebLogic's embedded LDAP server.

Once WebLogic has determined the resource principal information, it presents these credentials to the J2EE connector as a Java Authentication and Authorization Service (JAAS) Subject.

7.3.3.2 Mapping WebLogic users to resource principals

A security mapping is a mapping between WebLogic users (also known as initiating principals) and resource principals. For example, in a container-managed environment, a client will have been authenticated as a particular WebLogic user. Now this WebLogic user must be associated with a resource principal (i.e., a user and her credentials) that has access to the EIS. This security mapping can be configured only for resource adapters already deployed to WebLogic. To access these security mappings for a resource adapter, right-click the desired connector in the left frame of the Administration Console and choose the Define Credential Mappings option.

This lists all the current credential mappings, and also provides the "Configure a new Credential" option to create a new credential mapping. To set up this credential map, you will need to supply the names of the WebLogic user and the associated remote user. After you have created this credential mapping, you should return to the list of all credential maps. Here, you will be able to click the username of each remote user that you have defined and assign a password to the remote user.

For each credential map that you configure, you will need to also specify the password associated with the remote user. Your credential maps are persisted by the security realm implementation, and also will be available the next time you start WebLogic Server.

WebLogic reserves three special local usernames for any resource adapter:

weblogic_ra_initial

If you map this user to a resource principal, the target credentials are used for setting up the initial connections for the connection pool when the resource adapter is deployed. If you haven't mapped this user to a resource principal, WebLogic uses the credentials associated with weblogic_ra_default.

weblogic_ra_anonymous

If you map this user to a resource principal, the target credentials are used when no user is authenticated for the connection request to the resource adapter.

weblogic_ra_default

If you map this user to a resource principal, the target credentials are used when the current runtime principal doesn't match any of the initiating principals defined, or when no user has been authenticated for the connection request and no anonymous credentials have been defined for the anonymous user.

Note that if initial capacity of the connection pool is greater than 0, you should map the weblogic_ra_initial user to a resource principal that is authorized to access the actual EIS.