User guide

This section provides an overview with code examples on how to use the API of jEEBus.SHIP. The complete example classes can be found in the downloadable Project in the package org.openmuc.jeebus.ship.examples.

Server side

1. Set up a ShipNodeConfiguration:ShipNodeConfiguration conf = new ShipNodeConfiguration(yourParameters...);
2. Set up a ConnectionHandler which will notify the user when a connection changes:

ConnectionHandler connHandler = new ConnectionHandler() {
    @Override
    public void onMessageReceived(
        byte[] fullMsg, byte[] payload, ShipConnectionInterface shipConn
    ) {
        /*
         This method can also be used to keep track of server
         connections. Note that adding server connections only works in
         auto-accept-mode as messages can not be exchanged with
         unauthenticated partners. Alternatively use the clientConnectedCB
         to authenticate the partner as well.
        */
        /*
         if (!serverConnections.contains(shipConn)) {
             serverConnections.add(shipConn);
         }
        */
        System.out.println(MessageUtility.parseShipMsgToString(fullMsg));
    }

    @Override
    public void onDisconnect(
        DisconnectReason reason, ShipConnectionInterface shipConn
    ) {
        /*
         this method can be used to keep track of server connections,
         alternatively use the clientConnectedCB
        */
        serverConnections.remove(shipConn);
    }

    @Override
    public void serviceAdded(String ipAddr, String ski) {
        /*
         If you want you can authenticate any received SKI like this.
         However, this is unsecure and not recommended.
        */
        ship.addTrustedSki(ski);
    }

    @Override
    public void serviceRemoved(String ipAddr) {
        // do something
    }

    @Override
    public void connectionDataExchangeEnabled(String ipAddr) {
        /*
         This is called when the connection to a device reaches the
         state "Connection Data Exchange". This is the State where
         non-SHIP-specific Messages (i.e. SPINE) are exchanged.
        */
    }
};

3. Initiate a Ship-Object with the ShipNodeConfiguration and ConnectionHandler to start a SHIP node:Ship ship = new Ship(conf, connHandler);
4. Either set auto accept mode or add the server SKI to the trusted SKIs if you know it in advance:ship.setAutoAcceptMode()Note that the auto accept mode expires after a set time window if no connection was established with another server.
5. Set up a callback for when a client connects to your server:

ship.setClientConnectedCB((connection) -> {
    if (!serverConnections.contains(connection.getApiShipConn())) {
        serverConnections.add(connection.getApiShipConn());
    }

    /*
     Connection Data Preparation (CDP) authenticates client and server and ensures
     a safe communication.
    */
    ship.runConnectionDataPreparation(connection);

    // After successfully running CDP, any message can be sent.
    byte[] exampleMsg = "example payload".getBytes();
    connection.getApiShipConn().sendMsg(exampleMsg);
});

6. Wait for clients to connect.

Client side

1. Set up a ShipNodeConfiguration:ShipNodeConfiguration conf = new ShipNodeConfiguration(yourParameters...);
2. Starting a client requires starting a SHIP node which automatically starts a server. If the node will be purely used as a client a ConnectionHandler is not needed and can be left null. Otherwise implement a ConnectionHandler (see server guide). Note that you will have to know the server IP address in advance if you do not implement a ConnectionHandler.
3. Initiate a Ship-Object with the ShipNodeConfiguration and ConnectionHandler to start a SHIP node:Ship ship = new Ship(conf, connHandler);
4. Either set auto accept mode or add the server SKI to the trusted SKIs if you know it in advance. This is the same as server guide step 4.
5. Open a connection to another SHIP node/server:ShipConnectionInterface shipConnInterface = ship.openConnection("127.0.0.1:2001");
6. Add server SKI to the trusted SKIs if you haven’t already.
7. Send a message to the server:shipConnInterface.sendMsg("exampleMsg".getBytes());
8. Optional: close the connection:shipConnInterface.close()