
Release Notes JGroups 2.3
=========================

Version: $Id: ReleaseNotes-2.3.txt,v 1.4 2006/04/26 07:56:01 belaban Exp $
Author: Bela Ban


Multiplexer
-----------
In JBoss we have multiple JGroups channels, one for each application (e.g. JBossCache, ClusterPartition etc).

The goal of the Multiplexer is to combine all stacks with the *same* configuration into one, and have multiple
apps on top of that same channel.

To do this we have to introduce multiplexing and demultiplexing functionality, ie. each app will have to have
a unique application ID (a string), and when sending a message, the message has to be tagged with that ID. When
receiving a message, it will be dispatched to the right app based on the ID attached to the message.
We require special handling for VIEW and SUSPECT messages: those need to be dispatched to *all* apps.
State transfer also needs to be handled specially, here we probably have to use thread locals, or change the API (TBD).

When deployed into JBoss, the Multiplexer will be exposed as an MBean, and all apps that depend on it will be deployed
with dependency injection on the Multiplexer. Of course, the old configuration will still be supported.

The config of the Multiplexer is done via a config file, which lists a number of stacks, each keyed by a name, e.g.
"udp", "tcp", "tcp-nio" etc. See ./conf/stacks.xml for an example. An app is configured with the name of a stack, e.g.
"udp", and a reference to the Multiplexer MBean. It will get a proxy channel through which all of its communication
will take place. The proxy channel (MuxChannel) will mux/demux messages to the real JGroups channel.

The advantage of the Multiplexer is that we can reduce N channels into M where M < N. This means fewer threads, therefore
fewer context switches, less memory consumption and easier configuration and better support.


Partial state transfer
----------------------
The Channel.getState() method can now define the ID of a substate to be fetched. This allows applications to
get only a part of its state, not the entire state.
See http://www.jgroups.org/javagroupsnew/docs/manual/html/user-channel.html#PartialStateTransfer for details.


AUTH
----
AUTH is a protocol directly under GMS, which allows to authenticate members who want to join a group. Based on a
pluggable authentication mechanism, new members are either admitted or rejected. In the latter case, Channel.connect()
will fail with a security exception.
For details see JGroups/doc/design/AUTH.txt.

Sequencer based total order protocol
------------------------------------
SEQUENCER is an improved implementation of total order, and faster than TOTAL. When sending a message to
the group, the sender sends the message via unicast to the coordinator, who then broadcasts the message
(on behalf of the sender) to all members, with a unique sequence number. The coordinator uses FIFO,
but since there is only 1 sender, this results in total order.
SEQUENCER can be used for example to maintain identical replicas of a (JMS) queue: senders and receivers can
send and receive messages to/from any queue replica simultaneously, without affecting the consistency
of all replicas across the cluster.
A quick 2 node performance test (perf.Test) with 2 million 1K messages showed
ca 6500 messages/sec with sequencer.xml, compared to ca. 10500 messages/sec with fc-fast-minimalthreads.xml.
For details see JGroups/doc/design/SEQUENCER.txt.

ENCRYPT enhancements
--------------------
The encrypt_entire_message flag (if set to true) will now encrypt the entire message (including the headers),
as opposed to only encrypting the message buffer. Note that this operation requires serialization of the message,
so setting this option to true is expensive. Why use it ? When one wants to prevent eavesdroppers from snooping
out information located in the (non-encrypted) headers, such as sequence numbers.



Incompatibilities to previous version
-------------------------------------
Changed method signature of the RpcDispatcher.callRemoteMethod() methods to throw a Throwable.
Previously they returned the exception as an object, now the exception will be thrown.
Callers of these methods have to change their code, so this is an incompatible change. However,
these calls are not used in JBossCache and JBoss Clustering.
(http://jira.jboss.com/jira/browse/JGRP-154)



Enhancements and bug fixes
--------------------------
- FD_SOCK now uses the bind address of the transport unless a bind_addr is specifically
  specified, or the -Dbind.address system property is used.
- FRAG had a bug that corrupted messages when messages were sent concurrently in multiple threads


Documentation
-------------
- The user's guide has been updated (http://www.jgroups.org/javagroupsnew/docs/manual/html/index.html)