fulmine.event.subscription
Interface ISubscriptionManager

All Superinterfaces:

IDestroyable, ILifeCycle

All Known Subinterfaces:

IChannel

All Known Implementing Classes:

Channel, ContainerSubscriptionManager, RemoteContainerSubscriptionManager, SubscriptionManager

public interface ISubscriptionManager
extends ILifeCycle

Manages subscriptions for the IEvent events generated by IEventSource instances. The subscriptions are encapsulated in ISubscription instances. Subscription requests are issued to the manager using an ISubscriptionParameters object that defines what event sources to subscribe for. This is also the key used to store the ISubscription instance.

Once a subscription instance is created, any number of listeners ( IEventListener instances) can be associated with it via the addListener(ISubscriptionParameters, IEventListener) method. When a listener is added to the subscription, the subscription will register the listener with any currently subscribed event sources.

Subscription match processing occurs when the subscription is issued and continues until the subscription is cancelled. This allows subscriptions for event sources not yet created to be issued. When the event source is created, the utility method eventSourceCreated(IAddressable) should be called and the subscriptions registered with the manager are checked for a match against the created source.

Author:

Ramon Servadei

Method Summary

boolean	addListener(ISubscriptionParameters parameters, IEventListener listener) Add the listener to the IEventListener instances associated with the ISubscription represented by the parameters.
void	eventSourceCreated(IAddressable identity) Method to invoke when a new IEventSource is created.
void	eventSourceDestroyed(IAddressable identity) Method to invoke when an IEventSource is destroyed.
List<IEventListener>	getListeners(ISubscriptionParameters parameters) Get a copy of the IEventListener instances that have been added to the subscription identified by the parameters.
Collection<IEventSource>	getSubscribedSources() Get a copy of the Collection of all the event sources that are currently subscribed for.
Collection<IEventSource>	getSubscribedSources(ISubscriptionParameters parameters) Get a copy of the Collection of the currently subscribed event sources that are matched by the subscription parameters.
boolean	includes(IAddressable parameters) Determine if there is at least one ISubscription instance whose subscription parameters include the parameters passed in.
boolean	isSubscribed(IEventSource source) Determine if there is at least one ISubscription that has a match reference for the event source.
boolean	removeListener(ISubscriptionParameters parameters, IEventListener listener) Remove the listener from the IEventListener instances associated with the ISubscription represented by the parameters.
boolean	subscribe(ISubscriptionParameters parameters) Create an ISubscription for the event source(s) represented in the subscription parameters.
boolean	unsubscribe(ISubscriptionParameters parameters) Remove the subscription represented by the parameters.

Methods inherited from interface fulmine.ILifeCycle

isActive, start

Methods inherited from interface fulmine.IDestroyable

destroy

Method Detail

subscribe

boolean subscribe(ISubscriptionParameters parameters)

Create an ISubscription for the event source(s) represented in the subscription parameters. The created subscription is keyed against the parameters argument.

This is an idempotent operation.

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

true if the subscription was created, false if it already existed

See Also:

getSubscribedSources(ISubscriptionParameters), unsubscribe(ISubscriptionParameters)

unsubscribe

boolean unsubscribe(ISubscriptionParameters parameters)

Remove the subscription represented by the parameters. The subscription is found by looking it up against the parameters as its key.

This unregisters the listener(s) associated with the subscription from the event source(s) that the subscription matched and destroys the associated ISubscription instance.

This is an idempotent operation.

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

true if a subscription was found, false otherwise

See Also:

getSubscribedSources(ISubscriptionParameters), subscribe(ISubscriptionParameters)

addListener

boolean addListener(ISubscriptionParameters parameters,
                    IEventListener listener)

Add the listener to the IEventListener instances associated with the ISubscription represented by the parameters. The subscription is found using the same lookup semantics as #getSubscription(ISubscriptionParameters).

On adding, the subscription will register the listener with any currently matched IEventSource instances.

This is an idempotent operation.

Parameters:

parameters - the subscription parameters identifying the subscription

listener - the listener to add to the subscription's list of listeners

Returns:

true if the listener was added, false if it already existed

removeListener

boolean removeListener(ISubscriptionParameters parameters,
                       IEventListener listener)

Remove the listener from the IEventListener instances associated with the ISubscription represented by the parameters. The subscription is found using the same lookup semantics as #getSubscription(ISubscriptionParameters).

On removal, the subscription will unregister the listener from any currently matched IEventSource instances.

This is an idempotent operation.

Parameters:

parameters - the subscription parameters identifying the subscription

listener - the listener to remove from the subscription's list of listeners

Returns:

true if the listener was removed, false if it was not found

getSubscribedSources

Collection<IEventSource> getSubscribedSources()

Get a copy of the Collection of all the event sources that are currently subscribed for.

Returns:

a copy of the Collection of all the event source instances that are currently subscribed for

getSubscribedSources

Collection<IEventSource> getSubscribedSources(ISubscriptionParameters parameters)

Get a copy of the Collection of the currently subscribed event sources that are matched by the subscription parameters.

This does a matching operation to find any other ISubscriptions that would include these parameters and then adds the IEventSources to the collection to return.

This is not a key lookup operation.

Parameters:

parameters - the subscription parameters to match against event sources currently subscribed for

Returns:

a copy of the Collection of the event sources currently subscribed for and that are matched by the subscription parameters argument

isSubscribed

boolean isSubscribed(IEventSource source)

Determine if there is at least one ISubscription that has a match reference for the event source.

This checks if the event source is already subscribed. To find out if this source would be subscribed, use #includes(ISubscriptionParameters).

Parameters:

source - the event source to check for at least one subscription within this manager

Returns:

true if the source is found in at least one subscription within this manager

includes

boolean includes(IAddressable parameters)

Determine if there is at least one ISubscription instance whose subscription parameters include the parameters passed in.

This operation is not a key lookup and will search through all subscriptions until one is found that would include the parameters.

Parameters:

parameters - the parameters to check

Returns:

true if there is at least one subscription instance that includes the parameters

See Also:

ISubscriptionParameters.includes(IAddressable)

eventSourceCreated

void eventSourceCreated(IAddressable identity)

Method to invoke when a new IEventSource is created. This provides the manager with the mechanism to be notified when event sources are created and go through existing subscriptions to identify if the new event source should be subscribed for.

Parameters:

identity - identifies the attributes of the created event source

eventSourceDestroyed

void eventSourceDestroyed(IAddressable identity)

Method to invoke when an IEventSource is destroyed. Complimentary to eventSourceCreated(IAddressable).

Parameters:

identity - identifies the attributes of the destroyed event source

getListeners

List<IEventListener> getListeners(ISubscriptionParameters parameters)

Get a copy of the IEventListener instances that have been added to the subscription identified by the parameters. The subscription is found using a key lookup operation; the subscription is found by association with the parameters.

This operation performs no semantic matching with wildcards, it is a key lookup operation.

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

the list of IEventListener instances for the identified subscription or Collections.emptyList()