Class: IRouterClient
Router Client (Finsemble Workspaces)
For communications amongst desktop services, components, or outside the container entirely, Finsemble provides an event infrastructure with high level protocols. The Router is the center of this functionality, sending and receiving messages between windows.
See the Router tutorial for an overview.
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. SeeremoveListener
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
andpublish
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
object optional The initial state for the topic; defaults to empty object.
params
optional Optional parameters.
Name Type Description publishCallback
eventHandler optional Used to set custom behavior in publishing data. The default callback automatically sets the publish data as the new state.
subscribeCallback
eventHandler optional 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 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)
-
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 callback 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)
-
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). SeeSubscribe
for corresponding subscription published results (in the form of aNotify
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");
-
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. Seepublish
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
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)
-
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);