EncounterManager

Connection Creation

ASAP peers run an ASAP session over an existing connection. That connection is not created by peers but other parts of an ASAP application. Those parts needs to provide Input- and Outputstream.

ASAP can use any networks that provides those streams - which are all known protocols, like Bluetooth, TCP, LoRa just to name a few. Multiple protocols can and should be used in parallel. That's the very idea of ASAP - build most resilient applications using as much communication protocols as possible.

It makes no sense to connect to peers at the same time over more than one protocol, though. It would a wast of rescource since an ASAP session is rather quick. A peer would not even recognize that is has multiple connection to the same other peer. They would have the same ASAP session over two protocols. Wast of resources.

We decided not to make a peer more complex than it already is but to introduce a EncounterManager. It wraps a peer. It keeps track of running ASAP sessions and can decide if a new connection should be established or not.

The following code is taken from unit test connectAliceAndBobWithEncounterManager_Preferred in ConnectPeers.

// peer alice in its role as connection handler
ASAPConnectionHandler alice = new ASAPPeerFS(TestConstants.ALICE_ID, aliceFolder, formats);

// create an encounter manager for peer alice with cool down period 100ms
ASAPEncounterManager aliceEncounterManager = new ASAPEncounterManagerImpl(alice, 100);

Scenario

Let's discuss usage of our encounter manager in an example.

There are two peers (Alice and Bob) including their encounter manager. Another entity BTConnectionProducer symbolises a part in an application that can produce Bluetooth connections.

1. Bluetooth adapter on both sides would recognize another device in communication range. Adapters would see at least a device name or even a service description if service discovery is used. (Such details are out of the scope here, though).

2. Both adapter should ask their local encounter manager if they should create an connection.

3. Both would agree since there is no other connection to Alice or Bob. Encounter manager remember recent connections over a cool down period. That period is defined by developers. It avoid that flickering effect we already discussed.

4. Their is usually a race condition in ASAP based applications using ad-hoc protocols like Bluetooth: Both side would offer an open port to other (ASAP) applications. Both sides would see each other. Both would realize they are not connected yet and would establish a connection. Both sides would do exactly the same simultaneously. That leads to two Bluetooth connections. (We tested it on several devices and took a few nerving hours to realize the problem). So, encounter manager on both side are called with a hint that this race condition could exist. Encounter manager would start a timer to figure out if two connection attemps with the same device are in process. A protocols runs to clean up the situation. Anyway, you as developers are not bothered with details.

5. Finally, a single connection is established. Encounter manager on both side would ask their peers to run an ASAP session.

Code

Good news: The code is much shorter than this explanation.

InputStream is; 
OutputStream os;
if(aliceEncounterManager.shouldCreateConnectionToPeer​(
    "Bob", EncounterConnectionType.AD_HOC_LAYER_2_NETWORK)) {
        // connect and remember is and os
} else { // leave }

// connection established - create stream pair object
StreamPair newStreamPair = StreamPairImpl.getStreamPair(is, os);

// optional - close connection if - in this case - idle for 200ms
IdleStreamPairCloser.getIdleStreamsCloser(newStreamPair, 200).start();

// ask manager to handle new encouter
aliceEncounterManager.handleEncounter(newStreamPair, EncounterConnectionType.AD_HOC_LAYER_2_NETWORK);