Class: RouterClientConstructor

Event Router Client

This module contains the RouterClient for sending and receiving events between Finsemble components and services. See Event Router Tutorial for an overview of the router's functionality.

Event router callbacks for incoming messages are always in the form callback(error, event). If error is null, then the incoming data is always in event.data. If error is set, it contains a diagnotic object and message. On error, the event parameter is not undefined.

Members

ready

Backward compatibility?

Methods

addListener
(channel, eventHandler)

clients/routerClientConstructor.js, line 756

Add listener for incoming transmit events on specified channel. Each of the incoming events will trigger the specified event handler. The number of listeners is not limited (either local to this Finsemble window or in a seperate Finsemble window).

See transmit for sending a cooresponding event message to listener. See removeListener to remove the listener.

Name Type Description
channel string

any unique string to identify the channel (must match correspond transmit channel name)

eventHandler function

function (see example below)

Example
FSBL.Clients.RouterClient.addListener("SomeChannelName", function (error, response) {
			if (error) {
				console.log("ChannelA Error: ' + JSON.stringify(error));
			} else {
				var data = response.data;
				console.log("ChannelA Response: ' + JSON.stringify(response));
			}
});

addPubSubResponder
(topic, initialState, params, callback)

clients/routerClientConstructor.js, line 951

Add a PubSub responder for specified topic. All subscribes and publishes to the topic will comes to responder (whether from local window or another window). Only one PubSub responder allowed per topic value in Finsemble application; however, the topic value may be a regular-expression representing a set of related topics, in which case the PubSub responder will responder to all matching topics. When a regEx topic is used, the same default functionality is provides for each matching topic -- the difference is only one PubSub responder is needed to cover a set of related topics, plus the same callback handers can be used (if provided).

All the callback function are optional because each PubSub responder comes with build-in default functionality (described below).

Note an exact topic match will take precedence over a regEx match, but otherwise results are unpredictable for overlapping RegEx topics.

See subscribe and publish for corresponding functions sending to the PubSub responder.

Name Type Description
topic string

unique topic for this responder, or a topic RegEx (e.g. '/abc.+/') to handle a set of topics

initialState object

initial state for the topic (defaults to empty struct); can be any object

params object optional

optional parameters

Name Type Description
subscribeCallback function optional

allows responder know of incoming subscription and accept or reject it (default is to accept)

publishCallback function optional

allows responder to use the publish data to form a new state (default is the publish data becomes the new state)

unsubscribeCallback function optional

allows responder to know of the unsubscribe, but it must be accepted (the default accepts)

callback function optional

optional callback(err,res) function. If addPubSubResponder failed then err set; otherwise, res set to "success"

Example
function subscribeCallback(error, subscribe) {
	if (subscribe) {
		// must make this callback to accept or reject the subscribe (default is to accept). First parm is err and second is the initial state
		subscribe.sendNotifyToSubscriber(null, { "NOTIFICATION-STATE": "One" });
	}
}
function publishCallback(error, publish) {
	if (publish) {
		// must make this callback to send notify to all subscribers (if error parameter set then notify will not be sent)
		publish.sendNotifyToAllSubscribers(null, publish.data);
	}
}
function unsubscribeCallback(error, unsubscribe) {
	if (unsubscribe) {
		// must make this callback to acknowledge the unsubscribe
		unsubscribe.removeSubscriber();
	}
}
FSBL.Clients.RouterClient.addPubSubResponder("topicABC", { "State": "start" },
	{
		subscribeCallback:subscribeCallback,
		publishCallback:publishCallback,
		unsubscribeCallback:unsubscribeCallback
	});

  or

FSBL.Clients.RouterClient.addPubSubResponder("topicABC", { "State": "start" });

  or

FSBL.Clients.RouterClient.addPubSubResponder(\/topicA*\/, { "State": "start" });

addResponder
(channel, queryEventHandler)

clients/routerClientConstructor.js, line 819

Add query responder to the specified channel (only one responder allowed per channel within the Finsemble application). The responder's queryEventHander function will receive all incoming queries for the specified channel (whether from this Finsemble window or remote Finsemble windows).

See query for sending a corresponding query-event message to this responder.

Name Type Description
channel string

any unique string to identify the channel (must match correspond query channel name); only one responder allower per channel

queryEventHandler function

function to handle the incoming query (see example below); note incoming queryMessage contains function to send response

Example
FSBL.Clients.RouterClient.addResponder("ResponderChannelName", function (error, queryMessage) {
	if (error) {
		console.log('addResponder failed: ' + JSON.stringify(error));
	} else {
		// process income query message
		queryMessage.sendQueryResponse(null, queryMessage.data); // A QUERY RESPONSE MUST BE SENT
	}
});

disconnectAll
()

clients/routerClientConstructor.js, line 1077

Removes all listeners, responders, and subscribers for this router client -- automatically called when client is shutting down. Can be called multiple times.

onReady
(cb)

clients/routerClientConstructor.js, line 722

Checks if router is ready. May be invoked multiple times. Invokes cb when ready, which may be immediately. Router is not ready until underlying transport to router service is ready.

Name Type Description
cb function

callback function to invoke when router is ready

publish
(topic, event)

clients/routerClientConstructor.js, line 1041

Publish to a PubSub Responder, which will trigger a corresponding Notify to be sent to all subscribers (local in this window or remote in other windows). There can be multiple publishers for a topic (again, in same window or remote windows)

See addPubSubResponder for corresponding add of a SubPub responder to handle the publish (i.e. sending notifications to all subscriber). See Subscribe for corresponding subscription to receive publish results (in the form of a notify event)

Name Type Description
topic string

topic being published to

event object

topic state to be published to all subscriber (unless the SubPub responder optionally modifies in between)

Example
FSBL.Clients.RouterClient.publish("topicABC", topicState);

query
(responderChannel, queryEvent, params, responseEventHandler)

clients/routerClientConstructor.js, line 861

Send a query to responder listening on specified channel. The responder may be in this Finsemble window or another Finsemble window.

See addResponder to add a responder to receive the query.

Name Type Description
responderChannel any

any unique string to identify the channel (must match correspond responder channel name)

queryEvent object

event message sent to responder

params any optional

this object currently can carry only a timeout value (e.g. { timeout: 3000 }) for a query-response timer. Timer defaults to 5000 milliseconds is no params value is passed in. A timer is set only when timeout > 0. If the timer expires, only a warning message is display for diagnostics.

responseEventHandler function

event handler to receive in query response (sent from the responder for the specified channel)

Example
FSBL.Clients.RouterClient.query("someChannelName", {}, function (error, queryResponseMessage) {
	if (error) {
		console.log('query failed: ' + JSON.stringify(error));
	} else {
		// process income query response message
		var responseData = queryResponseMessage.data;
		console.log('query response: ' + JSON.stringify(queryResponseMessage));
	}
});

FSBL.Clients.RouterClient.query("someChannelName", { queryKey: "abc123"}, { timeout: 1000 }, function (error, queryResponseMessage) {
	if (!error) {
		// process income query response message
		var responseData = queryResponseMessage.data;
	}
});

removeListener
(channel, eventHandler)

clients/routerClientConstructor.js, line 791

Remove event listener from specified channel for the specific event handler (only listeners created locally can be removed).

See addListener for corresponding add of a listener.

Name Type Description
channel string

unique channel name to remove listener from

eventHandler function

function used for the event handler when the listener was added

removePubSubResponder
(topic)

clients/routerClientConstructor.js, line 987

Remove pubsub responder from specified topic. Only locally created responders (i.e. created in local window) can be removed.

See addPubSubResponder for corresponding add of a SubPub responder.

Name Type Description
topic string

unique topic for responder being removed (may be RegEx, but if so much be exact regEx used previously with addPubSubResponder)

Example
FSBL.Clients.RouterClient.removePubSubResponder("topicABC");

removeResponder
(responderChannel)

clients/routerClientConstructor.js, line 889

Remove query responder from specified channel. Only a locally added responder can be removed (i.e. a responder defined in the same component or service).

See addResponder for corresponding add of a query responder.

Name Type Description
responderChannel string

string identifying the channel to remove responder from

Example
FSBL.Clients.RouterClient.removeResponder("someChannelName");

subscribe
(topic, notifyCallback)

clients/routerClientConstructor.js, line 1019

Subscribe to a PubSub Responder. Each responder topic can have many subscribers (local in this window or remote in other windows). Each subscriber immediately (but asyncronouly) receives back current state in a notify; new notifys are receive for each publish sent to the same topic.

See addPubSubResponder for corresponding add of a SubPub responder to handle the subscribe. See publish for corresponding publish to notify the subscriber.

Name Type Description
topic string

topic being subscribed to

notifyCallback function

invoked for each income notify for the given topic (i.e. initial notify plus for each publish)

Returns:
subscribe-id object optionally used for unsubscribing later
Example
var subscribeId = RouterClient.subscribe("topicABC", function(err,notify) {
		if (!err) {
			var notificationStateData = notify.data;
			// do something with notify data
 	}
});

transmit
(toChannel, event)

clients/routerClientConstructor.js, line 777

Transmit event to all listeners on the specified channel. If no listeners the event is discarded without error. All listeners to the channel in this Finsemble window and other Finsemble windows will receive the transmit.

See addListener to add a listener to receive the transmit.

Name Type Description
toChannel string

any unique string to identify the channel (must match correspond listener channel name)

event any

any object or primitive type to be transmitted

Example
FSBL.Clients.RouterClient.transmit("SomeChannelName", event);

unsubscribe
(subscribeID)

clients/routerClientConstructor.js, line 1059

Unsubscribe from PubSub responder so no more notifications received (but doesn't affect other subscriptions). Only works from the window the PubSub responder was created in.

See subscribe for corresponding subscription being removed.

Name Type Description
subscribeID object

the id return from the corresponding subscribe for the topic

Example
FSBL.Clients.RouterClient.unsubscribe(subscribeId);