Programming with the DoDWAN API

Instantiation of DoDWAN in a Java program

In order for a mobile device to participate in a delay-tolerant mobile ad hoc network using DoDWAN, an instance of class DoDWAN must be created on this device. Basically, a DoDWAN object provides the core services whereby delay-tolerant communication can be achieved in the mobile ad hoc network. This is done as shown below:

import casa.dodwan.run.Dodwan;
...
Dodwan dodwan = new Dodwan(); 
dodwan.online();

Warning: A DoDWAN object maintains a cache where documents in transit can be stored locally. For this reason it is not desirable to create several DoDWAN objects on a single device (and, for that matter, in a single JVM), since that would come down to maintaining duplicates of the cache (and of each document it contains) on this device. This would be quite costly in terms of resource consumption. Note however that several instances of class DoDWAN can indeed be created on a single device, but this mostly makes sense for the purpose of experimentation, demonstration, or simulation. As a general rule, keep in mind that each mobile device should run only one instance of class DoDWAN.

By default, a DoDWAN instance disables communication at startup. Therefore a call to the method online() is required to allow effective message ttransmissions. As soon as it has been created, a DoDWAN instance starts running in the background. When on line, it tries to locate other instances with which it can exchange data. Each DoDWAN instance behaves approximately as described below:

Periodically (by default, every 15 seconds), it broadcasts an announcement that contains its profile of interests (resultant of subscriptions patterns aggregation) and a description of the content of its local cache adapted to the interests of its neighbours.
When receiving this announcement, any other instance of DoDWAN searches in the description for documents of interest it is missing. If there exists such documents, then the receiver of the announcement sends a request to the announcement sender, asking for the broadcast of the documents it is missing.
Any DoDWAN instance that receives a document verifies if it is interested by this document. If so, then the receiver puts the document in its cache. Thereafter, this DoDWAN instance will serve as a mobile carrier for the newly acquired document, thus contributing to help disseminate this document further in the network.

Since each instance of DoDWAN broadcasts an announcement periodically, replies favorably to any request it receives from its neighbours and stores documents of interest in its local cache, the global result is a delay-tolerant selective dissemination of documents in the whole network. This dissemination is however dependent on the mobility and volatility of the devices that participate in the network.

Sending and receiving messages using the publish/subscribe service

DoDWAN supports the dissemination of so-called “messages”. A message contains:

a descriptor which contains a number of attributes that can be used to specify the source of this message, its destination, its type, etc;
a payload as raw data (bytes).

Classe Descriptor are used when invoking methods related to the publish/subscribe service of DoDWAN.

Creating a descriptor

A Descriptor object can be created as shown below:

import casa.dodwan.docware.*;
...
Descriptor descriptor = new Descriptor();

Every message is identified through a so called document identifier stored in its descriptor, this identifier serving as a key for the message in the cache . A convenient way of setting this identifier is to use the method that forges a unique one, as shown below:

descriptor.setUniqueDocumentId();

In order not to globally saturate the DoDWAN network, messages remain in the cache of a DoDWAN instance only during a limited amount of time. For this purpose, a so-called deadline must be given to each message. This can be done as shown below. Note that if no deadline is present in the descriptor, the message will be destroyed as soon as deposited in the cache.

descriptor.setDeadline(new Date(System.currentTimeMillis() + 60000));

A descriptor can be given a number of additional, user-defined attributes:

descriptor.setAttribute("language", "English");
descriptor.setAttribute("topic", "DTN routing");

Sending a message

Once a Descriptor has been created, a message can be sent in the network using DoDWAN’s Publish/Subscribe service:

dodwan.pubSubService.publish(descriptor, new String("Hello Topic DTN routing").getBytes());

Receiving messages

The publish/subscribe service makes it possible to receive and process messages selectively. In order to specify what kind of messages we wish to receive from the network, a description of this kind of messages must be provided. This is done by defining a pattern for these messages. A pattern is simply a Descriptor that contains a number of attributes (those we wish to base the selection upon), each attribute carrying a value that is a standard Java regular expression that will be applied in order to find matching documents. The creation of such a pattern descriptor is shown below:

Descriptor pattern = new Descriptor();
pattern.setAttribute("language", "English|French");
pattern.setAttribute("topic", ".*DTN.*|.*SARAH.*");

The pattern defined above describes the kind of messages we are interested in. In this particular case, we wish to select only messages in English or French, and whose attribute ’topic’ contains either the term DTN or SARAH.

Besides describing the kind of messages we are interested in, we must also specify how these messages must be processed. This is done by developing the code of a specific message processor. The code of a verbose processor (that simply displays any message it receives on stdout) is shown below. The process method of this processor is passed the descriptor of the received message. With the key of the message present in this descriptor, it retrieves the payload of the message stored in the cache. In this particular example, the payload is returned as an array of bytes. It also possible to put the retrieved payload in a file.

import casa.dodwan.util.*;
 
public class MyProcessor implements Processor<Descriptor> {

  public void process(Descriptor descriptor) {
  // Any message processed is simply displayed
  System.out.println(descriptor);
  System.out.println(new String(dodwan.pubSubService.getAsBytes(descriptor.getKey()));
  }
}

The pattern that defines the kind of messages we are interested in and the processor that defines how these messages must be processed must be combined in order to form a subscriber that must be registered with DoDWAN’s Publish/Subscribe service. Note that if no processor is supplied, the received messages will be stored in DoDWAN’s cache and relayed to other hosts if possible, without being delivered locally to any consumer.

dodwan.pubSubService.addSubscriber("sub1", pattern, new MyProcessor());

This subscriber is active immediately: any message received by DoDWAN and that matches the subscriber’s pattern will then be passed to the subscriber’s processor. Note that in the above example, the subscriber is registered with a key (string “sub1” in this particular case). This key must be unique so that it is possible to un-register a subscriber from the publish/subscribe service:

dodwan.pubSubService.removeSubscriber("sub1");

Programming with the DoDWAN API

The DoDWAN platform

DoDWAN Apps for netbooks

DoDWAN Apps for smartphones

DoDWAN SDK

Additional documentation

Instantiation of DoDWAN in a Java program

Sending and receiving messages using the publish/subscribe service

Creating a descriptor

Sending a message

Receiving messages

Log In