J2EE Connector Architecture migration tips

Versions of WebSphere Application Server previous to Version 5.0 provided an initial implementation of the J2EE Connector Architecture (JCA) specification, Version 1.0. This implementation provided basic run time support based on the final JCA 1.0 Specification, but it was not a complete implementation.

Version 5.0 of the product provides a complete implementation of the JCA 1.0 Specification, which supports:

Connection sharing (res-sharing-scope).
Get/use/close programming model for connection handles.
Get/use/cache programming model for connection handles.
XA, Local, and No Transaction models of resource adapters, including XA recovery.
Security options A and C per the specification.
Applications with embedded .rar files
Additional feature: Version 5.0 also provides connection pooling, for increasing the efficiency of connection usage.

As of Version 6.0, the product provides a complete implementation of the JCA 1.5 Specification, which supports:

All the features of the JCA 1.0 Specification.
Deferred enlistment transaction optimization.
Lazy connection association optimization.
Inbound communication from an enterprise information system (EIS) to a resource adapter.
Inbound transactions from an EIS to a resource adapter.
Work management, which enables a resource adapter to put work on separate threads and to pass execution context (such as inbound transactions) to the thread .
Life cycle management, which enables a resource adapter to be stopped and started.

Moving from an early implementation of JCA

If you move from one of the earlier implementations of the J2EE Connector Architecture to the current implementation, be aware of the following corresponding changes in WebSphere Application Server:

This version of the product supports the res-sharing-scope tag within the resource reference (resource-ref) element. This tag was not available in previous versions and defaulted to shareable connections. Beginning with Version 5.0, WebSphere Application Server supports both shareable and unshareable connections.
The current product supports the Web container. Both enterprise bean and Web components can utilize the J2EE Connector Architecture.
Both connection handle usage patterns (get/use/close and get/use/cache) are supported. The get/use/close pattern indicates that a connection is retrieved, used, and closed all within the same transaction or method boundary. The get/use/cache pattern indicates that you can cache a connection across transaction or method boundaries.
The current version supports additional authentication mechanisms. The capability to support Options A and C per the JCA specification is provided, as well as support for res-auth settings of either Application or Container. In versions before Version 5.0, the res-auth setting was basically ignored, therefore it was treated as if res-auth was set to Application. If your existing applications have res-auth set to Container, they might behave differently if you install them into a current environment without any changes.
As of Version 6.0, resource authentication for res-auth settings of Container is preferably specified on the resource-reference mapping during application deployment. Specification of container-managed authentication on a data source or connection factory is deprecated.
As of Version 5.0, you can no longer specify pool and subpool names. The pool name is based on the data source or connection factory Java Naming and Directory Interface (JNDI) name. Subpools were eliminated to provide better performance.
As of Version 6.0, configuration data formerly in the j2c.properties file is now supported through the wsadmin scripting tool and the administration console. A migration utility updates the resources.xml file (or files) based on the settings in a j2c.properties file. A template j2c.properties file is no longer placed in the installed directory tree, but run-time code remains in place to process the file and favor its settings over those from the real configuration.

Migration involving first-time use of connection pooling

If you are upgrading to WebSphere Application Server V6.x from a version prior to V5.0, be aware of the run-time behavior changes that your
applications might incur because of the new connection pooling feature in the product.

Although not required by the J2EE architecture, connection pooling support is provided by the connection management component of WebSphere Application Server to help improve the performance of getting and using connections to a backend, such as a database or transaction resource manager (CICS or IMS, for example). The connection pooling support is provided, individually, to every data source and connection factory that you configure. The properties associated with each connection pool have default values that are sufficient for most application server environments. However, in some cases, the default values might not meet the needs of application connection requests, and result in problems such as ConnectionWaitTimeout exceptions.

Therefore consider the application requirements of each data source and connection factory that you configure, and set the corresponding connection pool properties appropriately. The Connection pool settings and Tuning parameters for data access resources topics provide good reference for setting the properties.

Migration issue for the combination of Web services and JCA connectors

For applications that use Web services and JCA connectors, be aware that those generated on WebSphere Studio Application Developer -- Integration Edition Version 4.1.1 can run unchanged on WebSphere Application Server Version 6.0 only if they are regenerated using WebSphere Studio Application Developer -- Integration Edition Version 5.0 tools, or Rational Application Developer tools. This limitation is because of the wsd14j.jar file. As delivered in WebSphere Application Server Enterprise Version 4.1, the file is not fully compliant with JSR 110 (because JSR 110 was not final at the time that Version 4.1 shipped). The wsd14j.jar file shipped with WebSphere Application Server Version 6.0, of course, is compliant. However, because most of the classes have the same package names and interfaces, BUT NOT ALL, the two wsd14j.jar files cannot co-exist in the same WebSphere Application Server installation.

JDBC provider templates: important general migration tip

Always handle the jdbc-resource-provider-templates.xml file as read-only . When updating this file, special consideration should be taken. Before installing a PTF, you should save your updated jdbc-resource-provider-templates.xml file. After applying the PTF, you will need to verify that the new jdbc-resource-provider-templates.xml file has your correct entries. If the entries are not valid, you will have to merge your changes into this new jdbc-resource-provider-templates.xml file manually.