Programming WebLogic Resource Adapters
The following sections describe connection management in WebLogic Server resource adapters. For more information on connection management, see Chapter 6, "Connection Management," of the J2CA 1.5 Specification.
One of the requirements of the J2CA 1.5 Specification is the connection management contract. The connection management contract between WebLogic Server and a resource adapter:
The resource adapter's side of the connection management contract is embodied in the resource adapter's Connection
, ConnectionFactory
, ManagedConnection
, and ManagedConnectionFactory
classes.
A J2EE application component uses a public interface called a connection factory to access a connection instance, which the component then uses to connect to the underlying EIS. Examples of connections include database connections and JMS (Java Message Service) connections.
A resource adapter provides connection and connection factory interfaces, acting as a connection factory for EIS connections. For example, thejavax.sql.DataSource and java.sql.Connection interfaces are JDBC-based interfaces for connecting to a relational database.
An application looks up a connection factory instance in the Java Naming and Directory Interface (JNDI) namespace and uses it to obtain EIS connections. See Obtaining the ConnectionFactory (Client-JNDI Interaction).
Version 1.5 resource adapters can be bound in the JNDI tree as independent objects, making them available as system resources in their own right or as message sources for message-driven beans (MDBs). In contrast, version 1.0 resource adapters are identified by their ConnectionFactory
objects bound in the JNDI tree.
In a version 1.5 resource adapter, at deployment time, the ResourceAdapter
Bean (if it exists) is bound into the JNDI tree using the value of the jndi-name element in the weblogic-ra.xml file. As a result, administrators can view resource adapters as single deployable entities, and they can interact with resource adapter capabilities publicly exposed by the resource adapter provider. For more information, see jndi-name in weblogic-ra.xml Schema.
The application assembler or component provider configures the Connection Factory requirements for an application component in the application's deployment descriptor. For example:
res-ref-name: eis/myEIS
res-type: javax.resource.cci.ConnectionFactory
res-auth: Application or Container
The resource adapter deployer provides the configuration information for the resource adapter.
An application looks up a ConnectionFactory
instance in the Java Naming and Directory Interface (JNDI) namespace and uses it to obtain EIS connections. The following events occur when an application in a managed environment obtains a connection to an EIS instance from a Connection Factory, as specified in the res-type variable.
Note: A managed application environment defines an operational environment for a J2EE-based, multi-tier, Web-enabled application that accesses EISes.
ConnectionFactory
instance in the component's environment by using the JNDI interface, as shown in Listing 5-1.//obtain the initial JNDI Naming context
Context initctx = new InitialContext();
// perform JNDI lookup to obtain the connection factory
javax.resource.cci.ConnectionFactory cxf =
(javax.resource.cci.ConnectionFactory)
initctx.lookup(
"
java:comp/env/eis/MyEIS");
javax.resource.cci.Connection cx = cxf.getConnection();
cx.close();
Outbound resource adapters based on the J2CA 1.5 Specification can be configured to have one or more outbound connections, each having its own WebLogic Server-specific authentication and transaction support. You configure outbound connection properties in the ra.xml and weblogic-ra.xml deployment descriptor files.
You use the outbound-resource-adapter element and its subelements in the weblogic-ra.xml deployment descriptor to describe the outbound components of a resource adapter.
You can define outbound connection pools at three levels:
The connection-factory-interface element (a subelement of the connection-definition-group element) serves as a required unique element (a key) to each connection-definition-group. There must be a one-to-one relationship between the connection-definition-interface element in weblogic-ra.xml and the connectiondefinition-interface element in ra.xml.
connection-properties
subelement to specify properties at the instance level too; properties specified at the instance level override those provided at the group and global levels. See connection-instance.The following is an example of a weblogic-ra.xml deployment descriptor that configures multiple outbound connections:
Listing 5-2 weblogic-ra.xml Deployment Descriptor: Multiple Outbound Connections
<?xml version="1.0" ?>
<weblogic-connector xmlns="http://www.bea.com/ns/weblogic/90">
<jndi-name>900eisaNameOfBlackBoxXATx</jndi-name>
<outbound-resource-adapter>
<connection-definition-group>
<connection-factory-interface>javax.sql.DataSource
</connection-factory-interface>
<connection-instance>
<jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME1
</jndi-name>
<connection-properties>
<pool-params>
<initial-capacity>2</initial-capacity>
<max-capacity>10</max-capacity>
<capacity-increment>1</capacity-increment>
<shrinking-enabled>true</shrinking-enabled>
<shrink-frequency-seconds>60</shrink-frequency-seconds>
</pool-params>
<properties>
<property>
<name>ConnectionURL</name>
<value>jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false
</value>
</property>
<property>
<name>XADataSourceName</name>
<value>OracleXAPool</value>
</property>
<property>
<name>TestClassPath</name>
<value>HelloFromsetTestClassPathGoodDay</value>
</property>
<property>
<name>unique_ra_id</name>
<value>eisablackbox-xa.oracle.900</value>
</property>
</properties>
</connection-properties>
</connection-instance>
<connection-instance>
<jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME2
</jndi-name>
<connection-properties>
<pool-params>
<initial-capacity>2</initial-capacity>
<max-capacity>10</max-capacity>
<capacity-increment>1</capacity-increment>
<shrinking-enabled>true</shrinking-enabled>
<shrink-frequency-seconds>60
</shrink-frequency-seconds>
</pool-params>
<properties>
<property>
<name>ConnectionURL</name>
<value>jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false
</value>
</property>
<property>
<name>XADataSourceName</name>
<value>OracleXAPool</value>
</property>
<property>
<name>TestClassPath</name>
<value>HelloFromsetTestClassPathGoodDay</value>
</property>
<property>
<name>unique_ra_id</name>
<value>eisablackbox-xa.oracle.900</value>
</property>
</properties>
</connection-properties>
</connection-instance>
</connection-definition-group>
<connection-definition-group>
<connection-factory-interface>javax.sql.DataSourceCopy
</connection-factory-interface>
<connection-instance>
<jndi-name>eis/900eisaBlackBoxXATxConnectorJNDINAME3</jndi-name>
<connection-properties>
<pool-params>
<initial-capacity>2</initial-capacity>
<max-capacity>10</max-capacity>
<capacity-increment>1</capacity-increment>
<shrinking-enabled>true</shrinking-enabled>
<shrink-frequency-seconds>60</shrink-frequency-seconds>
</pool-params>
<properties>
<property>
<name>ConnectionURL</name>
<value>jdbc:oracle:thin:@bcpdb:1531:bay920;create=true;autocommit=false
</value>
</property>
<property>
<name>XADataSourceName</name>
<value>OracleXAPoolB</value>
</property>
<property>
<name>TestClassPath</name>
<value>HelloFromsetTestClassPathGoodDay</value>
</property>
<property>
<name>unique_ra_id</name>
<value>eisablackbox-xa-two.oracle.900</value>
</property>
</properties>
</connection-properties>
</connection-instance>
</connection-definition-group>
</outbound-resource-adapter>
</weblogic-connector>
The J2CA 1.5 Specification permits you to configure a resource adapter to support inbound message connections. The following are the main steps for configuring an inbound connection:
ActivationSpec
for each supported inbound message type in the ra.xml deployment descriptor. For information about requirements for an ActivationSpec
class, see Chapter 12, "Message Inflow" in the J2CA 1.5 Specification.The following example shows how an inbound connection with two message listener/activation specs could be configured in the ra.xml deployment descriptor:
Listing 5-3 Example of Configuring an Inbound Connection
<inbound-resourceadapter>
<messageadapter>
<messagelistener>
<messagelistener-type>
weblogic.qa.tests.connector.adapters.flex.InboundMsgListener
</messagelistener-type>
<activationspec>
<activationspec-class>
weblogic.qa.tests.connector.adapters.flex.ActivationSpecImpl
</activationspec-class>
</activationspec>
</messagelistener>
<messagelistener>
<messagelistener-type>
weblogic.qa.tests.connector.adapters.flex.ServiceRequestMsgListener
</messagelistener-type>
<activationspec>
<activationspec-class>
weblogic.qa.tests.connector.adapters.flex.ServiceRequestActivationSpec
</activationspec-class>
</activationspec>
</messagelistener>
</messageadapter>
</inbound-resourceadapter>
This section explains how to configure WebLogic Server resource adapter connection pool parameters in the weblogic-ra.xml deployment descriptor. For more details, see weblogic-ra.xml Schema.
Depending on the complexity of the Enterprise Information System (EIS) that the ManagedConnection
is representing, creating ManagedConnections
can be expensive. 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
.
Because no initiating security principal or request context information is known at WebLogic Server startup, you create initial connections using a security subject that you specify in the security element, as described in Configuring Security Identities for Resource Adapters.
As more ManagedConnections
are created, they consume more system resources—such as memory and disk space. Depending on the Enterprise Information System (EIS), this consumption may affect the performance of the overall system. To control the effects of ManagedConnections
on system resources, you can specify a maximum number of allocated ManagedConnections
in the max-capacity element of 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 ManagedConnections
beyond this limit results in a ResourceAllocationException being returned to the caller.
In compliance with the J2CA 1.5 Specification, 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 an 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.
Using the capacity-increment element in the weblogic-ra.xml descriptor file, you can specify a number of additional ManagedConnections
to be created automatically when a match is not found. This feature provides give you the flexibility to control connection pool growth over time and the performance hit on the server each time this growth occurs.
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 the initial capacity or as close to this as possible 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 Manager will wait between attempts to reclaim unused ManagedConnections
. The default value of this element is 900 seconds.
If the maximum number of connections 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.
When a connection is created and fails, the connection is placed on an unavailable list. WebLogic Server attempts to recreate failed connections on the unavailable list. The highest-num-unavailable element controls the number of unavailable connections that can exist on the unavailable list at one time.
To configure WebLogic Server to attempt to recreate a connection that fails while creating additional ManagedConnections
, enable the connection-creation-retry-frequency-seconds element. By default, this feature is disabled.
A connection request contains parameter information. By default, the connector container calls the matchManagedConnections() method on the ManagedConnectionFactory
to match the available connection in the pool to the parameters in the request. The connection that is successfully matched is returned.
It may be that the ManagedConnectionFactory
does not support the call to matchManagedConnections(). If so, the matchManagedConnections() method call throws a javax.resource.NotSupportedException. If the exception is caught, the connector container automatically stops calling the matchManagedConnections() method on the ManagedConnectionFactory
.
You can set the match-connections-supported element to specify whether the resource adapter supports connection matching. By default, this element is set to true and the matchManagedConnections() method is called at least once. If it is set to false, the method call is never made.
If connection matching is not supported, a new resource is created and returned if the maximum number of resources has not been reached; otherwise, the oldest unavailable resource is refreshed and returned.
The test-frequency-seconds element allows you to specify how frequently (in seconds) connections in the pool are tested for viability.
You can set the test-connections-on-create element to enable the testing of connections as they are created. The default value is false
.
You can set the test-connections-on-release element to enable the testing of connections as they are released back into the connection pool. The default value is false
.
You can set the test-connections-on-reserve element to enable the testing of connections as they are reserved from the connection pool. The default value is false
.
The connection proxy wrapper feature is valid only for resource adapters that are created based on the J2EE 1.0 Connector Architecture. 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 the following features:
If the connection object returned from a connection request is cast as a Connection
implementation class (rather than an interface implemented by the Connection
class), a ClassCastException
can occur. This exception is caused by one of the following:
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 unwrapped connection object during a connection request. The server logs a warning message to indicate that proxy generation has been turned off. When this occurs, connection leak detection and late XAResource enlistment features are also turned off.
WebLogic Server attempts to detect the ClassCastException
by performing a test at resource adapter deployment time 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 client code can be modified, as in the following example.
Assume the client is casting the connection object to MyConnection
.
If you know for sure whether or not a connection proxy can be used in the resource adapter, you can avoid a proxy test by explicitly setting the use-connection-proxies element in the WebLogic Server 8.1 version of weblogic-ra.xml to true or false.
Note: WebLogic Server still supports J2CA 1.0 resource adapters. For 1.0 resource adapters, continue to use the WebLogic Server 8.1 deployment descriptors found in weblogic-ra.xml. It contains elements that continue to accommodate 1.0 resource adapters.
If set to true, the proxy test is not performed and connection properties are generated.
If set to false, the proxy test is not performed and connection proxies are generated.
If use-connection-proxies is unspecified, the proxy test is performed and proxies are generated if the test passes. (The test passes if a ClassCastException is not thrown by the resource adapter).
Note: The test cannot detect a ClassCastException caused by the client code.
If a resource adapter's ManagedConnectionFactory
implements the ValidatingManagedConnectionFactory
interface, then the application server can test the validity of existing connections. You can test either a specific outbound connection or the entire pool of outbound connections for a particular ManagedConnectionFactory
. Testing the entire pool results in testing each connection in the pool individually. For more information on this feature, see section 6.5.3.4 "Detecting Invalid Connections" in the J2CA 1.5 Specification.
The following optional elements in the weblogic-ra.xml deployment descriptor allow you to control the testing of connections in the pool.
To test a resource adapter's connection pools:
See Test outbound connections in the console help.