Class: IRouterClient

Methods

addListener

(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 corresponding 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 corresponding transmit channel name).
eventHandler	StandardCallback	The callback to be invoked if the method fails.

Example

FSBL.Clients.RouterClient.addListener("SomeChannelName", function (error, response) {
	if (error) {
 		Logger.system.error("ChannelA Error: " + JSON.stringify(error));
	} else {
 		var data response.data;
 		if (response.originatedHere()) {
  			Logger.system.warn("Received a message from the calling window, ignoring");
 		} else {
			// Logic to perform with data
		}
	}
});

addPubSubResponder

(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 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 guaranteed for overlapping RegEx topics.

See subscribe and publish for interacting with a PubSub responder.

Name	Type	Description
topic	string | RegExp	A unique topic for this responder, or a topic RegEx (e.g. '/abc.+/') to handle a set of topics.
initialState	undefined | object	optional The initial state for the topic; defaults to empty object.
params	undefined | Type Literal	optional Optional parameters. Name Type Description N/A Type Literal Name Type Description publishCallback eventHandler Used to set custom behavior in publishing data. The default callback automatically sets the publish data as the new state. subscribeCallback eventHandler Used to set custom behavior regarding whether an incoming subscribe request is accepted or rejected. The default callback automatically accepts all incoming requests. unsubscribeCallback eventHandler Used to set custom behavior when receiving an unsubscribe request. The default callback automatically accepts the request by calling .removeSubscriber(). See example code.
callback	undefined | Type Literal	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". Name Type Description N/A Type Literal

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)

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 Finsemble.

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 corresponding query channel name); only one responder is allowed per channel.
queryEventHandler	StandardCallback	The callback to be invoked if the method fails.

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)

Checks if Router is ready. May be invoked multiple times. Invokes optional callback and resolves promise when ready, which may be immediately. Router is not ready until underlying transport to Router Service is ready.

Name	Type	Description
cb	undefined | Type Literal	optional Name Type Description N/A Type Literal

publish

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

Sends a query to the responder listening on the 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	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	The callback to be invoked if the method fails.

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)

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	The unique channel name from which to remove the listener.
eventHandler	StandardCallback	The callback to be invoked if the method fails.

removePubSubResponder

(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	string | RegExp	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)

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");

stop

()

Used to stop the router. Generally used for unit testing.

subscribe

(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 asynchronously) receives back current state in a notify; new notifications are received 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	The callback to be invoked if the method fails.

Example

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

transmit

(toChannel, event, options)

Transmits an event to all listeners on the specified channel. If 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	undefined | Type Literal	optional An object containing options for your transmission. Name Type Description N/A Type Literal 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)

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

Currently, the origin of an incoming Router message is determined by way of the SharedWorker transport. By definition, SharedWorkers do not work across domains. This means any message coming in over the transport 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)

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);