fulmine.event.subscription
Interface ISubscription

All Superinterfaces:

IAddressable, IDestroyable, ISubscriptionParameters

All Known Implementing Classes:

ContainerSubscription, RxSubscription, Subscription, TxSubscription

public interface ISubscription
extends IDestroyable, ISubscriptionParameters

Encapsulates a single subscription for IEventSource instances. The subscription has a collection of IEventListener instances that are registered as listeners against all event sources that are matched by the subscription. The subscription also stores references to all matching event sources.

A subscription operates with an ISubscriptionManager. The manager uses the subscription to determine if it would match an event source and, if it does, the manager adds the event source as a match reference. On adding, the subscription registers its listeners against the event source.

Subscriptions are defined by an ISubscriptionParameters instance that identifies that type, domain and identity attributes of matching event sources. A subscription can match the attributes exactly or use wildcards. The wildcard match for the type or domain can be specified using WILDCARD_TYPE and WILDCARD_DOMAIN . The identity specified for a subscription is a regular expression matching one or more event source identities.

Author:

Ramon Servadei

Field Summary

static IDomain	WILDCARD_DOMAIN Wildcard for domain subscriptions; this allows any domain to be matched by a subscription.
static String	WILDCARD_ID_REGEX Wildcard for identity subscriptions; this allows any identity to be matched by a subscription.
static IType	WILDCARD_TYPE Wildcard for type subscriptions; this allows any type to be matched by a subscription.

Method Summary

boolean	addListener(IEventListener listener) Add the listener to the IEventListener instances associated with this ISubscription.
boolean	addMatch(IEventSource source) Add the event source as a matched reference.
List<IEventListener>	getListeners() Get a copy of the internal List of all the IEventListener instances used by the subscription to register against the subscribed IEventSource instances.
Collection<IEventSource>	getMatches() Get a copy of the internal Collection of all the IEventSource instances referenced by this subscription.
boolean	removeListener(IEventListener listener) Remove the listener from the IEventListener instances associated with this ISubscription.
boolean	removeMatch(ISubscriptionParameters parameters) Remove the event source(s) identified by the parameters from this subscription's matched references.

Methods inherited from interface fulmine.event.subscription.ISubscriptionParameters

includes

Methods inherited from interface fulmine.IAddressable

getAddress, getDomain, getIdentity, getType

Field Detail

WILDCARD_ID_REGEX

static final String WILDCARD_ID_REGEX

Wildcard for identity subscriptions; this allows any identity to be matched by a subscription.

See Also:

Constant Field Values

WILDCARD_TYPE

static final IType WILDCARD_TYPE

Wildcard for type subscriptions; this allows any type to be matched by a subscription.

WILDCARD_DOMAIN

static final IDomain WILDCARD_DOMAIN

Wildcard for domain subscriptions; this allows any domain to be matched by a subscription.

Method Detail

addMatch

boolean addMatch(IEventSource source)

Add the event source as a matched reference.

The source is only added if the subscription does not already contain the source as a match.

This is an idempotent operation.

Parameters:

source - the event source

Returns:

true if the event source was added, false if the subscription already has the source as a matched reference

removeMatch

boolean removeMatch(ISubscriptionParameters parameters)

Remove the event source(s) identified by the parameters from this subscription's matched references.

Note: if the parameters include wildcards, multiple event sources may be removed.

Parameters:

parameters - the subscription parameters identifying any matching event sources to remove

Returns:

true if at least one event source was found and removed, false if no event source was found to remove

getMatches

Collection<IEventSource> getMatches()

Get a copy of the internal Collection of all the IEventSource instances referenced by this subscription. The order of the collection elements is arbitrary.

Returns:

a copy of the collection of all IEventSource instances referenced by this subscription

getListeners

List<IEventListener> getListeners()

Get a copy of the internal List of all the IEventListener instances used by the subscription to register against the subscribed IEventSource instances.

Returns:

a copy of the internal List of all the listeners that are registered against all subscribed IEventSource instances. The order of the listeners is the order of calling addListener(IEventListener).

removeListener

boolean removeListener(IEventListener listener)

Remove the listener from the IEventListener instances associated with this ISubscription. The subscription will remove the listener from any currently matched IEventSource instances.

This is an idempotent operation.

Parameters:

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

addListener

boolean addListener(IEventListener listener)

Add the listener to the IEventListener instances associated with this ISubscription. The subscription will register the listener with any currently matched IEventSource instances.

This is an idempotent operation.

Parameters:

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

Returns:

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