Implement your own Shark ASAP application (2 of 5)

Step 2: Designing two sets algorithms

This steps brings your application closer to be a decentralized ASAP application. We are going to design (not yet implement) algorithms. There are actually to sets of algorithms to be implemented. It might look a bit outlandish first. It will be very simple in retrospect, though. Promised.

Most algorithms will very very small and require just a few lines of code. Also promised. Take you time in this step. You have it.

• 2.1 - Recall ASAP
• 2.2 - The Big Picture
• 2.3 - Choose ASAP format
• 2.4 - Implement API methods
• 2.5 - Handle Received Messages
• Results

2.1 Become familiar with ASAP

First step: Make yourself familiar with if you have not yet: What is ASAP and read section ASAP Peer. Go ahead with 2.2 afterwards.

2.2 Get a big picture

Welcome back. A core element of your ASAP application will be an ASAP peer. Most applications have to deal with two general incidents:

1. App users interact with your application.
2. Your application (with a ASAP peer in it) encounters another one.

That is the most essential difference between centralized and decentralized applications. Let’s assume a centralized messenger app: User Alice types something in her app (client side). A send action would deliver serialized data to the central server. Applications logic runs on server side which could inform other client applications. Another client side could retrieve data from server and presents it after de-serialization to its user, e.g. Bob.

A decentralized messenger is (slightly) different: User Alice would also type something in her app. No difference. This app would store those data locally, though. That is different. Data exchange is made during a peer encounter. (This can be in ad-hoc networks. An encounter can also happen via Internet, see e.g. ASAPHub. ASAP applications are not more slowly be design! The are free to chose their infrastructure by design, though – a slow or fast one. But we do not have to deal with those details yet).

We have to deal with to sets of algorithms:

1. How to implement your API? What happens if a user interacts with your application.
2. What has to be done during a peer encounter?

You do not have to write done much in this step. You do not have to implement anything. Take you use cases. Take some paper, a pencil and a tea (of whatever make you relaxed) and think it over. Play out the scenarios.

Let's take our messenger as examples and use case send a message. What happens? User Alice interacts with your API and enters a message. What would you do with it? It must be stored with the ASAP peer. That’s right. But become more specific and remember ASAP message structure.

Make a (mental) note here. What is next. Well, actually nothing. Nothing would happen if there is no other peer nearby.

What would happen if there is a peer encounter. Both peer would exchange messages. Algorithms are required that deals with incoming messages. Messages can be ignored, can be presented to users. Messages can be re-sent or not.

There are two sets of algorithms: One has to deal with user interactions on your applications. What of you application data are to be sent to other peers. How would ASAP messages look like.

The other set has to deal with received messages. How can you extract you application data from messages? Are messages to be re-sent to other peers?

Make a sketch, get the big picture. That is the task of this step. The algorithms have to be described in detail in the next steps.

Some other thoughs: ASAP can be compared to oral communication. Think it that way. Alice says something (to Bob). What would Alice (had to) do if she would hear a message? You could describe even more complex scenarios like a kind of digital money. Alice would issue a bond to Bob. Alice would remember that fact - in IT terms: Alice peer would be in a status that remember the fact of an issued bond. Bob would receive a message that contains a bond of Alice. Would to do with it? Maybe he decides to sign and sends it back. Alice would receive a signed bond from Bob issued by here. What would she do? Etc. pp. Think you application as a series of messages. Your application can remember sent messages. You application must not expect a reply (in a given time frame). Your application is free to ignore a message that returns not within an expected time frame, though. You application must not stop working.

It is probably the most complicated step on the whole trail. Think your whole app. Gosh. Take your time. It can be fun.

It would be no surprise if you would change your API in the process. Do it. You have not yet implemented anything. Changing interfaces does not do any harm in this stage of development. Later it will.

But as always: No over-engineering. Stop it if your thoughts start circling. Start the next step and become more specific. You can come back here anytime. Most will which is ok and normal.

2.3 How man ASAP applications - choose a format

Thanks to the previous steps, you have a fairly good idea what method call results in sending an ASAP message. Some questions remain. The most crucial on is: How many applications are you about to build?.

You might answer: One of course. What a stupid question. Maybe it is but not in any case.

