<chapter id="compatibility">
    <title>Version Compatibility and Interoperability</title>
    
    <para>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.</para>
    
    <para>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.</para>
    
    <para>Beginning in 1.2.4.SP2, a new configuration attribute 
    <literal>ReplicationVersion</literal> 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.</para>
    
    <para>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 <literal>ReplicationVersion</literal> 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 <literal>ReplicationVersion</literal> to 
    <literal>1.2.3</literal> on all caches, a workaround is to set system property 
    <literal>jboss.cache.fqn.123compatible</literal> to <literal>true</literal>.</para>
    
</chapter>