fulmine.event.subscription
Class SubscriptionManager

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.event.subscription.SubscriptionManager

All Implemented Interfaces:

ISubscriptionManager, IDestroyable, ILifeCycle

Direct Known Subclasses:

ContainerSubscriptionManager

public abstract class SubscriptionManager
extends AbstractLifeCycle
implements ISubscriptionManager

Base implementation of a subscription manager.

This is thread safe. Access on the internal collection of ISubscription instances is synchronized just enough to get the subscription. The subscription implementations are assumed to be thread safe.

Author:

Ramon Servadei

Constructor Summary

SubscriptionManager(IFrameworkContext context, ISubscriptionFactory factory)
Standard constructor

Method Summary

boolean	addListener(ISubscriptionParameters parameters, IEventListener listener) Add the listener to the IEventListener instances associated with the ISubscription represented by the parameters.
protected abstract void	doAddListener(ISubscriptionParameters parameters, IEventListener listener) Called as the final step in addListener(ISubscriptionParameters, IEventListener).
protected void	doDestroy() Overridden in subclasses to perform custom logic on destruction.
protected abstract void	doEventSourceCreated(IAddressable id) Called as the final step in the eventSourceCreated(IAddressable) method.
protected abstract boolean	doEventSourceExists(IAddressable id) Template method to identify if the IEventSource identified by the IAddressable argument exists.
protected abstract IEventSource	doGetEventSource(IAddressable id) Template method to get the IEventSource identified by the IAddressable argument.
protected abstract Collection<? extends IEventSource>	doGetEventSources() Template method to get the collection of IEventSource instances the manager will operate over.
protected void	doRaiseSubscribeEvent(ISubscriptionParameters parameters)
protected void	doRaiseUnsubscribeEvent(ISubscriptionParameters 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.
protected IFrameworkContext	getContext()
List<IEventListener>	getListeners(ISubscriptionParameters parameters) Get a copy of the IEventListener instances that have been added to the subscription identified by the parameters.
protected AsyncLog	getLog() Get the log to use for the object hierarchy
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.
protected ISubscription	getSubscription(ISubscriptionParameters parameters)
protected Map<ISubscriptionParameters,ISubscription>	getSubscriptions() Get the current subscriptions parameters to subscription.
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.
String	toString()
boolean	unsubscribe(ISubscriptionParameters parameters) Remove the subscription represented by the parameters.

Methods inherited from class fulmine.AbstractLifeCycle

checkActive, destroy, doStart, finalize, isActive, start

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface fulmine.ILifeCycle

isActive, start

Methods inherited from interface fulmine.IDestroyable

destroy

Constructor Detail

SubscriptionManager

public SubscriptionManager(IFrameworkContext context,
                           ISubscriptionFactory factory)

Standard constructor

Parameters:

context - the context to use

factory - the container subscription factory to use

Method Detail

subscribe

public final boolean subscribe(ISubscriptionParameters parameters)

Description copied from interface: ISubscriptionManager

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.

Specified by:

subscribe in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

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

See Also:

ISubscriptionManager.getSubscribedSources(ISubscriptionParameters), ISubscriptionManager.unsubscribe(ISubscriptionParameters)

getSubscription

protected final ISubscription getSubscription(ISubscriptionParameters parameters)

addListener

public final boolean addListener(ISubscriptionParameters parameters,
                                 IEventListener listener)

Description copied from interface: ISubscriptionManager

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.

Specified by:

addListener in interface ISubscriptionManager

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

public final boolean removeListener(ISubscriptionParameters parameters,
                                    IEventListener listener)

Description copied from interface: ISubscriptionManager

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.

Specified by:

removeListener in interface ISubscriptionManager

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

getListeners

public final List<IEventListener> getListeners(ISubscriptionParameters parameters)

Description copied from interface: ISubscriptionManager

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.

Specified by:

getListeners in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

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

unsubscribe

public final boolean unsubscribe(ISubscriptionParameters parameters)

Description copied from interface: ISubscriptionManager

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.

Specified by:

unsubscribe in interface ISubscriptionManager

Parameters:

parameters - the subscription parameters identifying the subscription

Returns:

true if a subscription was found, false otherwise

See Also:

ISubscriptionManager.getSubscribedSources(ISubscriptionParameters), ISubscriptionManager.subscribe(ISubscriptionParameters)

isSubscribed

public final boolean isSubscribed(IEventSource source)

Description copied from interface: ISubscriptionManager

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).

