Caplin Trader 4.8.0

Class: module:caplin/core/event/EventHub

module:caplin/core/event/EventHub

Constructs an EventHub. You should probably request it as a service from the ServiceRegistry rather than creating your own.

This can be done as follows: require("service!caplin.event-service")

Like OpenAjax Hub, the caplin EventHub class facilitates inter-component communication between components that have no prior knowledge of each other. The EventHub class differs, however, in that it does not use a traditional EventSubscriber interface. Rather than sending named messages on named channels, the EventHub takes a more object oriented approach, and uses method invocations in place of message passing.

Communication is done by choosing any interface or class definition you please, or making your own like this:

	 app.base.BalloonManager = function() {}
	 app.base.BalloonManager.prototype.blow = function(amount) { console.log("blow") }
	 app.base.BalloonManager.prototype.pop = function() { console.log("boom") }

Any object that implements this interface can be subscribed to the event hub on a particular channel (notice how the wildcard allows channel subsets to be specified):

	 require("service!caplin.event-service").subscribe("app.base.BalloonManager", "channelA.*", instanceWithBalloon);

It now becomes possible to publish events to all subscribers by invoking methods on a proxy object as follows:

	 var proxy = require("service!caplin.event-service").getProxy("app.base.BalloonManager", "channelA.updates");
	 proxy.blow(3);
	 proxy.blow(3);
	 proxy.blow(1);
	 proxy.pop();

By using well defined JavaScript interfaces rather than an informally defined set of messages, you get the following advantages:

  • You don't need any un-marshalling code to unpack the messages you receive.
  • You don't end up with anaemic class APIs where all communication is done via a single sendEvent() method.
  • Content assist continues to work within your IDE.
  • You can use tools like jsdoc-toolkit to create readable API documentation.

The EventHub is one of the two classes used to facilitate inter-blade communication:

Constructor

new module:caplin/core/event/EventHub()

Methods

areSubscriberErrorsCaught()

Determine whether errors in any of the event subscribers will be caught and logged by the event hub, or allowed to bubble up.

Catching and logging errors is typically preferable in production environments, whereas failing fast and letting the exception bubble to the top is preferable for developer environments. The module:caplin/core/event/EventHub#setAreSubscriberErrorsCaught method can be used to configure this as appropriate for the environment.

getProxy(sInterface, sEventGroup, proxyInterfaceopt) → {Object}

Return a proxy for the given event interface that will forward all method invocations to all subscribers on that interface.

The following example shows how a proxy for generating FI specific trade messages might be created:

var oFiTradingProxy = require("service!caplin.event-service").getProxy("pkg.Logger", "trading.fi");
Parameters:
Name Type Attributes Description
sInterface String The event interface for which a proxy is being requested.
sEventGroup String A group classification of the type of event messages that will be sent, so that subscribers that want to can limit the events they will receive.
proxyInterface function <optional>
 The event interface for which a proxy is being requested - optional.
Returns:
A proxy object that implements the requested interface, but forwards all event invocation to the relevant subscribers.
Type
Object

setAreSubscriberErrorsCaught(bAreSubscriberErrorsCaught)

Set whether errors in any of the event subscribers will be caught and logged by the event hub, or allowed to bubble up.
Parameters:
Name Type Description
bAreSubscriberErrorsCaught Boolean Whether errors will be caught or will bubble.
See:

subscribe(sInterface, sEventGroupMatcher, oImplementor, proxyInterfaceopt)

Create a subscription for a given event interface.

The following example shows how a trade message only logger might be subscribed for relevant logging events:

require("service!caplin.event-service").subscribe("pkg.Logger", "trading.*", oTradingLogger);
Parameters:
Name Type Attributes Description
sInterface String The event interface being subscribed to, and which the implementing component implements.
sEventGroupMatcher String A wild-card matcher specifying the subset of events the subscriber wishes to be notified of.
oImplementor Object A reference to the object receiving the subscription.
proxyInterface function <optional>
 The event interface for which a proxy is being requested - optional.

unsubscribe(sInterface, sEventGroupMatcher, oImplementor)

Cancel an existing event interface subscription.

The following example shows how a trade message only logger might be unsubscribed from receiving further events:

require("service!caplin.event-service").unsubscribe("pkg.Logger", "trading.*", oTradingLogger);
Parameters:
Name Type Description
sInterface String The event interface the subscription was for.
sEventGroupMatcher String A wild-card matcher specifying the subset of events the subscriber wanted to be notified of.
oImplementor Object A reference to the subscribing object.