Container interoperability
Container interoperability describes the ability of WebSphere Application Server clients and servers at different versions to successfully negotiate differences in native Enterprise JavaBeans (EJB) V1.1 finder methods support and Java 2 Platform, Enterprise Edition (J2EE) V1.3 compliance.
At one time, there were significant interoperability problems among WebSphere Application Server, versions 4.0.x and 3.5.x distributed, and V4.0.x for zSeries. The introduction of interoperable versions of some class types solved these problems for distributed versions 3.5.6, 4.0.3, and 5 as well as for zSeries V4.0.x.
Older 4.0.x and 3.5.x client and appserver versions do not support the interoperability classes, which makes them uninteroperable with versions that use the classes. The system property com.ibm.websphere.container.portable remedies this situation by enabling newer versions of the appserver to turn off the interoperability classes. This lets a more recent appserver return class types that are interoperable with an older client.
Depending on the value of com.ibm.websphere.container.portable, application servers at versions 5 and later, 4.0.3 and later, and 3.5.6 and later, return different classes for the following:
- Enumerations and collections returned by EJB 1.1 finder methods
- EJBMetaData
- Handles to:
- Entity beans
- Session beans
- Home interfaces
- Entity beans
Instructions for setting the com.ibm.websphere.container.portable property are in the release notes for versions 3.5.6 and later, and 4.0.3 and later. The following tables show interoperability characteristics for various version combinations of appservers and clients as well as default property values for each combination.
Interoperability of V3.5.x client with V5 (and later) appserver
Clients at V3.5.5 and earlier are not interoperable with V5 and later servers when using:
- EJBMetaData
- Enumerations returned by EJB 1.x finder methods
- Handles to entity beans
If you would like to use updated Handle classes in EJB 2.x-compliant beans but have one of the older clients (versions 3.5.5 and earlier) installed, set the system property com.ibm.websphere.container.portable.finder to false. With this setting in place, the V5 appserver uses the updated handles but returns the enumerations and collections that were used in the earlier clients.
Interoperability of V5 (and later) client with Version 3.5.x appserver
| Client at V5 and later, using this function | Application server at V3.5.6, property true | Application server at V3.5.6, property false (default) | Application server at V3.5.5 and earlier |
|---|---|---|---|
| EJBMetaData | Does not work across domains | Works | Does not work |
| Handle to session bean | Works | Works | Does not work |
| Handle to entity bean | Does not work across domains | Does not work across domains | Does not work across domains |
| Enumeration returned by EJB 1.x finder method | Works | Works | Works |
Interoperability of V4.0.x client with V5 (and later) appserver
Ideally, all 4.0.x clients that use Version 5 appservers should be at V4.0.3 or later.
V5 and later appservers return the interoperability class types by default (true). This can cause interoperability problems for distributed clients at versions 4.0.1 or 4.0.2. In particular, problems can occur with collections and enumerations returned by EJB 1.1 finder methods.
Although it is strongly discouraged, you can set com.ibm.websphere.container.portable to false on a V5 and later appserver. This causes the appserver to return the old class types, providing interoperability with clients at V4.0.2 and earlier. This is discouraged because:
- The V5 appserver instance would become non-J2EE 1.3 compliant
with regard to handles, home interface handles, and EJBMetaData.
- EJB 1.x finder methods return collection and enumeration objects that
do not originate from ejbportable.jar.
- Interoperability restrictions still exist with the property set to false.
- V5 and later client handles to entity beans and home interfaces
do not work across domains for the server you set to false.
If you would like to use updated Handle classes in EJB 2.x-compliant beans but have one of the older clients (versions 4.0.2 and earlier) installed, set the system property com.ibm.websphere.container.portable.finder to false. With this setting in place, the V5 and later appserver uses the updated handles but returns the enumerations and collections that were used in the earlier clients.
Interoperability of client at V4.0.2 and earlier with V5 (and later) appserver
| Client at V4.0.2 and earlier, using this function | Application server at V5 and later, property true (default) | Application server at V5 and later, property false |
|---|---|---|
| EJBMetaData | Does not work | Works for 4.0.2 client |
| Handle to session bean | Does not work | Works |
| Handle to entity bean | Does not work | Does not work across cells |
| Enumeration returned by EJB 1.x finder method | Does not work | Works |
| Collection returned by EJB 1.x finder method | Does not work | Works |
| Handle to home interface | Does not work | Does not work across cells |
If you would like to use updated Handle classes in EJB 2.x-compliant beans but have one of the older clients (versions 3.5.5 and earlier, and 4.0.2 and earlier) installed, set the system property com.ibm.websphere.container.portable.finder to false. With this setting in place, the V5 and later server uses the new Handle classes but returns the older enumeration and collection classes.
Interoperability of client at V4.0.3 and later with V5 and later appserver
Clients at V4.0.3 and later work well with V5 and later appservers. However, if you set the com.ibm.websphere.container.portable to false, client handles to entity beans and home interfaces do not work across domains for the server you set to false.
| Client at V4.0.3 and later, using this function | Application server at V5 and later, property true (default) | Application server at V5 and later, property false |
|---|---|---|
| EJBMetaData | Works | Works |
| Handle to session bean | Works | Works |
| Handle to entity bean | Works | Does not work across cells |
| Enumeration returned by EJB 1.x finder method | Works | Works |
| Collection returned by EJB 1.x finder method | Works | Works |
| Handle to home interface | Works | Does not work across cells |
Interoperability of V5 and later client with Version 4.0.x appserver
Clients at V5 and later work well with V4.0.3 appservers if you set com.ibm.websphere.container.portable to true. Client handles to entity beans and home interfaces do not work across domains for any V4.0.3 server with com.ibm.websphere.container.portable at the default value, false. V5 client handles to application servers at V4.0.2 and earlier also have restrictions.
| Client at V5 and later, using this function | Application server at V4.0.3, property true | Application server at V4.0.3, property false (default) | Application server at V4.0.2 or earlier |
|---|---|---|---|
| EJBMetaData | Works | Works | Works for 4.0.2 server only |
| Handle to session bean | Works | Works | Works |
| Handle to entity bean | Works | Does not work across domains | Does not work across domains |
| Enumeration returned by EJB 1.x finder method | Works | Works | Works |
| Collection returned by EJB 1.x finder method | Works | Works | Works |
| Handle to home interface | Works | Does not work across domains | Does not work across domains |
Interoperability of zSeries V4.0.x client with Version 5 and later appserver
The only valid configuration for container interoperability with zSeries V4.0.x clients is the default configuration for the V5 appserver.
Interoperability of V5 and later client with zSeries V4.0.x appserver
V5 clients should work with a zSeries V4.0.x appserver with the correct interoperability fixes described in the zSeries documentation. The interoperability characteristics should be the same as for a V4.0.3 distributed appserver with the property set to true.
| Client at V5 and later, using this function | zSeries appserver at V4.0.x |
|---|---|
| EJBMetaData | Works |
| Handle to session bean | Works |
| Handle to entity bean | Works |
| Enumeration returned by EJB 1.x finder method | Works |
| Collection returned by EJB 1.x finder method | Works |
| Handle to home interface | Works |
Interoperability of the handle formats in WebSphere Application Server, V5 and Version 5.0.1
Applications that attempt to persist handles to enterprise beans and EJBHome needed to subclass ObjectInputStream in WebSphere Application Server, V5. This action was required so that the subclass ObjectInputStream could utilize the context class loader to resolve the classes for enterprise beans and EJBHome stubs.
In addition, handles created and persisted in WebSphere Application Server, V5 only work with objects that have an unchanged remote interface. If the remote interface is changed, the handle is no longer valid because the stub is serialized inside the handle and its serial VUID changes if the remote interface changes.
This release introduces a new handle persistence mechanism that avoids the implementation drawbacks of the previous version. However, if handles are used for this WebSphere Application Server deployment, consider the following issues when applying this update, future WebSphere Application Server Fix Packs and EJB Container cumulative fixes for WebSphere Application Server, V5.
If a WebSphere Application Server, V5 persisted handle or home handle is encountered by a WebSphere Application Server, V5.0.1 system, it can be read and utilized. In addition, it will be converted to WebSphere Application Server, V5.0.1 format if it is re-persisted. The WebSphere Application Server, V5.0.1 format cannot be read by a WebSphere Application Server, V5 system unless PQ72184 is applied.
Problems arise when handles are persisted and shared across systems that are not at the WebSphere Application Server, V5.0.1 level or later. However, a V5 system can receive a handle from V5.0.1 remotely through a call to get a handle on an enterprise bean or a getHomeHandle on an EJBHome. The remote call will succeed, however, any attempt to persist it on the V5 system will have the same limitations regarding the use of ObjectInputStream and changes in remote interface invalidating the persisted handle.
When your application stores handles persistently and shares this persistence with multiple clients or appservers, apply WebSphere Application Server, V5.0.1 or PQ72184 to both the client and server systems at the same time. Failure to do so can result in the inability of these systems to read the handle data stored by upgraded systems. Also, handles stored by the WebSphere Application Server, V5 can force the applications of the updated system to still subclass ObjectInputStream. Applications using the WebSphere Application Server Enterprise, V5 scheduler and process choreographer, are affected by these changes. These users should update their V5 systems at the same time with either V5.0.1 or PQ72184.
If the applications store handles in the session context, or locally in a file on the same system, that is not shared by other applications, on different systems, they might be able to update their systems individually, rather than all at once. If Client Container and thin client applications do not share persisted handle data, they can be updated as needed as well. However, handles created and persisted in WebSphere Application Server, V5, V4.0.3 and later (with the property flag set), or V3.5.7 and later (with the property flag set) are not usable if either the home or the remote interface changes.
If any WebSphere Application Server, V3.5.7 or V4.0.3 and later enables the system property com.ibm.websphere.container.portable to true, any handles to objects on that server have the same interoperability limitations. In addition, if any WebSphere Application Server, V3.5.7 and later or V4.0.3 applications store a handle obtained from a WebSphere Application Server, V5 or V5.0.1, the same restrictions apply, regarding the need to subclass ObjectInputStream and the usability of handles after a change to the remote interface is made.
Replication of the Http Session and Handles
This note applies to you if you place Handles to Homes or EJBs, or EJB or EJBHome references in the Http Session in your application and you use Http Session Replication. If you intend to replicate a mixed environment of V5.0.0 and V5.0.1 or 5.0.2 machines you should first apply the latest V5.0.0 container cumulative e-fix to the V5.0.0 machines before allowing the V5.0.1 or 5.0.2 server into the typology. The reason for this is that V5.0.0 servers are not able to understand the persisted Handle format used on the V5.0.1 and 5.0.2 server. This is similar to the case of V5.0.0 and Version 5.0.1 or 5.0.2 systems trying to use a shared database, mentioned above. But in this case, it is the Http Session object and not the database providing the persistence.
Top Down Deployment Mapping
The size of the Handle objects has grown due to the fix put in to allow serialization and deserialization to occur without the previous requirements of subclassing the ObjectInputStream and so on. Top down deployment of an object that contains EJB and EJBHome references create a database table ddl that has a field of 1000 bytes of VARCHAR for BITDATA which will contain the Handle. It might be that your object's Handle does not fit in the 1000 byte default field, and you might need to adjust this to a higher value. You might try increments of 250 bytes, that is, 1250, 1500, and so on.
EJB containers
Managing EJB containers
EJB container settings