org.electrocodeogram.cpc.core.api.hub.registry
Interface IEventHubRegistry

All Known Subinterfaces:

IManagableEventHubRegistry

public interface IEventHubRegistry

The central event dispatcher for CPCEvents, a key component of the CPC Framework. Each CPC subsystem can send events which may be of interest to other subsystems to this event hub. They are then dispatched to all interested parties.

Events are dispatched synchronously and asynchronously, depending on the preferences of the subscribed listeners.

Programmatical subscription/unsubscription for arbitrary CPCEvent types is handled by the subscribe and unsubscribe methods. Other modules interested in dynamically modifying their subscriptions should use these methods to subscribe/unsubscribe for the event types they are interested in.

However, the recommended way for static subscription is the eventHubListeners extension point of the CPC Core module.

A reference to the currently active IEventHubRegistry instance can be obtained via CPCCorePlugin.getEventHubRegistry().

NOTE: Any implementation of this interface also needs to implement IManagableEventHubRegistry.

Author:

vw

See Also:

CPCCorePlugin.getEventHubRegistry(), IManagableEventHubRegistry, DefaultEventHubRegistry, IEventHubListener, CPCEvent

Method Summary

void	dispatch(CPCEvent event) Dispatch the event to all interested parties.
void	subscribe(java.lang.Class<? extends CPCEvent> eventType, boolean synchronous, byte priority, IEventHubListener listener) Deprecated. It is highly recommended to use the eventHubListeners extension point to register listeners.
boolean	unsubscribe(java.lang.Class<? extends CPCEvent> eventType, boolean synchronous, IEventHubListener listener) Unregisters a CPCEvent listener callback.

Method Detail

subscribe

@Deprecated
void subscribe(java.lang.Class<? extends CPCEvent> eventType,
                          boolean synchronous,
                          byte priority,
                          IEventHubListener listener)

Deprecated. It is highly recommended to use the eventHubListeners extension point to register listeners.

Registers a listener callback to receive CPCEvent notifications. The class hierarchy is taken into account, i.e.
subscribe(CPCEvent.class, this);
will subscribe to all events.
If a specific event class is provided, then the listener will only be registered for that event type.

Parameters:

eventType - the CPCEvent subclass for which the listener should receive notifications, never null.

synchronous - true if this listener expects events to be dispatched in a synchronous fashion. In this case the sender of the event will be blocked until all synchronous listeners have processed the event. If this is false the events are dispatched in a separate background thread.

priority - sorting attribute which affects the order in which multiple listeners registered for the same event type will be notified. Listeners are called in descending order of their priority. If multiple listeners have the same priority, the order in not specified.
Values may be negative, a good default value is 0.

listener - the listener callback, never null.

unsubscribe

boolean unsubscribe(java.lang.Class<? extends CPCEvent> eventType,
                    boolean synchronous,
                    IEventHubListener listener)

Unregisters a CPCEvent listener callback.
A programmatically subscribed listener, should always be unsubscribed once it is no longer needed.
Unsubscribing of listeners which were registered via the eventHubListeners extension point is not required.

Parameters:

eventType - the CPCEvent subclass for which the listener was originally registered, never null

synchronous - should be set to the same value as was used during subscription of this listener.

listener - the listener to remove, never null

Returns:

true if the listener was registered, false if listener was unknown

dispatch

void dispatch(CPCEvent event)

Dispatch the event to all interested parties.

The event needs to be valid, otherwise an error is logged and the event is ignored.
Events are automatically sealed once they are passed to this method.
It is up to the registered listeners whether this event is dispatched synchronously, asynchronously or both.
The caller is guaranteed to be shielded from any potential exceptions thrown by any of the listeners. An exception thrown by one listener will not affect other listeners.

The caller should try to release as many locks as possible prior to calling this method as the focus might be passed to some long running synchronous listener. If a caller absolutely must not be blocked by the event dispatching process, it should move the call to this method into a separate background thread. However, even in that case some of the then concurrently executed listeners may contend for the main UI thread.
Calling this method from the background event dispatching thread is explicitly permitted. The event dispatching order to asynchronous listeners will be correctly maintained.

An IStoreProvider exclusive write lock may only be held during event dispatching, if the specification of the CPCEvent specifically states this fact. In all other cases an event generating thread will have to queue events internally and release the IStoreProvider lock before actually dispatching them with this method.

Parameters:

event - the event to dispatch, never null

See Also:

CPCEvent.isValid(), CPCEvent.seal(), IEventHubListener