Chapter 10. Version Compatibility and Interoperability

While this is not absolutely guaranteed, generally speaking within a major version, releases of JBoss Cache are meant to be compatible and interoperable. Compatible in the sense that it should be possible to upgrade an application from one version to another by simply replacing the jars. Interoperable in the sense that if two different versions of JBoss Cache are used in the same cluster, they should be able to exchange replication and state transfer messages. Note however that interoperability requires use of the same JGroups version in all nodes in the cluster. In most cases, the version of JGroups used by a version of JBoss Cache can be upgraded.

In the 1.2.4 and 1.2.4.SP1 releases, API compatibility and interoperability with previous releases was broken. The primary purpose of the 1.2.4.SP2 release was to restore API compatibility and interoperability. Note, however, that restoring API compatibility with earlier releases meant that 1.2.4.SP2 is not completely API compatible with the other two 1.2.4 releases. If you have built applications on top of 1.2.4 or 1.2.4.SP1, please recompile before upgrading to 1.2.4.SP2 in order to be sure you have no issues.

Beginning in 1.2.4.SP2, a new configuration attribute ReplicationVersion has been added. This attribute needs to be set in order to allow interoperability with previous releases. The value should be set to the release name of the version with which interoperability is desired, e.g. "1.2.3". If this attribute is set, the wire format of replication and state transfer messages will conform to that understood by the indicated release. This mechanism allows us to improve JBoss Cache by using more efficient wire formats while still providing a means to preserve interoperability.

In a rare usage scenario, multiple different JBoss Cache instances may be operating on each node in a cluster, but not all need to interoperate with a version 1.2.3 cache, and thus some caches will not be configured with ReplicationVersion set to 1.2.3. This can cause problems with serialization of Fqn objects. If you are using this kind of configuration, are having problems and are unwilling to set ReplicationVersion to 1.2.3 on all caches, a workaround is to set system property jboss.cache.fqn.123compatible to true.