OrtcClient

public class OrtcClient

ORTC client used for real-time connections.

Snippets

Code

var ortcNodeclient = require('ibtrealtimesjnode').IbtRealTimeSJNode;

// Create ORTC client
var ortcClient = new ortcNodeclient();

// Set ORTC client properties
ortcClient.setId('clientId');
ortcClient.setConnectionMetadata('clientConnMeta');
ortcClient.setClusterUrl('http://ortc-developers.realtime.co/server/2.1/');
//heartbeat settings
ortcClient.setHeartbeatTime(25);
//default is 3
ortcClient.setHeartbeatFails(5)
//enable heartbeat
ortcClient.setHeartbeatActive(true);

ortcClient.onConnected = function (ortc) {
    // Connected

    ortcClient.subscribe('channel1', true, function (ortc, channel, message) {
        // Received message: 'message' - at channel: 'channel');

        ortcClient.unsubscribe(channel);
    });

    ortcClient.subscribeWithBuffer('channel2', 'MyUniqueSubscriberId', function (ortc, channel, seqId, message) {                        
	    console.log("Received message: " + message + " at channel " + channel + " with unique message id " + seqId);                       
	});
};

ortcClient.onDisconnected = function (ortc) {
    // Disconnected
};

ortcClient.onSubscribed = function (ortc, channel) {
    // Subscribed to the channel 'channel');

    ortcClient.send(channel, 'Message to the channel');
};

ortcClient.onUnsubscribed = function (ortc, channel) {
    // Unsubscribed from the channel 'channel');

    ortcClient.disconnect();
};

ortcClient.onException = function (ortc, exception) {
    // Exception occurred: 'exception'
};

ortcClient.onReconnecting = function (ortc) {
     // Trying to reconnect
 };

ortcClient.onReconnected = function (ortc) {
     // Reconnected
 };

 // Post permissions
ortcClient.saveAuthentication(
'http://ortc-developers.realtime.co/server/2.1/', true,
'myAuthenticationToken', 0, 'myApplicationKey', 1400,
'myPrivateKey', { "channel1": "r", "channel2": "w" },
function (error, success) {
	if (error) {
		console.log('Error saving authentication: ' + error);
	} else if (success) {
		console.log('Successfully authenticated');

		ortcClient.connect('myApplicationKey', 'myAuthenticationToken');
	} else {
		console.log('Not authenticated');
	}
});

Constructors

object OrtcClient()

Creates a new instance of the ORTC Client class.

Code

var ortcClient = new ortcNodeclient();

Functions

void connect(string applicationKey, string authenticationToken)

Connects the client using the supplied application key and authentication token.

Parameters

string applicationKey

The application key.

string authenticationToken

The authentication token.

Code

ortcClient.connect('myApplicationKey', 'myAuthenticationToken');

void disablePresence(object Object, function Callback)

Disables presence for the specified channel.

Parameters

object Object

literal with presence attributes.

Properties

String applicationKey

Application key with access to presence service (optional if connected).

String channel

Channel to disable presence.

boolean isCluster

Specifies if url is cluster (optional if connected).

String privateKey

The private key provided when the ORTC service is purchased.

String url

Server containing the presence service (optional if connected).

function Callback

with error and result parameters.

Code

