Home | Class Index

SDK Version: 3.11.4-302512

Documentation generated on 24 July 2015

Class
caplin.core.event

EventHub

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) {alert("blow")}
	 app.base.BalloonManager.prototype.pop = function() {alert("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):

	 caplin.core.ServiceRegistry.getService("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 = caplin.core.ServiceRegistry.getService("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 Summary

Attributes Name and Description
caplin.core.event.EventHub()

Constructs an EventHub.

Field Summary

Attributes Name and Description
<static> caplin.core.event.EventHub.GlobalEventHubCreator

This is the single EventHub instance that should be used for all inter-component communication.

Method Summary

Attributes Name and Description
boolean areSubscriberErrorsCaught()

Determine whether errors in any of the event subscribers will be caught and logged by the event hub, or allowed to bubble up.
Object getProxy(String sInterface, String sEventGroup)

Return a proxy for the given event interface that will forward all method invocations to all subscribers on that interface.
void setAreSubscriberErrorsCaught(Boolean bAreSubscriberErrorsCaught)

Set whether errors in any of the event subscribers will be caught and logged by the event hub, or allowed to bubble up.
void subscribe(String sInterface, String sEventGroupMatcher, Object oImplementor)

Create a subscription for a given event interface.
void unsubscribe(String sInterface, String sEventGroupMatcher, Object oImplementor)

Cancel an existing event interface subscription.

Constructor Detail

► 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: caplin.core.ServiceRegistry.getService("caplin.event-service")

Field Detail

► <static> caplin.core.event.EventHub.GlobalEventHubCreator

This is the single EventHub instance that should be used for all inter-component communication.

Deprecated
This is now a service and should be accessed using caplin.core.ServiceRegistry.getService("caplin.event-service");

Method Detail

► boolean 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 #setAreSubscriberErrorsCaught method can be used to configure this as appropriate for the environment.

► Object getProxy(String sInterface, String sEventGroup)

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 = caplin.core.ServiceRegistry.getService("caplin.event-service").getProxy("pkg.Logger", "trading.fi");

Parameters
String sInterface The event interface for which a proxy is being requested.
String sEventGroup 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.
Returns
{Object} A proxy object that implements the requested interface, but forwards all event invocation to the relevant subscribers.

► void setAreSubscriberErrorsCaught(Boolean 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
Boolean bAreSubscriberErrorsCaught Whether errors will be caught or will bubble.
See
#areSubscriberErrorsCaught

► void subscribe(String sInterface, String sEventGroupMatcher, Object oImplementor)

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:

caplin.core.ServiceRegistry.getService("caplin.event-service").subscribe("pkg.Logger", "trading.*", oTradingLogger);

Parameters
String sInterface The event interface being subscribed to, and which the implementing component implements.
String sEventGroupMatcher A wild-card matcher specifying the subset of events the subscriber wishes to be notified of.
Object oImplementor A reference to the object receiving the subscription.

► void unsubscribe(String sInterface, String sEventGroupMatcher, Object oImplementor)

Cancel an existing event interface subscription.

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

caplin.core.ServiceRegistry.getService("caplin.event-service").unsubscribe("pkg.Logger", "trading.*", oTradingLogger);

Parameters
String sInterface The event interface the subscription was for.
String sEventGroupMatcher A wild-card matcher specifying the subset of events the subscriber wanted to be notified of.
Object oImplementor A reference to the subscribing object.