JGroups

For the international holding company, see JGroup.

JGroups

Developer(s)	Bela Ban
Stable release(s)
5.x 5.3.9.Final / July 12, 2024 (2024-07-12) 4.x 4.2.28.Final / April 10, 2024 (2024-04-10)
Repository	github.com/belaban/JGroups
Written in	Java
Operating system	Cross-platform
Size	2.1 MB
Type	reliable multicast system
License	Apache License 2.0
Website	www.jgroups.org

JGroups is a library for reliable one-to-one or one-to-many communication written in the Java language.

It can be used to create groups of processes whose members send messages to each other. JGroups enables developers to create reliable multipoint (multicast) applications where reliability is a deployment issue. JGroups also relieves the application developer from implementing this logic themselves. This saves significant development time and allows for the application to be deployed in different environments without having to change code.

Features

• Group creation and deletion. Group members can be spread across LANs or WANs
• Joining and leaving of groups
• Membership detection and notification about joined/left/crashed members
• Detection and removal of crashed members
• Sending and receiving of member-to-group messages (point-to-multipoint)
• Sending and receiving of member-to-member messages (point-to-point)

Code sample

This code below demonstrates the implementation of a simple command-line IRC client using JGroups:

public class Chat extends ReceiverAdapter {
    private JChannel channel;

    public Chat(String props, String name) {
        channel = new JChannel(props)
            .setName(name)
            .setReceiver(this)
            .connect("ChatCluster");
    }

    public void viewAccepted(View view) {
        System.out.printf("** view: %s\n", view);
    }

    public void receive(Message msg) {
        System.out.printf("from %s: %s\n", msg.getSource(), msg.getObject());
    }

    private void send(String line) {
        try {
            channel.send(new Message(null, line));
        } catch (Exception e) {}
    }

    public void run() throws Exception {
        BufferedReader in = new BufferedReader(new InputStreamReader(System.in));

        while (true) {
            System.out.print("> ");
            System.out.flush();
            send(in.readLine().toLowerCase());
        }
    }

    public void end() throws Exception {
        channel.close();
    }

    public static void start(Chat client) throws Exception {
        try {
            client.run();
        } catch (Exception e) {
        } finally {
            client.end();
        }
    }

    public static void main(String[] args) throws Exception {
        String props = "udp.xml";
        String name;

        for (int i = 0; i < args.length; i++) {
            if (args[i].equals("-props")) {
                props = args[++i];
                continue;
            }

            if (args[i].equals("-name")) {
                name = args[++i];
                continue;
            }

            System.out.println("Chat [-props XML config] [-name name]");
            return;
        }

        start(new Chat(props, name));
    }
}

A JChannel is instantiated from an XML configuration (e.g. udp.xml). The channel is the endpoint for joining a cluster.

Next, the receiver is set, which means that two callbacks will be invoked:

• viewAccepted(View view) when a new member joins, or an existing member leaves the cluster
• receive(Message msg) when a message from some other cluster member is received

Then, the channel joins cluster "ChatCluster". From now, messages can be sent and received, plus a new view (including this member) will be installed in all cluster members (including the newly joined member).

Anything typed in the main loop results in the creation of a message to be sent to all cluster members, including the sender.

Instances of the chat application can be run in the same process, on the same box, on different hosts in the local network, on hosts in different networks, or in the cloud. The code remains the same; only the configuration needs to be changed.

For example, in a local network, IP multicasting might be used. When IP multicasting is disabled, TCP can be used as transport. When run in the cloud, TCP plus a cloud discovery protocol would be used and so on...

Flexible protocol stack

The most powerful feature of JGroups is its flexible protocol stack, which allows developers to adapt it to exactly match their application requirements and network characteristics. The benefit of this is that you only pay for what you use. By mixing and matching protocols, various differing application requirements can be satisfied. JGroups comes with a number of protocols (but anyone can write their own), for example

• Transport protocols: UDP (IP multicast), TCP
• Fragmentation of large messages
• Discovery protocols to discover the initial membership for a joining node
• Reliable unicast and multicast message transmission. Lost messages are retransmitted
• Failure detection: crashed members are excluded from the membership
• Ordering protocols: Fifo, Total Order (sequencer or token based)
• Membership and notification of joined or crashed members
• Network partition (split brain) detection and merging
• Flow control
• Encryption and authentication (including SASL support)
• Compression

Building blocks

Building blocks are classes layered over JGroups channels, which provide higher-level abstractions such as

• RPCs to individual or all cluster nodes
• Distributed caches
• Distributed locks
• Distributed atomic counters
• Distributed task execution

External links

• The JGroups website
• A simple request distribution example in JGroups
• A slideshow presenting JGroups