JGroups - A Toolkit for Reliable Multicast Communication

The API of JGroups is very simple (similar to a UDP socket) and is always the same, regardless of how the underlying protocol stack is composed. To be able to send/receive messages, a channel has to be created. The reliability of a channel is specified as a string, which then causes the creation of the underlying protocol stack. The example below creates a channel and sends/receives 1 message:

String props="UDP:PING:FD:STABLE:NAKACK:UNICAST:" +
             "FRAG:FLUSH:GMS:VIEW_ENFORCER:STATE_TRANSFER:QUEUE";

Message send_msg;
Object  recv_msg;
Channel channel=new JChannel(props);

channel.connect("MyGroup");

send_msg=new Message(null, null, "Hello world");

channel.send(send_msg);

recv_msg=channel.receive(0);
System.out.println("Received " + recv_msg);

channel.disconnect();

channel.close();

The channel's properties are specified when creating it. They include IP Multicast (UDP), failure detection (FD), distributed message garbage collection (STABLE), multicast (NAKACK) and unicast (UNICAST) loss-less and FIFO delivery, fragmentation (FRAG), group membership (GMS, FLUSH, VIEW_ENFORCER, QUEUE) and state transfer (STATE_TRANSFER). Each protocol "X" results in the creation of an instance of a Java class X. All protocol instances are kept in a linked list (the protocol stack), which messages traverse up/down.

To join a group, connect() is called. It returns when the member has successfully joined the group named "MyGroup", or when it has created a new group (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 object "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 'true'). This is done using the receive() method.

Finally, the member disconnects from the channel and then closes it. This results in a notification being sent to all members who are registered for membership change notifications.