ortcClient.disablePresence({
	applicationKey : 'ORTC_APPLICATION_KEY',
	channel : 'CHANNEL_TO_ACTIVATE_PRESENCE',
	privateKey : 'ORTC_PRIVATE_KEY',
	url : 'http://ortc-developers.realtime.co/server/2.1/',
	isCluster : true
},
function(error,result){
	if(error){
		console.log('Presence',error);
	}else{
		console.log('Presence enable',result);
});	

void disconnect()

Disconnects the client.

Code

ortcClient.disconnect();

void enablePresence(object Object, function Callback)

Enables presence for the specified channel with first 100 unique metadata if true.

Parameters

object Object

literal with presence attributes.

Properties

String applicationKey

Application key with access to presence service (optional if connected).

String channel

Channel to activate presence.

boolean isCluster

Specifies if url is cluster (optional if connected).

boolean metadata

Defines if to collect first 100 unique metadata.

String privateKey

The private key provided when the ORTC service is purchased.

String url

Server containing the presence service (optional if connected).

function Callback

with error and result parameters.

Code

ortcClient.enablePresence({
	applicationKey : 'ORTC_APPLICATION_KEY',
	channel : 'CHANNEL_TO_ACTIVATE_PRESENCE',
	privateKey : 'ORTC_PRIVATE_KEY',
	url : 'http://ortc-developers.realtime.co/server/2.1/',
	isCluster : true,
	metadata : true
},
function(error,result){
	if(error){
		console.log('Presence',error);
	}else{
		console.log('Presence enable',result);
});	

string getAnnouncementSubChannel()

Gets the client announcement subchannel.

string getClusterUrl()

Gets the cluster server URL.

string getConnectionMetadata()

Gets the client connection metadata.

int getConnectionTimeout()

Gets the connection timeout.

string getId()

Gets the client identifier.

string getUrl()

Gets the server URL.

boolean getIsConnected()

Indicates whether the client is connected.

boolean isSubscribed(string channel)

Indicates whether the client is subscribed to the supplied channel.

Parameters

string channel

The channel name.

Code

var isSubscribed = ortcClient.isSubscribed('channel1');

void presence(object Object, function Callback)

Gets a json indicating the subscriptions in the specified channel and if active the first 100 unique metadata.

Parameters

object Object

literal with presence attributes.

Properties

String applicationKey

Application key with access to presence service (optional if connected).

String authenticationToken

Authentication token with access to presence service (optional if connected).

String channel

Channel with presence data active.

boolean isCluster

Specifies if url is cluster (optional if connected).

String url

Server containing the presence service (optional if connected).

function Callback

with error and result parameters.

Code

ortcClient.presence({
	applicationKey : 'ORTC_APPLICATION_KEY',
	authenticationToken : 'AUTHENTICATION_TOKEN',
	isCluster : true,
	url : 'http://ortc-developers.realtime.co/server/2.1/',
	channel : 'CHANNEL_WITH_ACTIVE_PRESENCE'
},
function(error,result){
	if(error){
		console.log('Presence error:',error);
	}else{
		if(result){
			console.log('Subscriptions',result.subscriptions);

			for(var metadata in result.metadata){
				console.log(metadata,'-',result.metadata[metadata]);
			}
		}else{
			console.log('Subscriptions empty');
		}
	}
});

void saveAuthentication(string url, boolean isCluster, string authenticationToken, boolean authenticationTokenIsPrivate, string applicationKey, int timeToLive, string privateKey, object permissions, function(error, success) callback)

Saves the channels and its permissions for the supplied application key and authentication token.

Parameters

string url

The ORTC server URL.

boolean isCluster

Indicates whether the ORTC server is in a cluster.

string authenticationToken

The authentication token generated by an application server (for instance: a unique session ID).

boolean authenticationTokenIsPrivate

Indicates whether the authentication token is private.

string applicationKey

The application key provided when the ORTC service is purchased.

int timeToLive

The authentication token time to live (TTL), in other words, the allowed activity time (in seconds).

string privateKey

The private key provided when the ORTC service is purchased.

object permissions

The channels and their permissions (w: write/read or r: read or p: presence, case sensitive).

function(error, success) callback

Function called when the authentication finishes. If 'error' is not null then an error occurred.

Code

ortcClient.saveAuthentication(
	'http://ortc-developers.realtime.co/server/2.1/',
	true,
	'myAuthenticationToken',
	0,
	'myApplicationKey',
	1400,
	'myPrivateKey',
	{ "channel1": "wrp", "channel2": "w" },
	function (error, success) {
		if (error) {
			console.log('Error saving authentication: ' + error);
		} else if (success) {
			console.log('Successfully authenticated');
		} else {
			console.log('Not authenticated');
		}
	});

void send(string channel, string message)

Sends the supplied message to the supplied channel.

Parameters

string channel

The channel name.

string message

The message to send.

Code

ortcClient.send('channel1', 'This message goes to channel1');

void publish(string channel, string message, integer ttl, function(err, seqId) result)

Publishes the supplied message to the supplied channel using guaranteed delivery mode.

Parameters

string channel

The channel name.

string message

The message to send.

integer ttl

The maximum amount of time (in seconds) the message is kept in the delivery buffer before it expires. To use the maximum allowed by the server use 0 as TTL.

function(err, seqId) result

Callback with the publish result. If an error ocourred err will contain the error description otherwise seqId will contain the published message unique message id.

Code

var ttl = 5 * 60; // 5 minutes
ortcClient.publish("MyChannel", "My message", ttl, function(err, seqId) {
    if(err) {
        console.log("ERROR PUBLISHING: " + err);
    } else {
        console.log("PUBLISHED WITH UNIQUE ID: " + seqId);
    }
});
    

void setAnnouncementSubChannel(string channel)

Sets the client announcement subchannel.

Parameters

string channel

The client announcement subchannel.

void setClusterUrl(string clusterUrl)

Sets the cluster server URL.

Parameters

string clusterUrl

The cluster server URL.

void setConnectionMetadata(string connectionMetadata)

Sets the client connection metadata.

Parameters

string connectionMetadata

The client connection metadata.

void setConnectionTimeout(int connectionTimeout)

Sets the connection timeout.

Parameters

int connectionTimeout

The connection timeout.

void setId(string id)

Sets the client identifier.

Parameters

string id

The client identifier.

void setUrl(string url)

Sets the server URL.

Parameters

string url

The server URL.

void subscribe(string channel, boolean subscribeOnReconnected, function(ortc, channel, message) onMessage)

Subscribes to the supplied channel to receive messages sent to it.

Parameters

string channel

The channel name.

boolean subscribeOnReconnected

Indicates whether the client should subscribe to the channel when reconnected (if it was previously subscribed when connected).

function(ortc, channel, message) onMessage

The callback called when a message arrives at the channel.

Code

ortcClient.subscribe('channel1', true, function (ortc, channel, message) {
	...
});

void subscribeWithFilter(string channel, boolean subscribeOnReconnected, string filter, function(ortc, channel, filtered, message) onMessageWithFilter)

Subscribes to the supplied channel to receive messages sent to it that validate the given filter.

Parameters

string channel

The channel name.

boolean subscribeOnReconnected

Indicates whether the client should subscribe to the channel when reconnected (if it was previously subscribed when connected).

string filter

The filter condition

function(ortc, channel, filtered, message) onMessageWithFilter

The callback called when a message arrives at the channel.
If the filtered parameter is true it means the server was able to filter the message, otherwise the message was not filtered and should be validated by the client.

Code

ortcClient.subscribeWithFilter('channel1', true, 'message.temperature > 70', function (ortc, channel, filtered, message) {
  if(filtered) {
    console.log("Received a filtered message:", message);
  }
});

void subscribeWithBuffer(string channel, string subscriberId, function(ortc, channel, seqId, message) onMessage)

Subscribes to the supplied channel to receive messages sent to it, using a server buffer to guarantee message delivery.

Parameters

string channel

The channel name.

string subscriberId

Identifies uniquely the subscriber, so the server can keep track of the messages already delivered.

function(ortc, channel, seqId, message) onMessage

The callback called when a message is received on the channel. The seqId parameter contains the message unique id.

Code

ortcClient.subscribeWithBuffer('channel1', 'UniqueSubscriberId', function (ortc, channel, seqId, message) {
  ...
});

void subscribeWithOptions(Object options, function(ortc, msgOptions) onMessage)

Subscribes to the supplied channel to receive messages sent to it, using a set of options to allow the mix of different subscription features like buffer, filter and push notifications.

Parameters

Object options

The subscription options containing the following properties: channel, subscribeOnReconnected, filter and subscriberId

function(ortc, msgOptions) onMessage

The callback called when a message is received on the channel. The msgOptions parameter contains an object with the following properties: channel, seqId, filtered and message.

Code

  var options = {
      channel: "MyChannel", 
      subscribeOnReconnected: true,  
      filter: "message.temperature > 70", 
      subscriberId: "MyUniqueSubscriberId"
  }

  ortcClient.subscribeWithOptions(options, function (ortc, msgOptions) {
    var channel = msgOptions.channel;
    var seqId = msgOptions.seqId;
    var filtered = msgOptions.filtered;
    var message = msgOptions.message;

    console.log("Received message", message, "in channel", channel, "with unique id", seqId);
});

void unsubscribe(string channel)

Unsubscribes from the supplied channel to stop receiving messages sent to it.

Parameters

string channel

The channel name.

Code

ortcClient.unsubscribe('channel1');

setHeartbeatTime(integer heartbeatTime)

Setup the amout of time (in seconds) expected by server between each heartbeat message

Parameters

integer heartbeatTime

amout of time expected by server between each heartbeat message

Code

                ortcClient.setHeartbeatTime(25);

          

getHeartbeatTime()

Return the amount of time (in seconds) that server expect heartbeat messages

Parameters

Code

                ortcClient.getHeartbeatTime();

          

setHeartbeatFails(integer numberOfHeartbeatFails)

Setup the amout of lost heartbeat messages tolerated by server before closing the connection. Default is 3

Parameters

integer numberOfHeartFails

number of heartbeat messages that server tolerates before close the connection

Code

              ortcClient.setHeartbeatFails(5);

          

getHeartbeatFails()

Return the amount of fail messages that server tolerates

Parameters

Code

                ortcClient.getHeartbeatFails();

            

setHeartbeatActive(boolean heartbeatActive)

Set if heartbeat are enable for the connection. Default is false

Parameters

boolean heartbeatActive

Set if heartbeat are enable for the connection.

Code

                  ortcClient.setHeartbeatActive(true);

            

getHeartbeatActive()

Return flag to check if heartbeat is active on ortc client

Parameters

Code

                  ortcClient.getHeartbeatActive();

      

Events

onConnected(object ortc)

Occurs when the client connects.

Parameters

object ortc

The ORTC Client object.

Code

ortcClient.onConnected = function (ortc) {
	...
};

onDisconnected(object ortc)

Occurs when the client disconnects.

Parameters

object ortc

The ORTC Client object.

Code

ortcClient.onDisconnected = function (ortc) {
	...
};

onException(object ortc, string exception)

Occurs when there is an exception.

Parameters

object ortc

The ORTC Client object.

string exception

The occurred exception.

Code

ortcClient.onException = function (ortc, event) {
	...
};

onReconnected(object ortc)

Occurs when the client reconnects.

Parameters

object ortc

The ORTC Client object.

Code

ortcClient.onReconnected = function (ortc) {
	...
};

onReconnecting(object ortc)

Occurs when the client attempts to reconnect.

Parameters

object ortc

The ORTC Client object.

Code

ortcClient.onReconnecting = function (ortc) {
	...
};

onSubscribed(object ortc, string channel)

Occurs when the client subscribes to a channel.

Parameters

object ortc

The ORTC Client object.

string channel

The channel name.

Code

ortcClient.onSubscribed = function (ortc, channel) {
	...
};

onUnsubscribed(object ortc, string channel)

Occurs when the client unsubscribes from a channel.

Parameters

object ortc

The ORTC Client object.

string channel

The channel name.

Code

ortcClient.onUnsubscribed = function (ortc, channel) {
	...
};