Specified by:

isSubscribed in interface ISubscriptionManager

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

getSubscribedSources

public final Collection<IEventSource> getSubscribedSources(ISubscriptionParameters parameters)

Description copied from interface: ISubscriptionManager

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.

Specified by:

getSubscribedSources in interface ISubscriptionManager

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

getSubscribedSources

public final Collection<IEventSource> getSubscribedSources()

Description copied from interface: ISubscriptionManager

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

Specified by:

getSubscribedSources in interface ISubscriptionManager

Returns:

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

includes

public final boolean includes(IAddressable parameters)

Description copied from interface: ISubscriptionManager

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.

Specified by:

includes in interface ISubscriptionManager

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

public final void eventSourceCreated(IAddressable identity)

Description copied from interface: ISubscriptionManager

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.

Specified by:

eventSourceCreated in interface ISubscriptionManager

Parameters:

identity - identifies the attributes of the created event source

eventSourceDestroyed

public void eventSourceDestroyed(IAddressable identity)

Description copied from interface: ISubscriptionManager

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

Specified by:

eventSourceDestroyed in interface ISubscriptionManager

Parameters:

identity - identifies the attributes of the destroyed event source

doRaiseSubscribeEvent

protected void doRaiseSubscribeEvent(ISubscriptionParameters parameters)

doRaiseUnsubscribeEvent

protected void doRaiseUnsubscribeEvent(ISubscriptionParameters parameters)

getSubscriptions

protected final Map<ISubscriptionParameters,ISubscription> getSubscriptions()

Get the current subscriptions parameters to subscription. Accessing this must be synchronized

Returns:

the map of subscriptions parameters to subscriptions.

doGetEventSources

protected abstract Collection<? extends IEventSource> doGetEventSources()

Template method to get the collection of IEventSource instances the manager will operate over.

Returns:

a collection of IEventSource instances

doGetEventSource

protected abstract IEventSource doGetEventSource(IAddressable id)

Template method to get the IEventSource identified by the IAddressable argument.

Parameters:

id - identifies the event source

Returns:

the IEventSource implementation to use

doEventSourceExists

protected abstract boolean doEventSourceExists(IAddressable id)

Template method to identify if the IEventSource identified by the IAddressable argument exists.

Parameters:

id - identifies the event source

Returns:

true if the container exists in the current context scope

doEventSourceCreated

protected abstract void doEventSourceCreated(IAddressable id)

Called as the final step in the eventSourceCreated(IAddressable) method. This provides sub-classes with an opportunity to perform any post creation work.

Parameters:

identity - identifies the event source

doAddListener

protected abstract void doAddListener(ISubscriptionParameters parameters,
                                      IEventListener listener)

Called as the final step in addListener(ISubscriptionParameters, IEventListener). Sub-classes can perform necessary closure work when the listener is added.

Parameters:

parameters - the subscription parameters identifying the subscripion(s)

listener - the listener added

doDestroy

protected void doDestroy()

Description copied from class: AbstractLifeCycle

Overridden in subclasses to perform custom logic on destruction. Any exceptions should be thrown as a RuntimeException or subclass thereof.

Specified by:

doDestroy in class AbstractLifeCycle

getLog

protected AsyncLog getLog()

Description copied from class: AbstractLifeCycle

Get the log to use for the object hierarchy

Overrides:

getLog in class AbstractLifeCycle

Returns:

the log to use for the object hierarchy

getContext

protected IFrameworkContext getContext()

toString

public final String toString()

Overrides:

toString in class AbstractLifeCycle