JGroups

Table of Contents

• Overview
• Sample code
• Configuration
• Links

Overview

JGroups is a clustering library, allowing members to exchange messages.

It provides the following functionality:

• Joining a given cluster (becoming a member)

• (Once joined), sending messages to other members

• Getting a list of the members in the same cluster

• Registering callbacks that are invoked when

  • a message is received

  • a member joins

  • a member leaves

• Leaving a cluster

Sample code

The code below shows how to send messages to all cluster members. Open two or more shells and run the demo with different arguments (names of the members), e.g. node1, node2 etc.

public class Demo {
    protected JChannel ch;

    protected void start(String name) throws Exception {
        ch=new JChannel("udp.xml").name(name)
          .setReceiver(new MyReceiver(name))
          .connect("demo-cluster");
        int counter=1;
        for(;;) {
            ch.send(null, "msg-" + counter++);
            Util.sleep(3000);
        }
    }

    protected static class MyReceiver implements Receiver {
        protected final String name;

        protected MyReceiver(String name) {
            this.name=name;
        }

        public void receive(Message msg) {
            System.out.printf("-- [%s] msg from %s: %s\n", name, msg.src(), msg.getObject());
        }

        public void viewAccepted(View v) {
            System.out.printf("-- [%s] new view: %s\n", name, v);
        }
    }

    public static void main(String[] args) throws Exception {
        new Demo().start(args[0]);
    }
}

JChannel is the handle to interact with JGroups. In start(), a new JChannel is created with configuration udp.xml (see Configuration), which needs to be found on the classpath. Alternatively, a fully qualified pathname can be given, e.g. /Users/bela/tcp.xml.

The receiver is set to an instance of MyReceiver, which implements two callbacks: viewAccepted(), invoked when a member joins or leaves, and receive(), invoked when a message is received.

Finally, cluster "demo-cluster" is joined via JChannel.connect(). When this call returns, a member can start sending and receiving messages.

The main loop sends a message to all cluster members (including itself) at a given interval.

The output of running 3 members A, B and C might look like this:

-------------------------------------------------------------------
GMS: address=C, cluster=demo-cluster, physical address=192.168.1.106:59093
-------------------------------------------------------------------
-- [C] new view: [A|6] (3) [A, B, C]
-- [C] message from C: msg-1
-- [C] message from A: msg-15
-- [C] message from B: msg-5
-- [C] message from C: msg-2
-- [C] message from A: msg-16

Configuration

A JChannel is created from an XML configuration (but can also be created programmatically, see the manual for details). The configuration contains a list of protocols. JChannel.send(Message msg) sends a message down the stack, passing each protocol, and the transport protocol (at the bottom) sends the message.

At the receiver, the transport protocol reads the message and passes it up the stack to the JChannel, which delivers it to the application (the receive(Message msg) callback).

A configuration might look as follows:

<config xmlns="urn:org:jgroups"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:org:jgroups http://www.jgroups.org/schema/jgroups.xsd">
    <UDP
         mcast_port="${jgroups.udp.mcast_port:45588}"
         thread_pool.max_threads="200" />
    <PING />
    <MERGE3 max_interval="30000"
            min_interval="10000"/>
    <FD_SOCK2/>
    <FD_ALL3/>
    <VERIFY_SUSPECT2 timeout="1500"  />
    <pbcast.NAKACK2 xmit_interval="500"/>
    <UNICAST3 xmit_interval="500" />
    <pbcast.STABLE desired_avg_gossip="50000"
                   max_bytes="4M"/>
    <pbcast.GMS print_local_addr="true" join_timeout="1000"/>
    <UFC max_credits="4M"
         min_threshold="0.4"/>
    <MFC max_credits="4M"
         min_threshold="0.4"/>
    <FRAG2 frag_size="60K"  />
</config>

It essentially contains the list of protocols. In the example above, UDP is the transport protocol and FRAG2 is the top protocol. Protocols have attributes, which govern the working of a protocol, e.g. xmit_interval in UNICAST3, which is the retransmission interval (in milliseconds) of messages, until they’re acknowledged.

The list of protocols defines the quality of service of a given stack, ie. reliable retransmisson, FIFO or total ordering and so on.

JGroups ships with multiple sample configurations, e.g. tcp.xml, which uses TCP instead of UDP as transport protocol. Consult the manual (link below) for more details.

Links

• Web site: http://www.jgroups.org

• Manual: http://www.jgroups.org/ug.html

• JIRA: https://issues.redhat.com/projects/JGRP

• Forum: https://groups.google.com/g/jgroups-dev

Bela Ban, Dec 2022