A messenger application has often two facets: Message exchange but also exchange of contact information. Both parts are clearly separated and have different goals: One is to learn about people and addresses. The other exchanges messages. I looks like two different ASAP apps with different format which run together in your application.

Read section Message structure (again).

Choosing a format or multiple formats has some impact on you software design. Implement clearly different tasks as own modules. Treat them as different ASAP applications and give each its own format.

You could also think of mail boxes. You are about implementing a distributed application. Your are about implementing code. Instances of the same code are going to run on different machines. Your instances will communicate by message exchange only. The format helps to separate incoming messages. Code becomes less complex. Choose different formats if you identify separated tasks in your application. If not – there is just one.

It is now time to start coding. Add your format(s)

public interface YourApplicationAPI {
    String APP_FORMAT = “yourOrganisationName/yourAppFormatName”;
    // your methods follow here e.g.
    void method1(String parameter);
    void method2(String parameter);
    void method3(String parameter);
}

2.4 Describe API Algorithms

Your are ready to start implementing your API.

public class YourApplicationAPIImplementation implements YourApplicationAPI {
    private ASAPPeer peer; // assume it is there - we come back to this point
    void method1(String parameter) {/*TODO*/}
    void method2(String parameter) {/*TODO*/}
    void method3(String parameter) {/*TODO*/}
}

You are, of course familiar with concepts like facade and delegate and we do not discuss those software engineering things here but only ASAP specifics.

Now, go through your API and decide for any method: Requires any call of this method a data transfer to another peer? Games have often an initialization phase. Play stones are set up. In chess, there is no communication required because the initial setup is clearly defined. It is the same with games like battleship – the initial setup has to remain a secret to the other party.

From an ASAP point of few, there are two relevant method types: a) Methods which require sending information and b) methods which require received data.

Let's discuss a) first and come back to our previous example. That would be an implementation.

    void sendMessage(Message message) {
        // need to send a message
        // 1st: serialize it:
        MessageSerializer serializer = new MessageSerializer(
                                 message.getRecipient(), 
                                 message.getMessage));

        byte[] serializedMessage = serializer.getSerializedMessage();

        // define a uri if you like
        String uri = "yourChat://chatRoomA";
        // 2nd: send it with ASAP peer
        this.peer.sendASAPMessage(APP_FORMAT, uri, serializedMessage);
    } 
}

peer.sendASAPMessage(..) keeps this message with the peer. This message is transmitted whenever possible during an encounter. It is the better choice in most cases.

There is an alternative method: peer.sendOnlineASAPMessage(..) would send this ASAP message only to peers which have are connected right now. This message is neither stored nor will their be any other attempt to re-transmit this message.

You might need to encrypt or sign your messages. Read section Cryptography in our developer guide. There is a full Public Key Infrastructure (PKI) Component. The PKI is based on ASAP and can run as parallel Shark Component in your application.

Peers store messages and make at least one delivery attempt to any other peer. This default behaviour can be changed, read section behaviour management in our develoder guide.

Most application want to present receive data. A messenger application does barley do anything else. We need access to received messages. There are two general ways:

• You program your own data management. You would add received messages to your persistent storage and implement methods to receive them.
• ASAP peers store both kinds of messages - sent and received. Read section ASAPStorage for details. This option is a good choice for any messenger like application. Our PKI has also no own persistency management.

Choice is yours. You should seriously consider using ASAPStorage. Con: You have to learn this little API. Pro: There is no other parallel persistent data management. You do not have to implement it.

2.5 Describe Received Messages Algorithms

Nearly any application is interested in receiving messages. It is time to remember section receive message. You have to register a listener for any supported format. This is a good thing. It helps to clarify your code. It also helps to separate your code from other components.

There is not much to explain. There are no further hidden tricks and hints. You must general choice is already made: Do you have your own data management or do you use ASAPStorage instead, see previous section.

Results

Congratulations. You have (started) implementing your API. That is very good. Because there are only two remaining steps: Test your software and implement a user interface. There is one intermediary step, though. It can be skipped but we strongly suggest to make your application a Shark Component. It takes less than an hour but allows your application to become part of a larger one. It is worth the time. Next step - make it a component.