Class: IRouterClient

Methods

addListener
(channel, eventHandler)(channel, eventHandler)

Adds a listener for incoming transmit events on the 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 separate Finsemble window).

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

Name Type Description
channel string

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

eventHandler StandardCallback

A callback handling any possible error and the response (see example below).

Example

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

addPubSubResponder
(topic, initialState, params, callback)(topic, initialState, params, callback)

Adds a PubSub responder for specified topic. All subscriptions and publications to the topic will come to the responder (whether from local window or another window).

Only one PubSub responder per topic value in Finsemble application is allowed; however, the topic value may be a regular-expression representing a set of related topics, in which case the PubSub responder will respond to all matching topics. When a regEx topic is used, the same default functionality is provided for each matching topic, except that only one PubSub responder is needed to cover a set of related topics, and the same callback handlers can be used (if provided).
You may omit any of the callbacks. If you do, default callbacks will be provided, the behavior of which are described below.
Note an exact topic match will take precedence over a regEx match, but otherwise no specific matching priority is guarenteed for overlapping RegEx topics.
See subscribe and publish for interacting with a PubSub responder.

Name Type Description
topic

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

initialState object optional

The initial state for the topic (defaults to empty object).

params optional

Optional parameters.

Name Type Description
publishCallback StandardCallback optional

Used to set custom behavior in publishing data (the default callback automatically sets the publish data as the new state).

subscribeCallback StandardCallback optional

Used to set custom behavior regarding whether an incoming subscribe request is accepted or rejcted (the default callback automatically accepts all incoming requests).

unsubscribeCallback StandardCallback optional

Used to set custom behavior when receiving an unsubscribe request. The default callback automatically accepts the request by calling .removeSubscriber(). See example code.

callback optional

An optional callback function, accepting a possible error and the response. If addPubSubResponder failed, then the error will be set; otherwise, the response will have a value of "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)(channel, queryEventHandler)

Adds a query responder to the specified channel. The responder's queryEventHandler function will receive all incoming queries for the specified channel (whether from this Finsemble window or remote Finsemble windows).

Note: Only one responder is allowed per channel within the Finsemble application.
See query for sending a corresponding query-event message to this responder.

Name Type Description
channel string

A unique string to identify the channel (must match correspond query channel name); only one responder is allowed per channel.

queryEventHandler StandardCallback

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

Example

FSBL.Clients.RouterClient.addResponder("ResponderChannelName", function (error, queryMessage) {
	if (error) {
		Logger.system.log('addResponder failed: ' + JSON.stringify(error));
	} else {
console.log("incoming data=" + queryMessage.data);
var response="Back at ya"; // Responses can be objects or strings
		queryMessage.sendQueryResponse(null, response); // The callback must respond, else a timeout will occur on the querying client.
	}
});

disconnectAll
()()

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

onReady
(cb)(cb)

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

Callback function to invoke when router is ready.

publish
(topic, event)(topic, event)

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

See addPubSubResponder for corresponding addition of a PubSub publisher (i.e. sending notifications to all subscriber). See Subscribe for corresponding subscription published results (in the form of a Notify event)

Name Type Description
topic string

A unique string representing the topic being published.

event any

The topic state to be published to all subscribers (unless the PubSub responder optionally modifies in between).

Example

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

query
(responderChannel, queryEvent, responseEventHandler)(responderChannel, queryEvent, responseEventHandler)

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

In the other overload for this method, you may specify optional parameters.
See addResponder to add a responder to receive the query.

Name Type Description
responderChannel string

A unique string that identifies the channel (must match the channel name on which a responder is listening).

queryEvent any

The event message sent to the responder.

responseEventHandler StandardCallback

An event handler to receive the query response (sent from a responder that is listening on this channel).

Example

FSBL.Clients.RouterClient.query("someChannelName", {}, function (error, queryResponseMessage) {
	if (error) {
		Logger.system.log('query failed: ' + JSON.stringify(error));
	} else {
		// process income query response message
		var responseData = queryResponseMessage.data;
		Logger.system.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)(channel, eventHandler)

Removes an event listener from the 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 StandardCallback

function used for the event handler when the listener was added

removePubSubResponder
(topic)(topic)

Removes a PubSub responder from the specified topic. Only locally created responders (i.e. created in the local window) can be removed.

See addPubSubResponder for corresponding addition of a PubSub responder.

Name Type Description
topic

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)(responderChannel)

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

See addResponder for adding a query responder.

Name Type Description
responderChannel string

String identifying the channel from which to remove the responder.

Example

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

subscribe
(topic, notifyCallback)(topic, notifyCallback)

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 addition of a PubSub responder to handle the subscribe. See publish for how to publish data to subscribers.

Name Type Description
topic string

A unique string representing the topic being subscribed to.

notifyCallback StandardCallback

Invoked on immediately upon subscription, then again on each incoming notification for the specified topic.

Example

var subscribeId = RouterClient.subscribe("topicABC", function(err,notify) {
		if (!err) {
			var notificationStateData = notify.data;
			// do something with notify data
 	}
});

transmit
(toChannel, event, options)(toChannel, event, options)

Transmits an event to all listeners on the specified channel. If no there are no listeners on the channel, the event is discarded without error. All listeners on 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

A unique string to identify the channel (must match corresponding listener channel name).

event any

An object or primitive type to be transmitted.

options optional

An object containing options for your transmission.

Name Type Description
suppressWarnings boolean

By default, the Router will log warnings if you transmit to a channel with no listeners. Set this to true to eliminate those warnings.

Example

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

trustedMessage
(incomingMessage)(incomingMessage)

Tests an incoming router message to see if it originated from the same origin (e.g. a trusted source...not cross-domain).

Currently identity of the origin is determined via the SharedWorker transport (by definition, SharedWorkers do not work across domains). This means any message coming in over the Inter-application Bus will not be trusted; however, by default, all same-origin components and services connect to the router using a SharedWorker transport.

Name Type Description
incomingMessage any

An incoming router message (e.g. transmit, query, notification) to test to see if trusted.

Example
FSBL.Clients.RouterClient.trustedMessage(incomingRouterMessage);

unsubscribe
(subscribeIDStruct)(subscribeIDStruct)

Unsubscribes from a PubSub responder so no more notifications are 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
subscribeIDStruct
Name Type Description
subscribeID string

The id returned from the corresponding subscription to the topic.

topic string

The topic for the subscription.

Example

FSBL.Clients.RouterClient.unsubscribe(subscribeId);