Get connection information

This tutorial shows you how to obtain and display information about the status of your application's connection to a streaming server, using Caplin's Connection Service.  In this example, we're displaying it using a coloured indicator that changes colour whenever a new status message is received.

You can get connection information by using caplin.services.ConnectionService, which we provide for that purpose. To use it you will have to add a listener, implementing the ConnectionServiceListener interface, to it by simply calling addStatusChangedListener.

Below, is an example we've provided using a blade workbench.

Setup

The only piece of configuration needed here is to register the connection service we're using.  In an actual application, the app's boot-strapping code will usually do that.

var oConnectionService = new test.blades.connectionblade.workbench.ConnectionStub();
caplin.core.ServiceRegistry.registerService("caplin.connection-service", oConnectionService);
To make this example as simple as possible, we're using a ConnectionStub, which will send status messages every 500ms.

Using the Connection Service

To use the Connection Service, all you need to do is get the service from the Service Registry, and register a ConnectionServiceListener on it. This Listener will be notified whenever a connection change occurs.

The Connection Service also provides a way of connecting and disconnecting from the streaming server by the use of the connect and disconnect methods.

Implementing the ConnectionServiceListener Interface

The ConnectionServiceListener interface has four different callbacks, which will be called when a change is detected on the connection.

These are:

  • onConnectionAvailable: Will be called when the connection is ready and all the services are up.
  • onConnectionUnavailable: Will be called when the connection is down.
  • onConnectionLimited: Will be called when some data-sources are unavailable, and this connection is not completely OK. Some data may be missing or stale if this is the case.
  • onConnectionInfo: Will be called when any message arrives which doesn't actually affect the connection state.

In our example, we will use these callbacks to change the colour of the indicator when connection is Available, Unavailable or Limited, and if some information arrives which doesn’t affect the connection state, we’ll log the message.

/**********************************************************************************************
			   ConnectionServiceListener Interface Implementation
***********************************************************************************************/
test.blades.connectionblade.ExampleClass.prototype.onConnectionUnavailable = function() 
{
	this._modifyIndicator("status_error");
};

test.blades.connectionblade.ExampleClass.prototype.onConnectionInfo = function(sMessage) 
{
	this._showMessage(sMessage);
};

test.blades.connectionblade.ExampleClass.prototype.onConnectionAvailable = function() 
{
	this._modifyIndicator("status_ok");
};
	
test.blades.connectionblade.ExampleClass.prototype.onConnectionLimited = function() 
{
	this._modifyIndicator("status_limited");
};

Get the Service and Register the Listener

So, to summarise, these are the simple steps that we’ll need to follow:

  1. Implement the ConnectionServiceListener interface.
  2. Get the service:

    this.oConnectionService = caplin.core.ServiceRegistry.getService("caplin.connection-service");
  3. Add our listener:

    this.oConnectionService.addStatusChangedListener (this);

Using the ConnectionService in this way with a BladeRunnerJS workbench could produce output something like this:

In this example, only the onConnectionInfo messages are logged in detail;
other status changes cause the indicator light to change colour.