Introduction

Combadge is a peer-to-peer messaging toolkit, built on top of JXTA, that provides unreliable unicast and multicast messaging.

The design goal of Combadge is to make it as easy as possible to develop straightforward P2P application rapidly. It does so by implementing some common use cases in JXTA's P2P messaging, such as group discovery, pipe resolution, publishing of advertisement and message serialization.

Download

Combadge is available using Subversion from http://svn.oaktop.com/Combadge. You may prefer the web interface, which has a convenient link that tar's up all the files for you.

The Combadge project was built using Maven. However, you should be able to use it even if you don't use Maven.

Understand by Example

Let's take a look at what it takes to build a simple group of clients that ping each other to measure their network latency.

What It Does

The application that we are implementing is a simple program that starts up and tries to ping all its peers. It then report the latency, in both the outbound (from itself to another peer) and inbound directions.

The complete source code can be downloaded from here. You may want to take a quick look at it before continuing (only 52 lines).

Initialization

The first step to using Combadge is to initalize the JXTA platform and then create a ComSpace based on it. ComSpace is a communication realm identified by a simple name, which is created under a JXTA parent group. Generally, you can just use the world peer group as the parent.

PeerGroup world = PeerGroupFactory.newNetPeerGroup();
final ComSpace space = new ComSpace("Test", world);
space.start();

Don't forget that the ComSpace will also need to be started!

Set up

After starting the runtime, the next step is to install listeners that will receive messages and perform the latency measurement.

In reverse order of the actual program flow, we will first set up the code to respond to messages.

space.attach("/latencydemo/request", new ComListener() {
      public void take(String sender, String path, Object msg) {
        Map map = (Map) msg;
        map.put("mid", new Date());
        space.transmit(sender, "/latencydemo/reply", map);
      }
    });

In this segment, we attach a listener that will respond to any request for testing latency. Notice the first argument to the attach method call, which is a prefix-matching path name for filtering messages. Combadge programs communicate in messages that are classified by path names. The path-based classification gives you an easy way to isolate different services running in the same space.

In case it isn't already obvious, the code above responds to any latency request by putting the current time in the message, and replying it to the sender of the request, using the "/latencydemo/reply" path. Notice that the message is just a simple serialized Java object. There is no complicated message format or options.

space.attach("/latencydemo/reply", new ComListener() {
      public void take(String sender, String path, Object msg) {
        Map map = (Map) msg;
        long start = ((Date) map.get("start")).getTime();
        long mid = ((Date) map.get("mid")).getTime();
        long now = System.currentTimeMillis();
 
        System.out.println(space.whoami() + " to " + sender
            + " - outbound: " + (mid - start) + " return: "
            + (now - mid));
      }
    });

Likewise, we attach a handler that will print out the eventual measurement result. Again, note the prefix in the handler and how it deserialize the message as a plain Java Map.

Finally, below is the code that actually initiate the testing. It sends out, every 2 seconds, a request message with the current time to all the peers who monitor the "/latencytest/request" path.

for(int k = 0; k < 5; k++) {
      Thread.sleep(1000 * 2);
      Map msg = new HashMap();
      msg.put("start", new Date());
      space.broadcast("/latencydemo/request", msg);
    }

Notice that we use the broadcast method, which will broadcast the message to every peer inside this ComSpace.

Clean Up

When you are done, don't forget to clean up Combadge and JXTA!

space.stop();
world.stopApp();

That's it. This is a complete peer-to-peer program that will measure connectivity latency.

More Information

Combadge is licensed under the General Public License, version 2.0.
The documentation for the code is sparse. However, you can learn most of what you need to know about Combadge by studying the test case code and the various demo programs available.

Combadge