The JGroups project
= JGroups :author: Bela Ban :toc2: :toclevels: 3 :icons: :homepage: http://www.jgroups.org :source-highlighter: pygments
== Overview link:$$http:///jgroups.org$$[JGroups] is a clustering library, allowing members to exchange messages.
It provides the following functionality:
== 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 >), 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:
-- [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]]
== 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:
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.
== Running the tests
The unit tests are executed with Maven:
This runs all TestNG suites (functional, encrypt, byteman, jdbc, stack-independent, time-sensitive, udp, udp-new, tcp, tcp-new, tcp-nio, tcp-nio-new).
To run a single suite:
Replace functional with any of the suite names listed above.
== Links
Bela Ban, Dec 2022
No open issues yet, or sync has not completed.