Container interoperability

Container interoperability describes the ability of WAS clients and servers at different versions to successfully negotiate differences in native Enterprise JavaBeans (EJB) Version 1.1 finder methods support and Java 2 Platform, Enterprise Edition (J2EE) Version 1.3 compliance.

At one time, there were significant interoperability problems among WAS, versions 4.0.x and 3.5.x distributed, and Version 4.0.x for zSeries. The introduction of interoperable versions of some class types solved problems for distributed versions 3.5.6, 4.0.3, and 5 as well as for zSeries Version 4.0.x. Older 4.0.x and 3.5.x client and application server 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 application server to turn off the interoperability classes. This lets a more recent application server 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, 4.0.3 and later, and 3.5.6 and later, return different classes for the following:

If the property is set to false, application servers return the old class types, to enable interoperability with versions 3.5.5 and earlier, and 4.0.2 and earlier. If the property is set to true, application servers return the new classes.

Interoperability of Version 3.5.x client with Version 5 application server

Clients at Version 3.5.5 and earlier are not interoperable with Version 5 servers when using:

To interoperate with Version 5 application servers, upgrade all Version 3.5.x clients to Version 3.5.6 or later.

Interoperability of Version 5 client with Version 3.5.x application server

Client at Version 5, using this function Application server at Version 3.5.6, property true Application server at Version 3.5.6, property false (default) Application server at Version 3.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 Version 4.0.x client with Version 5 application server

Ideally, all 4.0.x clients that use Version 5 application servers should be at Version 4.0.3 or later.

Version 5 application servers 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 Version 5 application server. This causes the application server to return the old class types, providing interoperability with clients at Version 4.0.2 and earlier. This is discouraged because:

Interoperability of client at Version 4.0.2 and earlier with Version 5 application server

Client at Version 4.0.2 and earlier, using this function Application server at Version 5, property true (default) Application server at Version 5, 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 Version 5 server uses the new Handle classes but returns the older enumeration and collection classes.

Interoperability of client at Version 4.0.3 and later with Version 5 application server

Clients at Version 4.0.3 and later work well with Version 5 application servers. 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 Version 4.0.3 and later, using this function Application server at Version 5, property true (default) Application server at Version 5, 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 Version 5 client with Version 4.0.x application server

Clients at Version 5 work well with Version 4.0.3 application servers 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 Version 4.0.3 server with com.ibm.websphere.container.portable at the default value, false. Version 5 client handles to application servers at Version 4.0.2 and earlier also have restrictions.

Client at Version 5, using this function Application server at Version 4.0.3, property true Application server at Version 4.0.3, property false (default) Application server at Version 4.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 Version 4.0.x client with Version 5 application server

The only valid configuration for container interoperability with zSeries Version 4.0.x clients is the default configuration for the Version 5 application server.

Interoperability of Version 5 client with zSeries Version 4.0.x application server

Version 5 clients should work with a zSeries Version 4.0.x application server with the correct interoperability fixes described in the zSeries documentation. The interoperability characteristics should be the same as for a Version 4.0.3 distributed application server with the property set to true.

Client at Version 5, using this function zSeries application server at Version 4.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 WAS, Version 5 and Version 5.0.1

Applications that attempt to persist handles to enterprise beans and EJBHome needed to subclass ObjectInputStream in WAS, Version 5. 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 WAS, Version 5 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 Version UID 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 WAS deployment, consider the following issues when applying this update, future WAS Fix Packs for WAS, Version 5.

If a WAS, Version 5 persisted handle or home handle is encountered by a WAS, Version 5.0.1 system, it can be read and utilized. In addition, it is converted to WAS, Version 5.0.1 format if it is re-persisted. The WAS, Version 5.0.1 format cannot be read by a WAS, Version 5 system. In this case, upgrade the Version 5 server to Version 5.0.1 or later.

Problems arise when handles are persisted and shared across systems that are not at the WAS, Version 5.0.1 level or later. However, a Version 5 system can receive a handle from Version 5.0.1 remotely through a call to get a handle on an enterprise bean or a getHomeHandle on an EJBHome . The remote call succeeds, however, any attempt to persist it on the Version 5 system has the same limitations regarding the use of ObjectInputStream and changes in remote interface invalidating the persisted handle.

When your application stored handles persistently and shares this persistence with multiple clients or application servers, apply WAS, Version 5.0.1 or later 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 upgrade systems. Also, handles stored by the WAS, Version 5 can force the applications of the updated system to still subclass ObjectInputStream.

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 WAS, Version 5, Version 4.0.3 and later (with the property flag set), or Version 3.5.7 and later (with the property flag set) are not usable if either the home or the remote interface changes.

If any WAS, Version 3.5.7 or Version 4.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 WAS, Version 3.5.7 and later or Version 4.0.3 applications store a handle obtained from a WAS, Version 5 or Version 5.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 Version 5.0 and Version 5.0.1 or 5.0.2 application servers, first upgrade any Version 5.0 application servers to Version 5.0.1 or later before allowing the Version 5.0.1 or 5.0.2 server into the topology. Version 5.0 servers are not able to understand the persisted Hnandle format used on the Version 5.0.1 and 5.0.2 servers.

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 contains 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.