ASAPStorage

Each ASAP application keeps its data in an ASAPStorage. There are as many ASAPStorage in a peer as applications.

There is not need for ASAP application to access those storages at all. On the contrary, it is a really good idea to build an ASAP application that uses this library only as it was planned to be: a message routing protocol.

Nevertheless, messages are stored. And sometimes it might be easier or requires less resource to just access those messages instead of keeping a copy in an application specific database. We cannot make that decision but provide a documentation. The general concept of ASAP message storing is explained. Some specifics and deeper insights into the API come later.

Application can send and receive messages with the ASAPPeer interface. A message is sent with a specific format.

There is an ASAPStorage for each format. An ASAPStorage keeps all messages of an ASAP application. It can be seen as an in- and outbox in an e-mail system.

Each ASAPStorage has got an ASAPChunkStorage which holds a number of ASAPChunks. A chunk is a collection of ASAP message with the same uri. There are at least as many different chunks different uris in our application. This code snippet is from was used to explain how to send a message.

public static final String FORMAT = "application/x-YOUR_APP_FORMAT";
public static final String MESSAGE_URI = "YOUR_APP://message";
...
ASAPPeer yourPeer = ..;
...
byte[] yourMessageContent = ..; // create it

// send message
yourPeer.sendASAPMessage(FORMAT , MESSAGE_URI , yourMessageContent);

This message is stored for later or immediate (usally both) delivery. The following code illustrates how to get access to the ChunkStorage where this message is stored:

public static final String FORMAT = "application/x-YOUR_APP_FORMAT";
...
ASAPPeer asapPeer = ..; // got an object reference from somewhere else
ASAPStorage  asapStorage = asapPeer.getASAPStorage(FORMAT);
ASAPChunkStorage chunkStorage = asapStorage.getChunkStorage();

There is one other thing to understand before we get access to our message again: It is the era.

Each ASAPStorage has got an era. It is initialized with zero. The era can be changed whenever a) the peer encounters another one or loses a connection. The era is changed if b) also at least one new message was added to this storage by calling yourPeer.sendASAPMessage().

We have anything we need to find our message in the storage:

int era = asapStorage.getEra(); // current era
ASAPChunk asapChunk = chunkStorage.getChunk(MESSAGE_URI, era);
int numberMsg = asapChunk.getNumberMessage(); // how many are there?
// get messages
Iterator<byte[]> messages = asapChunk.getMessages();
while(messages.hasNext()) {
    byte[] message = messages.next();
    // do something useful
}

Era counting

Each storage has its own era. There is no peer wide era. An era is only incremented if a message was added and peers are encountered. As more messages an application produces message as faster grows the era.

Era is of type Integer. The initial era is zero. It grows until it reaches the maximum value that can be represented with an integer. The next era ist zero again. Yes, message are removed after a while when an era comes back. This will usually take quite a while.

You do not have to bother with era arithmetic, though. If you have the need to calculate a previous or following era use the appropriate method:

int era = asapStorage.getEra(); // current era
int previousEra = asapStorage.getPreviousEra(era);
int nextEra = asapStorage.getNextEra(era);
int oldestEra = asapStorage.getOldestEra(); // era of the oldest chunk in this storage

ASAPChannel

Message are seen as a more or less constant flow. Message with the same URI are kept in same chunk until era changes. There are a number of algorithms which do not care about era but a list of message in their original order. That feature is provided by ASAPChannel.

ASAPChannel channel = asapStorage.getChannel(MESSAGE_URI); // current era
Iterator<byte[]> messages = channel.getMessages();

A channel object provides e.g an interator of message not only from one chunk but from all chunks in the right order.

[TODO: recipients and extraData]

Incoming Messages

Message can be retrieved during a peer encounter. Those message are kept in an incoming storage.

// get a (maybe empty) list of all peers we received message from
List<CharSequence> sender = asapStorage.getSender();
// get storage that contains message of this application from "Alice"
ASAPStorage aliceIncomingStorage = asapStorage.getExistingIncomingStorage("Alice");