Request Trial

Get started

The first steps to use connectanum


» Next - More about the router

Installation

Router

To install and run the router is very easy. The package comes with an out of the box server that can be build with the maven command mvn compile assembly:single

  1. Install the Java 1.8_91 or higher on the machine that runs the router
  2. Copy the connectanum.jar to a secure destination like /opt/local/connectanum/connectanum.jar and perform sudo chmod +x /opt/local/connectanum/connectanum.jar
  3. Configure ports, certificates, roles and more as needed in /opt/local/connectanum/config/conf.json
  4. Use the provided init.d script or write your own to register connectanum as a service
  5. Start the service
  6. Done

Client

The client is part of the connectanum core package. You need to add the core from your local maven repository to your new client project. To do so, simply deploy connectanum with mvn deploy and add the dependency to your pom.xml.

The core has a Client class that does all the work. This sample code simply bootstraps the client:

final Client client = new Client(/* -1 for no reconnect; >= 0 for reconnect */);

client.setConnectHandler(() -> {
    // WHENEVER THE CLIENT RECONNECTS THIS LAMBDA WILL BE CALLED
    Config config = de.konsultaner.wamp.util.Config.getInstance(Config.class);

    IClientChallenger[] challengers = {new SimpleClientCraChallenger()};
    int nThreads = 10;
    DefaultMessageEventHandler messageEventHandler = new DefaultMessageEventHandler(challengers,nThreads);
    client.setMessageHandler(messageEventHandler);

    client.authenticate(config.client.role.authId,config.client.role.secret,config.client.role.realm).addListener(authenticatedFuture -> {
        if(authenticatedFuture.isSuccess()){
            messageEventHandler.registerMessageEventListeners(SomeProcedures.class);
            messageEventHandler.registerMessageEventListeners(SomeOtherProcedures.class);
        }else{
            System.out.println("Authentication failed with user "+config.client.role.authId+" to realm: "+config.client.role.realm+"!");
            // reconnect if the authentication failed
            client.disconnect().addListener(closeFuture -> {
                if(closeFuture.isSuccess()){
                    client.reconnect();
                }else{
                    System.out.println("Disconnecting failed! Could not start to reconnect.");
                }
            });
        }
    });
});

client.run();

The DefaultMessageEventHandler handles incoming and outgoing messages and forwards them to your controller actions. It is also possible to register event handler for broadcast events as a part of the publish subscribe process. All actions are executed in their own thread to prevent blocking. The amount of threads used for each client is configurable.

init.d

This is a simple example script to run connectanum as a daemon. To see the router output type cat /var/log/messages | less.

#!/bin/sh
### BEGIN INIT INFO
# Provides:          connectanum
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# X-Interactive:     true
# Short-Description: Runs the connectanum router
### END INIT INFO

SERVICE_NAME=Connectanum
PATH_TO_JAR="/usr/local/connectanum/connectanum.jar -s -m"
PID_PATH_NAME=/tmp/connectanum-pid
case $1 in
    start)
        echo "Starting $SERVICE_NAME ..."
        if [ ! -f $PID_PATH_NAME ]; then
            cd /usr/local/connectanum/
            nohup java -jar $PATH_TO_JAR >> /var/log/messages &
            echo $! > $PID_PATH_NAME
            echo "$SERVICE_NAME started ..."
        else
            echo "$SERVICE_NAME is already running ..."
        fi
    ;;
    stop)
        if [ -f $PID_PATH_NAME ]; then
            PID=$(cat $PID_PATH_NAME);
            echo "$SERVICE_NAME stoping ..."
            kill $PID;
            echo "$SERVICE_NAME stopped ..."
            rm $PID_PATH_NAME
        else
            echo "$SERVICE_NAME is not running ..."
        fi
    ;;
    restart)
        if [ -f $PID_PATH_NAME ]; then
            PID=$(cat $PID_PATH_NAME);
            echo "$SERVICE_NAME stopping ...";
            kill $PID;
            echo "$SERVICE_NAME stopped ...";
            rm $PID_PATH_NAME
            echo "$SERVICE_NAME starting ..."
            cd /usr/local/connectanum/
            nohup java -jar $PATH_TO_JAR >> /var/log/messages &
            echo $! > $PID_PATH_NAME
            echo "$SERVICE_NAME started ..."
        else
            echo "$SERVICE_NAME is not running ..."
        fi
    ;;
esac

Secure WebSocket Server with SSL and LetsEncrypt

To secure your Connectanum WebSocket Server with SSL you can use LetsEncrypt. You need to install the certbot first. Configure connectanum to use /usr/local/connectanum/config/ as the default path for the certificate. The following script may be added to the cron tab to be executed every 2 months. This way the certbot issues new certificates and installs them automatically.

#!/bin/bash

service connectanum stop
/bin/certbot/./certbot-auto certonly --standalone --keep -d example.com
cp /etc/letsencrypt/live/example.com/privkey.pem /usr/local/connectanum/config/privkey.pem
cp /etc/letsencrypt/live/example.com/fullchain.pem /usr/local/connectanum/config/fullchain.crt
service connectanum start

Where to use Get started The router The java client JavaScript and other clients