JGroups - A Toolkit for Reliable Multicast Communication

The API of JGroups is very simple (similar to a UDP socket). The code is always the same, regardless of the protocol stack used.

To be able to send/receive messages, a channel has to be created. The reliability of a channel is specified via XML, which then causes the creation of the underlying protocol stack.
The example below creates a channel and sends/receives 1 message:

      JChannel channel=new JChannel("/home/bela/udp.xml");
      channel.setReceiver(new ReceiverAdapter() {
          public void receive(Message msg) {
              System.out.println("received msg from " + msg.getSrc() + ": " + msg.getObject());
          }
      });
      channel.connect("MyCluster");
      channel.send(new Message(null, null, "hello world"));
      channel.close();

The channel's properties are specified in the constructor, in this case we refer to an XML file with an absolute path. If we use a relative path, then the file is looked up on the classpath.

The XML file contains a list of protocols to be used by the new channel. Protocols included might be transport, discovery, fragmentation, reliable transmission, flow control and state transfer.

To join a cluster, connect() is called. It returns when the member has successfully joined the cluster named "MyCluster", or when it has created a new cluster (if it is the first member).

Then a message is sent using the send() method. A message contains the receiver's address ('null' = all group members), the sender's address ('null', will be filled in by the protocol stack before sending the message) and a byte buffer. In the example, the String "hello world" is set to be the message's contents. It is serialized into the message's byte buffer.

Since the message is sent to all members, the sender will also receive it (unless the socket option 'receive own multicasts' is set to false). This is done via the receive() callback, which was registered with the channel before.

Finally, the member closes the channel and thus leaves the cluster. This results in a notification being sent to all members who are registered for membership change notifications.