-
Notifications
You must be signed in to change notification settings - Fork 6
Home
I try to explain in a little movie why we think that building applications on ad-hoc networks are better than sliced bread: ASAP - Motivation. There is also a German version: ASAP - Introduction (German)
(Some older scatches can be found here: ASAP Intro (some sketches (German))
Mobile devices can create ad-hoc networks based on short range protocols. There are number of routing protocols. Most of them recognize changes in network topology and adjust their routing tables accordingly. Devices leaving the network are forgotten sooner or later.
We are interested in a different scenario. We assume mobile devices to be owned by human users. Their devices can establish ad-hoc connections whenever they met. Devices (Users) leaving ad-hoc networks are very likely be seen again. The ASAP protocol is based on those assumptions. Use this library if they hold for your project as well.
ASAP assumes that your application produces messages. ASAP can store and disseminate messages. A lot of application communication patterns can be broken down to message exchange. Apparently, messenger applications are the best example. But even communication within a distributed calender app can be understood and implemented as message exchange: Each change is described in a message which is to be sent to all particiants of that app.
Consequent usage of the command pattern can lead to a server free (and maybe fully distributed application). Writing centralized apps is even more simple.
There is a little movie that tries to explain the core concepts and basic example.
Another movie explains example code which can be found in the test folder of this project.
This movies illustrates the routing features of ASAP with a little triangle scenario.
ASAP based apps are considered to be self-contained. Data, application and communication logic is within the application. ASAP apps are not meant to be complex apps. We implemented a messenger app, a public key infrastructure, a smart contract app but have no plans to implement system like weather predication. Rule of thumb: ASAP is good for
- small data sets
- apps which gather data in a very distributed manner like IoT apps
- apps with (small but) sensitive data with demands for strong privacy
- robust apps which can or should run on Internet but also ad-hoc networks
- apps which want to avoid a server as single point of failure / point to be spied.
- apps who like / need / require full control over their communication networks.
An ASAP app is also called an ASAP Peer. Quite often, an ASAP app / peer is owned / used / can be attached to a human user. It is good practice to name an ASAP peer after its owner if their is any.
Following code sniplet illustrates creation of an ASAP peer which stores its data in a file system.
public static final String PEERS_ROOT_FOLDER = "asapPeersRoot";
...
String name = "Alice";
ASAPChunkReceivedListener asapChunkReceivedListener = null; // explained later
String folderName = PEERS_ROOT_FOLDER + "/" + name;
ASAPPeer asapPeer = ASAPPeerFS.createASAPPeer(name, // peer name
folderName, // peer folder
asapChunkReceivedListener // come back to this one later
);See javadoc for more details.
Applications can comprise several sub apps. A messenger keeps contacts beside chats. Even chats (or however such a construct might be called) can have a different behaviour. Some might be open - anybody can send messages. Some might be closed - only a defined group of users can exchange messages.
Each ASAP Peer comprises an arbitrary number of ASAP Engines. An ASAP Engines offers methods
- to manage data within an ASAP Storage
- to define strategies for data exchange during an encounter with another ASAP Peer.
Following code illustrates creation of an ASAP Engine.
String format = "yourApp/yourDataFormat";
ASAPEngine asapEngine = asapPeer.createEngineByFormat(format);The format string makes engine unique within its peer. It is recommended (but not required) to follow the idea of MIME format.
An engine is only created once when using createEngineByFormat. Subsequent calls would produce same engine again.
See javadoc for more details.
[TODO - will be in an advanced features chapter.]
ASAP Peers run on a hardware which is able to create a point-to-point connection. We think of Bluetooth, Wifi-direct. But even protocols from ISO layer above 2 can be used, e.g. IP, TCP, even SMTP.
ASAP has no requirement to those point-to-point protocols. They can have a low bandwith, high probability of communication breakdowns. ASAP does not assume that a communication can be re-established after breakdown. Protocols can even be switched, e.g. to hide communication patterns.
Basic ASAP routing is very simple:
- ASAP apps produce messages and store them with an ASAP Engine.
- ASAP Peers can be provided with a established point-to-point connection - called ASAP encounter
- Each engine can send messages during this encounter. Each engine will remember its communication partner.
In most cases, ASAP is used for a delayed transmission of messages. Apps produce messages and store it with an ASAP Engine. Engines transmit those messages as-soon-as-possible (asap). They keep track of transmission. Message exchange behaviour can be customized for each engine, see [TODO - extra chapter]
Storing a message is straightforward.
byte[] message = // up to you;
CharSequence messageURI = "yourApp://aString";
asapEngine.add(messageURI, message);Your app must produce messages as byte arrays. It is recommended to described a message with an URI but it can be null, though. A URI helps to separate messages from e.g. different chats within the same ASAP chat engine. A URI can be null, though.
One A in ASAP stands for asynchroneous. Message are received during an ASAP encounter which happens - from ASAP Peer perspective - randomly. ASAP Engines send message during an encounter and store received message locally. (This standard behaviour can be changed - see [TODO]).
ASAP apps are informed about received messages with a ASAPChunkReceivedListener, see javadoc. ASAP app developers should implement a class implementing this interfaces and make it available to the ASAP Peer during its creation or later with setASAPChunkReceivedListener. The ASAP Chunk concept is very simple but not discussed here, see [TODO - details about message exhange].
Just a single method must be implemented. Here is an example:
import net.sharksystem.asap.util.Helper;
...
void chunkReceived(String format, String sender, String uri, int era) {
...
ASAPMessages receivedMessages = Helper.getMessagesByChunkReceivedInfos(
format, sender, uri,
folderName, // see peer creation
era);
Iterator<byte[]> msgInter = receivedMessages.getMessages();Received message a managed by an ASAP Engine. Those messages can be retrieved and deleted. In this code, a Helper class is used to produce a set of (ASAPMessages)[http://sharksystem.net/asap/javadoc/net/sharksystem/asap/ASAPMessages.html]. It is up to the application how to deal with received messages.
(A fully functional example)[https://github.com/SharedKnowledge/ASAPJava/blob/master/test/net/sharksystem/asap/UsageExamples.java] illustrates message exchange between to peers.