Namespace: RouterTransport

Router Transport

Service-Level Module. Manages and contains the point-to-point transports (i.e., Layer 2) supported by Finsemble. Each transport communicates between a Finsemble services or component (i.e. a router client on one end) and the Finsemble router service (another router client on the other end).

Integration into routerService.js is automatic on startup.

Developer Notes on Adding New Transport: 1) Create new transport constructor. 2) Call RouterTransport.addTransport() to make the transport constructor (see the bottom of this file)

Each transport constructor must be implemented with the following interface:

ExampleTransportConstructor(params, parentMessageHandler, source, destination) where

        params is a passed in object including data that may (or may not) be needed for implementing the transport
                params.FinsembleUUID: globally unique identifier for Finsemble (one per host machine)
                params.applicationRoot:  value of manifest.finsemble.applicationRoot,
                params.routerDomainRoot: value of manifest.finsemble.moduleRoot,
                params.sameDomainTransport: transport to use for same domain clients
                params.crossDomainTransport: transport to use for cross domain clients
                params.transportSettings: transport settings from finsemble.router.transportSettings if defined, otherwise an empty object

        parentMessageHandler(incomingTransportInfo, routerMessage) where
                incomingTransportInfo is a transport-specific object containing essential information to route back to the same client.
                    The same object will be returned on a send() so the transport can use to send the message to that client.
                    It's up to the developer to decide what to put in the incomingTransportInfo object. The RouterService never
                    directly uses the object, except to do a property-based comparison for equality (so equality must be based on the top-level properties within the object.)
                routerMessage is an object containing a single router message. The transport generally does not need to know the contents --
                    it only sends and receives these messages. However, the router's header (routerMessage.header) is available to the transport if needed.

        source is either the source's client name or "RouterService" (when the RouterService is the source)

        destination is either the destination's client name or "RouterService" (when the RouterService is the desgination)

        callback(this) returns the constructor.  Normally a constructor is not asyncronous, but support in case the constructed transport requires async initialization.

The transport constructor must implement two functions. 1) send(transport, routerMessage) -- transport object contains destination transport info; routerMessage is the message to send 2) identifier() -- returns transport's name

These functions along with the parentMessageHandler callback all that's needed to interface with the higher-level router (either a client or router service):

The three transports implemented at the bottom of this file can serve as examples.

Methods

staticRouterTransport.addTransport
(transportName, transportConstructor)
common/routerTransport.js, line 75

Adds a new type of router transport to pass message between RouterClient and RouterService.

Name Type Description
transportName string

identifies the new transport

transportConstructor object

returns an instance of the new transport

staticRouterTransport.getActiveTransports
(params)
common/routerTransport.js, line 87

Gets array of active transports. What is active depends both on config and what is supported by the environment. Typically, if OF IAB is defined then the IAB transport is added to active list. Likewise, if SharedWorker defined, then SharedWork transport added to the active list. Special transports that don't have backwards compatability (e.g. FinsembleTransport) are only added if specified in the config.

Name Type Description
params string

transport paramters

Returns:
array of active transport names

staticRouterTransport.getDefaultTransport
(params, incomingMessageHandler, source, destination)
common/routerTransport.js, line 122

Get default transport for event router—this is the most reliable transport across all contexts.

Name Type Description
params object

parameters for transport

incomingMessageHandler any
source any
destination any
Returns:
the transport object

staticRouterTransport.getRecommendedTransport
(params, incomingMessageHandler, source, destination)
common/routerTransport.js, line 135

Get best client transport based on the run-time context. Will only return cross-domain transport if current context is inter-domain.

Name Type Description
params object

parameters for transport

incomingMessageHandler any
source any
destination any
Returns:
the transport object

staticRouterTransport.getTransport
(params, transportName, incomingMessageHandler, source, destination)
common/routerTransport.js, line 185

Get a specific transport by name. The transport must be in list of the active transports (i.e. previously added).

Name Type Description
params object

parameters for transport

transportName any
incomingMessageHandler any
source any
destination any
Returns:
the transport object