Peer side API

Important part

We want to hide as much complexity as possible from application developers. We make it short. Here is the less complex and best way to work with a hub in your ASAP based application.

We assume, you are already familiar with our ASAPEncounterManager.

Here is the code you should copy into your application.

SharkPeer sharkPeer = ...;
ASAPEncounterManagerImpl encounterManager = ...;
ASAPHubManager hubManager = ASAPHubManagerImpl.createASAPHubManager(encounterManager);

// create one or more descriptions
Collection<HubConnectorDescription> hubDescriptions = new ArrayList<>();
HubConnectorDescription localHostHubDescription =
   new TCPHubConnectorDescriptionImpl("localhost", 6910, true);
hubDescriptions.add(localHostHubDescription);

// hub manager will do the rest
HubManager.connectASAPHubs(hubDescriptions, sharkPeer.getASAPPeer(), true);

add and remove HubConnector

You can add and remove HubConnector objects to a ASAPHubManager. This manager performs a simple algorithm: This approach enables you to connect to the Hub using a custom HubConnector object.

1. Get a fresh list of peers from each connected hub
2. establish a connection to each peer - peers newer met first
3. wait a while
4. Go back to step 1

// create an encounter manager
ASAPPeer peer = ...;
ASAPEncounterManager asapEncounterManager = new ASAPEncounterManagerImpl(peer);
// create hub manager with encounter manager
ASAPHubManagerImpl hubManagerImpl = new ASAPHubManagerImpl(asapEncounterManager);
// start it
hubManagerImpl.start();
// use interface - clean is cleaner
ASAPHubManager asapASAPHubManager = hubManagerImpl;
// see step 3. Overwrite default (default 600 s = 10 minutes) if you like
asapASAPHubManager.setTimeOutInMillis(maxTimeOutMillis);
// create a hub hubConnector
HubConnector hubConnector = SharedTCPChannelConnectorPeerSide.createTCPHubConnector(host, specificPort);
// add a listener - use same encounter manager object!
NewConnectionListener listener = new YourNewConnectionListener(asapEncounterManager);
// add to hub manager
asapASAPHubManager.addHub(hubConnector);

// connectors to other hubs can be added as well
...
// can be removed
asapASAPHubManager.removeHub(hubConnector);

2. HubConnector with EncounterManager

It's also possible to connect to the hub without using a ASAPHubManager. You can use this approach if you want to connect to a single hub.

Class names in that project had the tendency to become quite lengthy.

HubConnector hubConnector = SharedTCPChannelConnectorPeerSide.createTCPHubConnector(host, specificPort);
NewConnectionListener listener = ...; // you have to implement this listener
hubConnector.addListener(listener);

// tell hub who you are - other peers will find you
hubConnector.connectHub(PEER_ID);
// get list of peer connected to this hub
hubConnector.getPeerIDs();
// get fresh status information from hub, especially peer ids
hubConnector.syncHubInformation();

This code creates HubConnector object and adds a listener. The listener is called when a point-to-point connection to another peer is established. An ASAP encounter should be initiated. We strongly suggest using our EncounterManager. A working implementation of a listener would be very simple:

class YourNewConnectionListener implements NewConnectionListener {
    private final EncounterManager em;
    YourNewConnectionListener(EncounterManager em) { this.em = em; }
    public void notifyPeerConnected(CharSequence targetPeerID, StreamPair streamPair) {
        try {
            this.em.handleEncounter(streamPair, EncounterConnectionType.INTERNET);
        }
        catch(IOException e) { /* write a log */ }
    }
}

Peers connect and disconnect from hub. It would be useful to get a fresh peer list from time to time, create a new connection to peers etc. Good news: You do not have to implement this algorithm but to use ASAPHubManager

3. using a HubConnector with a custom NewConnectionListener

This approach for handling an encounter between peers connected to the hub should only be used if you are using the hub for non-ASAP applications or for testing/debugging purposes. If the notifyPeerConnected method of NewConnectionListener is called a StreamPair object and the peer-id of the target peer is passed to it. The StreamPair provides an InputStream and an OutputStream which can be used for data transfer with the target peer.

Thus, the ASAPHub could be used as a TCP relay server for a wide range of Java applications. The use of a TCP relay server enables peers to establish a connection to each other even if they are behind a NAT, do not have a public IP address or don't want to expose a public TCP-IP port.

This example shows how to use the ASAPHub as a TCP relay server. We are implementing a custom NewConnectionListener class named CustomConnectionListener. This listener is added to our HubConnector.

public class MyApp{
    
    public static void main(String[] args) throws ASAPException, IOException, InterruptedException {
        // initialize HubConnector
        HubConnector hubConnector = SharedTCPChannelConnectorPeerSide.createTCPHubConnector("127.0.0.1", 6000);
        
        // add our custom NewConnectionListener to the HubConnector
        NewConnectionListener connectionListener = new CustomConnectionListener();
        hubConnector.addListener(connectionListener);
        
        // register on relay server with peer-id "alice"
        // if you want to use the hub as a relay server you should set the 'canCreateTCPConnections' parameter to false
         hubConnector.connectHub("alice", false);
        
        // get all peers which are already registered to the Hub
        Collection<CharSequence> peers = hubConnector.getPeerIDs();
        
        // exchange data with target peer bob
        hubConnector.connectPeer("bob");
        /*
        after the connection request was answered by bob the 'notifyPeerConnected' of our 'CustomConnectionListener'
        will be called   
         */
    }

    class CustomConnectionListener implements NewConnectionListener {

        private InputStream is;
        private OutputStream os;
        private String targetPeerId;

        public CustomConnectionListener(...) {
        ...
        }

        @Override
        public void notifyPeerConnected(CharSequence targetPeerID, StreamPair streamPair) {
            os = streamPair.getOutputStream();
            is = streamPair.getInputStream();
            targetPeerId = targetPeerID;
        
        ...
        }

        public InputStream getInputStream(){
            return is;
        }

        public OutputStream getInputStream(){
            return is;
        }

        public String getTargetPeerId(){
            return targetPeerId;
        }
    }
}

Have a look in our test package for further examples.