ASAPPeer

There is a video 25' video that tries to explain the core developers concept.

From developers perspective, there are just two relevant methods offered by an ASAP peer:

• an ASAP peer can be asked to deliver a message
• a listener can be informed about incomming messages

send a message into your P2P world

static final CharSequence YOUR_APP_NAME = "application/x-yourAppName";
static final CharSequence YOUR_URI = "yourSchema://example";
...
ASAPPeer alicePeer = ...;
byte[] serializedData = "VerySimpleExampleData".getBytes();
// send data
alicePeer.sendASAPMessage(YOUR_APP_NAME, YOUR_URI, serializedData);
// message is stored in the peer

format / uri

The format distinguishes messages from you application from others. E.g. smartphones meet and establish a Bluetooth connection. There could be an ASAP app on both devices but not necessarily the same. An ASAP peer would simply drop ASAP messages with an unknown format unless you explicitly declare otherwise. Two different ASAP apps would briefly exchanges messages just to find out that they have nothing to say to each other and cease communicating.

A uri helps to separate different message types within your application from each other. In a chat, there are message to set up a new discussion topic. Another message is used to post a message. A PKI will exchange certificates but also public keys in the first place. This parameter is optional and there is not need if your application has only one message type.

ASAP encounter

Peers can establish a point-to-point connection. We talk about an ASAP Encounter. Peers exchange messages during each encounter. Peers remember their encounter. Message are only sent one time to another peer. This memory is based on the era concept. Developers do not have to deal with this era concept. The following section can be read as just for your information

era

Era is a non-negative integer value. The initial era is 0 (zero). The era is kept persistent. Era is incremented each time an ASAP encounter is performed and your application sent a new message after a previous encounter.

Example: There might be two persons using your ASAP based application: Alice and Bob. Your application runs e.g. on their mobile phones. Maybe, you application is a kind of messenger.

Let’s also assume, that user Alice has produced a message. Your application would have ask its ASAP peer to send this message. This message is stored in the local ASAP peer.

Now, the ASAP peers on both devices establish a connection (e.g. Bluetooth, an Internet connection via an ASAPHub). Era on Alice side would be increased to 1 (one). Era in Bob side remains unchanged: No new message was created.

Peer on Bobs’ side would receive a message from Alice. It would know that this message was create in Alice era 0. Both peers would remember that encounter. Alice would remember that it sent any message up to era 0.

message received listener

Application can (and in most cases should) subscribe an object that implements ASAPMessageReceivedListener.

Applications are notified about received messages have to subscribe a listener.

ASAPMessageReceivedListener aliceMessageReceivedListener =
                new ASAPMessageReceivedListenerExample();

alicePeer.addASAPMessageReceivedListener(YOUR_APP_NAME, aliceMessagaliceMessageReceivedListener);

The following code just prints out some information about received chunk.

@Override
public void asapMessagesReceived(ASAPMessages msgs,
  String senderE2E, List<ASAPHop> hops) throws IOException {
    System.out.println(msgs.getFormat() + " | " + msgs.getURI() +  " | " + hops);
    Iterator<byte[]> yourPDUIter = messages.getMessages(); // access messages
}

ASAPMessageReceivedListenerExample does a bit more. It illustrates use of the ASAPMessages object.

opportunistic / ASAP routing

Developers do not have to deal with any communication detail. ASAP peers will send messages whenever possible. This behaviour is called opportunistic. ASAP is an opportunistic protocol.

ASAP peers also deliver received messages which makes any ASAP peer a router. (End-to-end encryption is strongly suggested for sensitive data, see crypto package)