Previous step: Architecture

For using the ubermep-project simply add dependency on the ubermep-core module from the ubermep project.

The following examples shows how to use ubermep to:

• create a peer-to-peer overlay network
• connect to an existing network
• communicate between the peers

Annotation: For every section below, you can find an appropriate example in the module ubermep-example.

Peer sender = new PeerImpl(new UPAddress("urn:itm:1"), new InetSocketAddress("0.0.0.0", 8080));
sender.start();

Peer receiver = new PeerImpl(new UPAddress("urn:itm:2"), new InetSocketAddress("0.0.0.0", 8081), 
    new InetSocketAddress("0.0.0.0", 8080));
receiver.start();

sender.stop();

For doing communication you first need to create and register a specified listener on the "receiver"-peer, to tell him what to do with the received payload.

There are 3 different kind of listeners:

• UnicastMulticastRequestListener: to handle Unicast and Multicast messages.
• SingleRequestSingleResponseRequestListener: to handle Single Request Single Response messages.
• MultiResponseRequestListener: to handle Single Request Multi Response and Multi Request Multi Response messages

To create a Listener you simply need to implement the specified "handle"-method. To tell ubermep that the message was successfully handled simply return true for the UnicastMulticastRequestListener and the MultiResponseRequestListener. For the SingleRequestSingleResponseRequestListener return the payload you would like to send back to the sender. The listeners on a peer are processed after the pattern of chain of responsibility, so the first listener returning true, respectively not null, is the one used.

For doing Multi-Response messaging you simply call the responseHandle.handleSingleResponse(payload)-method in the handleMultiResponseRequest(...)-method of the MultiResponseRequestListener. This will send a single Multi Response.

You can register a listener on a peer with the addRequestListener-method.

The following subsections describes how to do messaging.

To send a Unreliable Unicast message simply do:

UnreliableRequest request = new UnreliableUnicastRequest(receiver.getLocalUPAddress(), "payload".getBytes());
sender.send(request);

For Unreliable Multicast first create a list of receivers.

List<UPAddress> urns = new ArrayList<UPAddress>() {{
	add(receiver.getLocalUPAddress());
	add(...);
}};

Then send messages.

UnreliableRequest request = new UnreliableMulticastRequest(urns, "payload".getBytes());
sender.send(request);

To send a Reliable Unicast message simply do:

ReliableRequest request = new ReliableUnicastRequest(receiver.getLocalUPAddress(), "payload".getBytes());
final ListenableFuture<Response> responseFuture = sender.send(request);

Getting the response there are 2 possibilities:

• blocking response: wait until response received
• non-blocking response: do not wait until response recieved

To get a response in a "blocking-way" simply do:

Response response = responseFuture.get();

For "non-blocking-way":

responseFuture.addListener(new Runnable() {
	public void run() {
		Response response = responseFuture.get();
	}}, new ScheduledThreadPoolExecutor(1));

Sending Reliable Multicast messages do:

ReliableRequest request = new ReliableMulticastRequest(urns, "payload".getBytes());
final ListenableFuture<Response> responseFuture = sender.send(request);

Getting the response is the same as described before in the subsection Reliable Unicast.

Sending a Single Request Single Response request simply do:

ReliableRequest request = new SingleRequestSingleResponseRequest(receiver.getLocalUPAddress(), "payload".getBytes());
final ListenableFuture<Response> responseFuture = sender.send(request);

Getting the response is the same as described before in the subsection Reliable Unicast.

For sending a Single Request Multi Response request do:

ReliableRequest request = new SingleRequestMultiResponseRequest(receiver.getLocalUPAddress(), "payload".getBytes());
final ListenableFuture<Response> responseFuture = sender.send(request);

Getting the response(s) you have to possibilities:

• getting all responses at once, as described before in the subsection Reliable Unicast
• getting the responses with a ProgressListener, which will be informed for each received single Multi Response

To create a ProgressListener do:

ProgressListenerRunnable progressListenerRunnable = new ProgressListenerRunnable() {
	public void progress(String senderUrn, byte[] payload, int current, int total) {
		//do something with a single Multi Response response received e.g. 
		log.info("received: " + current + " of " + total);
	}

	public void run() {
		//do something when received all responses of the Multi Response response, e.g. 
		Response response = responseFuture.get();
	}
};

To add a ProgressListener to a peer simply do:

// ProgressListener dem ResponseFuture hinzufügen
responseFuture.addListener(progressListenerRunnable, new ScheduledThreadPoolExecutor(2));

For sending a Multi Request Multi Response request do:

ReliableRequest request = new MultiRequestMultiResponseRequest(urns, "payload".getBytes());
final ListenableFuture<Response> responseFuture = sender.send(request);

Getting the response(s) is the same as described above in the subsection Single Request Multi Response.

To use RPC with ubermep, you first need to create a Google Protocol Buffers (Protobuf) message as described on the project page of Protobuf. Afterwards you need to set up your message(s) for supporting rpc services. After compiling your service with the protoc-compiler, you receive a java source code file of your message, which you can include in your project.

Afterwards you need an Implementation the BlockingInterface, or (non-blocking-)Interface of your generated source code. Besides you need to implement ubermeps RpcBlockingService or (non-blocking-)RpcService, dependent on what kind of service you want to use. The "getter" of the Rpc(Blocking)Service need to return a new "Reflective(Blocking)Service", generated by the method newReflectiveBlockingService() of your generated (protobuf)-service.

Now you can register your "rpc-service-implementation" at a peer, by calling the registerService(...)-method.

Then you just need to get you a "rpc-channel" to your address like: UbermepRpcChannel blockingReceiverRpcChannel = sender.getRpcChannel(receiverUrn);, create a stub from your generated service and finally you can call your method.

For calling non-blocking services you additionaly need a parameter of the interface RpcCallback, which you can construct via the class RpcCallbackImpl.