WebLogic Server supports connection management in accordance with Connector Architecture 1.6 and includes support for the connection management contract, a standard model for configuring outbound and inbound connections and connection pooling, support for testing connections, and more.
For more information about the connection management contract, see Chapter 6, Connection Management, of JSR 322: Java EE Connector Architecture 1.6.
Connection Management Contract
The connection management contract is a requirement of Connector Architecture 1.6 and specifies a consistent model for connection management, a set of services that must be provided by the application server to its resource adapters, and more.
The connection management contract between WebLogic Server and a resource adapter:
Provides a consistent application programming model for connection acquisition for both managed and non-managed (two-tier) applications.
Enables a resource adapter to provide a connection factory and connection interfaces based on the common client interface (CCI) specific to the type of resource adapter and EIS. This enables JDBC drivers to be aligned with the Java EE Connector Architecture 1.6 with minimum impact on the existing JDBC APIs.
Enables an application server to provide various services — transactions, security, advanced pooling, error tracing/logging — for its configured set of resource adapters.
Supports connection pooling.
The resource adapter's side of the connection management contract is embodied in the resource adapter's
Connection Factory and Connection
A Java EE 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, the
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).
Resource Adapters Bound in JNDI Tree
Version 1.5 and 1.6 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 or 1.6 resource adapter, at deployment time, the
ResourceAdapter Bean (if it exists) is bound into the JNDI tree using the value of the Example A- element, shown 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 Example A- in weblogic-ra.xml Schema.
Obtaining the ConnectionFactory (Client-JNDI Interaction)
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
A managed application environment defines an operational environment for a Java EE-based, multi-tier, Web-enabled application that accesses EISes.
The application server uses a configured resource adapter to create physical connections to the underlying EIS.
The application component looks up a
ConnectionFactoryinstance in the component's environment by using the JNDI interface, as shown in Example 6-1.
The application component uses the returned connection to access the underlying EIS.
The application component invokes the
getConnectionmethod on the
ConnectionFactoryto obtain an EIS connection. The returned connection instance represents an application level handle to an underlying physical connection. An application component obtains multiple connections by calling the method
getConnectionon the connection factory multiple times:
javax.resource.cci.Connection cx = cxf.getConnection();
After the component finishes with the connection, it closes the connection using the close method on the
If an application component fails to close an allocated connection after its use, that connection is considered an unused connection. The application server manages the cleanup of unused connections.
Example 6-1 JNDI Lookup
//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");
The JNDI name passed in the method
NamingContext.lookup is the same as that specified in the
res-ref-name element of the deployment descriptor. The JNDI lookup results in an instance of type
java.resource.cci.ConnectionFactory as specified in the
Specifying and Obtaining Transaction Support Level
Section 7.13 of JSR 322: Java EE Connector Architecture 1.6 specifies that a resource adapter may determine and classify the level of transaction support it can provide at run time. To have the ability to specify the level of transaction support, a resource adapter's
ManagedConnectionFactory class must implement the
TransactionSupport interface. If this interface is not implemented, the Connector container uses the transaction support specified in the merged result of the resource adapter's
ra.xml file and
JSR 322: Java EE Connector Architecture 1.6 also defines the rules and priorities on the transaction support level determined from the
Connector annotation, and the
WebLogic Server supplements support for obtaining transaction support level by exposing the following two methods on the
ConnectorConnectionPoolRuntimeMBean.getRuntimeTransactionSupport()— Return the real transaction support level in use for this Connector connection pool.
This value may also be viewed in the WebLogic Server Administration Console in the Resource Adapter: Monitoring: Outbound Connection Pools page.
ConnectorConnectionPoolRuntimeMBean.getTransactionSupport()— Returns the static transaction support level, which is configured either in
ra.xmlor using the @Connector annotation, for the resource adapter for this Connector connection pool.
Specifying an Unshareable ManagedConnectionFactory
In most cases, an adapter's
ManagedConnectionFactory supports connection sharing, as defined in section 7.9 of JSR 322: Java EE Connector Architecture 1.6. The specification also says that a connection can be made unshareable by setting
Unshareable in the caller application's deployment descriptor or annotation.
However, it can be inconvenient to define an unshareable resource reference in the caller application. For example, the caller application may perform a look up to a
ConnectionFactory pool from WebLogic's global JNDI directly, but the application does not define unshareable resource references to this pool. WebLogic Server treats such use of the pools as shareable by default. As a result, if an adapter does not support connection sharing, the adapter will not work.
To circumvent this problem, WebLogic Server supports the public annotation
weblogic.connector.extensions.Unshareable. This annotation can be used on a
ManagedConnectionFactory class if the
ManagedConnectionFactory does not support sharing. When such an adapter is deployed, WebLogic Server checks the
ManagedConnectionFactory class and treats the
ManagedConnectionFactory and related pools as unshareable. If you configure a sharable resource reference to this unshareable pool in a Web application or an Enterprise Java Bean, WebLogic Server issues a warning message—but the Web application or the EJB nevertheless treats the pool as unshareable. There is no need to configure anything in
weblogic-ra.xml or in the WebLogic Server Administration Console.
ManagedConnectionFactory is shareable, nothing needs to be changed in the adapter's code. All
ManagedConnectionFactory instances and pools are considered shareable by default, unless the
ManagedConnectionFactory contains an
Configuring Outbound Connections
weblogic-ra.xmldeployment descriptor files.
Connection Pool Configuration Levels
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:
Global - Specify parameters that apply to all outbound connection groups in the resource adapter using the
default-connection-propertieselement. See default-connection-properties.
Group - Specify parameters that apply to all outbound connection instances belonging to a particular connection factory specified in the
ra.xmldeployment descriptor using the
connection-definition-groupelement. A one-to-one correspondence exists from a connection factory in
ra.xmlto a connection definition group in
weblogic-ra.xml. The properties specified in a group override any parameters specified at the global level. See connection-definition-group.
connection-factory-interfaceelement (a subelement of the
connection-definition-groupelement) serves as a required unique element (a key) to each
connection-definition-group. There must be a one-to-one relationship between the
Instance - Under each connection definition group, you can specify connection instances using the
connection-instanceelement of the
weblogic-ra.xmldeployment descriptor. These correspond to the individual connection pools for the resource adapter. You can use the
connection-propertiessubelement 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.
Retrying a Connection Attempt
If an application component attempts to obtain a connection instance from a connection pool using the
getConnection() method on the
ConnectionFactory, but the pool is temporarily suspended, WebLogic Server generates an exception that implements
javax.resource.spi.RetryableException. The application component can use an instance of
RetryableException to determine whether the connection failure is transient.
Isolating, Troubleshooting, and Fixing Outbound Connection Pool Failures Without Redeploying the Adapter
By default, if a resource adapter has multiple outbound connection pools, a failure in any one connection pool causes the entire deployment of the resource adapter to fail. However, the deploy-as-a-whole deployment option is available, which you can set to isolate individual outbound connection pool failures from the resource adapter deployment. Using this deployment option enables you to use the adapter health monitoring feature to identify connection pool failures, which you can troubleshoot and repair without the need to redeploy the resource adapter.
For general information about the resource adapter health monitoring features, see Monitoring Resource Adapter Health. For information about setting the
deploy-as-a-whole element in the
weblogic-ra.xml file, see the following topics:
The following sections explain how to use the deploy-as-a-whole deployment option and how to diagnose and recover from outbound connection pool failures:
Using the Deploy-As-A-Whole Option
To deploy a resource adapter so that the failure of an individual outbound connection pool does not cause the whole adapter deployment to fail, set the
deploy-as-whole element of the
weblogic-ra.xml file to
false (by default, this element is set to
true). For details about setting this deployment option, see Deploying a Resource Adapter Configured with Multiple Outbound Connection Pools.
If the deploy-as-a-whole option is set to
false, note the following:
If there is no error during deployment, the resource adapter deployment succeeds and is placed in an active state, with a health state of HEALTH_OK.
If an error occurs when creating or configuring at least one outbound connection pool, the health state of the adapter deployment is set to HEALTH_CRITICAL.
If any other failure occurs, such as the following, the adapter deployment fails:
An error parsing or validating the
weblogic-ra.xmlfile, or the deployment plan.
An error occurs when creating or configuring the ResourceAdapter or admin object beans.
Any pool-related classes failing to meet basic requirements defined by JSR 322: Java EE Connector Architecture 1.6 that can be detected statically; for example, the adapter's
ManagedConnectionFactoryclass not implementing the required standard interface
Troubleshooting Failed Connection Pools
If a connection pool is in a HEALTH_CRITICAL state, invoking most methods on the
ConnectorConnectionPoolRuntimeMBean, such as
testPool, may simply throw an
IllegalStateException. You can invoke only the following methods, which provide static information and are not affected by connection pool failures:
Shutdownfor failed pools)
getConnectionFactoryClassName()(returns the ConnectionFactoryName of the connection pool)
Note the following:
A resource adapter module's health state may change from HEALTH_OK to HEALTH_CRITICAL after one of the following actions:
Performing a dynamic update.
Performing either a
force resetof outbound connection pools
Stopping then restarting the resource adapter
Redeploying the adapter
If a connection pool is in the HEALTH_CRITICAL state, the
resumeactions on the pool have no effect.
Connection Pool Recovery Steps
Once a connection pool has failed and is in the HEALTH_CRITICAL state, check the failure reason and correct the error. For example, ensure that updated values for the pool's properties are valid and properly assigned.
For most failures that are caused by an incorrect configuration, Oracle recommends taking the following steps:
- Modify the configuration of each failed pool, if necessary.
- Save the new configuration to the adapter's deployment plan.
- Using the updated adapter's deployment plan, perform a dynamic update of the resource adapter.
The preceding steps can recover failed pools without affecting properly functioning and in-use connection pools. During the dynamic update process, all failed connection pools are recreated using the new configuration data, regardless of whether the configuration changes for the pools have been made in the new deployment plan or whether the configuration changes are dynamically updatable. For existing connection pools that are functioning properly, non-dynamic configuration changes are ignored. However, for failed connection pools, the configuration updates go into effect from the dynamic update process.
Other Options for Recovering Failed Connection Pools
As an alternative to performing a dynamic update to recover a failed connection pool, you can try one of the following methods. If the failure is due to causes other than an invalid pool configuration, one of these method might be appropriate:
Reset or force reset the failed connection pool, as described in Reset a Connection Pool.. Depending on the reason for the failure, these actions may or may not recover the failed pool. However, because no connections with failed pools are active, reset and force reset have the same effect. Note the following:
If the pool failure is not caused by an invalid configuration, the pool can potentially be recovered by resetting it, which uses the existing configuration data. For example, if the failure is due to a JNDI conflict, the pool can be recovered if the conflicting object from JNDI tree is removed. Resetting the connection pool would be recommended in this scenario.
If the connection pool has failed due to an invalid configuration, resetting the connection pool is not recommended. Resetting uses the existing deployment plan, or existing deployment descriptor information, which contain the invalid configuration data.
Redeploy the adapter. Note that this action affects all outbound connection pools in the resource adapter, including any that are functioning properly
Stop and then restart the resource adapter. This action also affects all outbound connection pools in the adapter. This method has drawbacks similar to performing a
force resetaction because it also uses the pre-existing configuration data without first performing a dynamic update. In addition, configuration data that has been revised that is not made available by dynamic update is not used. For this reason, stopping and then restarting the resource adapter is not a recommended option for recovering failed connection pools in most cases.
Multiple Outbound Connections Example
Example 6-2 is an example of a
weblogic-ra.xml deployment descriptor that configures multiple outbound connections:
Example 6-2 weblogic-ra.xml Deployment Descriptor: Multiple Outbound Connections
<?xml version="1.0" ?> <weblogic-connector xmlns="http://xmlns.oracle.com/weblogic/weblogic-connector"> <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>
Configuring Inbound Connections
The Java EE Connector Architecture 1.7 permits you to configure a resource adapter to support inbound message connections.
The following are the main steps for configuring an inbound connection:
- Provide a JNDI name for the resource adapter in the
weblogic-ra.xmldeployment descriptor. See Example A- in Table A-1
- Configure a message listener and
ActivationSpecfor each supported inbound message type in the
ra.xmldeployment descriptor. For information about requirements for an
ActivationSpecclass, see Chapter 13, Message Inflow in JSR 322: Java EE Connector Architecture 1.6.
- Within the packaged enterprise application, include a configured EJB message-driven bean (MDB). In the
resource-adapter-jndi-nameelement of the
weblogic-ejb-jar.xmldeployment descriptor, provide the same JNDI name assigned to the resource adapter in the previous step. Setting this value enables the MDB and resource adapter to communicate with each other.
- Configure the security identity to be used by the resource adapter for inbound connections. When messages are received by the resource adapter, work must be performed under a particular security identity. See Configuring Security Identities for Resource Adapters.
- Deploy the resource adapter as discussed in Deploying Applications to Oracle WebLogic Server.
- Deploy the MDB. See Deploying MDBs in Developing Message-Driven Beans for Oracle WebLogic Server and Deploying Applications to Oracle WebLogic Server.
Example 6-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>
Example 6-3 shows how an inbound connection with two message listener/activation specs could be configured in the
ra.xml deployment descriptor:
Configuring Connection Pool Parameters
You configure WebLogic Server resource adapter connection pool parameters in the
weblogic-ra.xml deployment descriptor.
initial-capacity: Setting the Initial Number of ManagedConnections
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
Because no initiating security principal or request context information is known at WebLogic Server startup, a server instance creates initial connections using a security subject by looking up special credential mappings for the initial connection. See Initial Connection: Requires a ManagedConnection from Adapter Without Application's Request.
WebLogic Server uses
Subject if a mapping is not found.
max-capacity: Setting the Maximum Number of ManagedConnections
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.
capacity-increment: Controlling the Number of ManagedConnections
In compliance with Connector Architecture 1.6, 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.
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.
shrinking-enabled: 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 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
shrink-frequency-seconds: Setting the Wait Time Between Attempts to Reclaim Unused ManagedConnections
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
highest-num-waiters: Controlling the Number of Clients Waiting for a Connection
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.
highest-num-unavailable: Controlling the Number of Unavailable Connections
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.
connection-creation-retry-frequency-seconds: Recreating Connections
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.
match-connections-supported: Matching Connections
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
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.
test-frequency-seconds: Testing the Viability of Connections
test-frequency-seconds element allows you to specify how frequently (in seconds) connections in the pool are tested for viability.
test-connections-on-create: Testing Connections upon Creation
You can set the
test-connections-on-create element to enable the testing of connections as they are created. The default value is
test-connections-on-release: Testing Connections upon Release to Connection Pool
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
test-connections-on-reserve: Testing Connections upon Reservation
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
deploy-as-a-whole: Isolating Outbound Connection Pool Failures from the Whole Adapter Deployment
You can set the
deploy-as-a-whole element to determine whether or not the deployment of a resource adapter, which contains multiple outbound connection pools, should fail if a failure occurs in any connection pool. The default value is
true, which causes the whole resource adapter deployment to fail if any error occurs (not just with connection pools).
Setting this element to
false enables the resource adapter deployment to succeed as long as at least one outbound connection pool remains healthy, allowing you isolate, diagnose, repair, and dynamically update the resource adapter without the need to redeploy it.
Connection Proxy Wrapper - 1.0 Resource Adapters
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 implementation class (rather than an interface implemented by the
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 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
- Rather than having
MyConnectionbe a class that implements the resource adapter's
MyConnectionto be an interface that extends
- Implement a
MyConnectionImplclass that implements the
Turning Proxy Generation On and Off
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 Server still supports Java EE Connector Architecture 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.
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).
The test cannot detect a
ClassCastException caused by the client code.
Reset a Connection Pool
ManagedConnectionFactoryor changing transaction support for connection.
You can reset a connection pool in one of two ways:
Reset—If no connections in the pool are in use, the pool is recreated. The new pool includes any configuration changes you may have made prior to the reset. If a connection is in use, the pool is not reset.
Force Reset—Immediately discards all used and unused connections and the pool is recreated. The new pool includes any configuration changes you may have made prior to the reset.
Use the following steps to reset a connection pool from the WebLogic Server Administration Console:
- Select your resource adapter from the Summary of Deployments table.
- Select Control > Outbound Connection Pools
- Select the connection pools to reset.
- Click Reset or Force Reset.
Validatinginterface, 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. See section 184.108.40.206 Detecting Invalid Connections in JSR 322: Java EE Connector Architecture 1.6.
Configuring Connection Testing
The following optional elements in the
weblogic-ra.xml deployment descriptor allow you to control the testing of connections in the pool.
test-frequency-seconds- The connector container periodically tests all the free connections in the pool. Use this element to specify the frequency with which the connections are tested. The default is 0, which means the connections will not be tested.
test-connections-on-create- Determines whether the connection should be tested upon its creation. By default it is false.
test-connections-on-release- Determines whether the connection should be tested upon its release. By default it is false.
test-connections-on-reserve- Determines whether the connection should be tested upon its reservation. By default it is false.
Testing Connections in the Administration Console
To test a resource adapter's connection pools:
- In the WebLogic Server Administration Console, open the Deployments page and select the resource adapter in the Deployments table.
- Select the Test tab.
You will see a table of connection pools for the resource adapter and the test status of each pool.
- Select the connection pool you want to test and click Test.
See Test outbound connections in the Oracle WebLogic Server Administration Console Online Help.