Release Notes JGroups 2.2.9
===========================

Version: $Id: ReleaseNotes-2.2.9.txt,v 1.8 2005/12/09 14:53:36 belaban Exp $
Author: Bela Ban
Date: Dec 9 2005


JMX support
-----------
The channel and most protocols can now be accessed via JMX. This can
be used in any environment that provides an MBeanServer, e.g. JBoss or
JDK 5. With JDK 5's jconsole, for example, retransmission counters can
be viewed in realtime, or operations can be invoked that dump the
retransmission windows for NAKACK etc.
More information is available at
http://wiki.jboss.org/wiki/Wiki.jsp?page=JMX.


Push model available in JChannel
--------------------------------
Instead of having to pull (receive()) a message out of a channel, a Receiver listener can
be registered with a channel. When a message, view change, state request etc
is available, the listener is called immediately. This avoids a context switch, given
that all messages are usually placed in a queue inside the channel and then pulled out
by the application thread. Here's an example of how this can be used:

JChannel ch=new JChannel();
ch.setReceiver(new ReceiverAdapter() {
    public void receive(Message msg) {
        System.out.println("-- received " + msg);
    }

    public void viewAccepted(View new_view) {
        System.out.println("-- new view: " + new_view);
    }
});
ch.connect("demo");
ch.send(new Message());

Note that ReceiverAdapter is a class which implements the Receiver
interface, so that only the methods one is interested in have to be
overridden.


Fine-grained interface binding
------------------------------
Attributes receive_on_all_interfaces and receive_interfaces enable
receiving multicast packets on all or a number of interfaces, e.g.
receive_interfaces="hme0,hme1,192.168.5.3"


Retransmission from random member
---------------------------------
[NAKACK] This is helpful if we have a large group, and want to avoid
having to ask the original sender of a message for retransmission. By
asking a random member, we take some potential load off of the
original sender.


Added payload to MethodCall
---------------------------
Needed to pass additional information with a method call, required 
in JBossCache.


Common transport protocol TP
----------------------------
UDP and TCP now derive from this, therefore common functionality has
to be implemented and tested only once. TCP now has many more
properties supported by TP.


Bounded buffer in message bundling
----------------------------------
Message bundling has by default always used unbounded buffers. For
very fast senders, this could result in more and more messages
being stored in the queue before the bundling thread could dequeue and
send them, resulting in out-of-memory issues.
The bundling buffer is now bounded, by default a size of 2000 elements
is configured. This can be set via 
outgoing_queue_max_size="<num_elements>".


Performance improvements
------------------------
50% speed improvement for
RpcDispatcher/MessageDispatcher/RequestCorrelator/MethodCall.
Most headers now support size() and Streamable, making marshalling and
unmarshalling faster.


Discovery of all clusters in a network
--------------------------------------
With JGroups/bin/probe.sh or probe.bat, it is now possible to discover *all* clusters running in
a network. This is useful for
- management tools that needs to discover the clusters running, and then drill down into each individual cluster
- for diagnostics and trouble shooting
Details at http://wiki.jboss.org/wiki/Wiki.jsp?page=Probe


View reconciliation (VIEW_SYNC protocol)
----------------------------------------
When a coordinator sends out a new view V2 and then leaves (or crashes), it is possible that not
all members receive that view. So we could end up with some members still having V1, and others having
V2. The members having V2 will discard all messages from members with V1.
Note that this is a very rare case, but when it happens, the cluster is screwed up.
VIEW_SYNC solves this by having each member periodically broadcast its view. When a member receives a view
that is greater than its own view, it installs it. Thus, all members will eventually end up with the same
view should the above problem occur. Note that the view sending is done by default every 60 seconds, but it can
also be triggered through JMX by calling the sendView() method directly.
See JGroups/doc/ReliableViewInstallation for details.


Address canonicalization
------------------------
To avoid many instances of Address, 2.2.9 now uses canonicalization, which points the same
addresses to the same memory location. Therefore most addresses can be garbage collected as soon as they
have been created, resulting in reduced memory overhead. Can be turned off with -Ddisable_canonicalization=true.


TCP_NIO support
---------------
A new implementation of NIO support has been added.  See configuration sample tcp_nio.xml.  
You can configure the number of "reader_threads", "writer_threads" and "processor_threads".
This should allow for large scale TCP based deployments, compared to TCP.

Bug fixes
---------
Critical: in rare cases, the digests could be computed incorrectly,
leading to higher message buffering than necessary

Critical: message bundling (in TP) changed the destination address, so
when unicast messages had to be retransmitted, because dest=null, the
receiver would drop them. This would cause UNICAST to stop delivering
messages, which would accumulate forever ! This happened only in very
rare cases when a high sustained throughput was encountered (e.g. 20
million messages sent at the highest possible speed).
Workaround: set enable_bundling="false" in UDP.

Minor: Apply recv_buf_size/send_buf_size to all TCP socket connections.
Many smaller bug fixes.