net.sf.eBus.client

Class EMultiSubscribeFeed

java.lang.Object

net.sf.eBus.client.EFeed

net.sf.eBus.client.EMultiFeed<ENotificationMessage,ESubscribeFeed>

net.sf.eBus.client.EMultiSubscribeFeed

All Implemented Interfaces:

IEFeed, IESubscribeFeed

public final class EMultiSubscribeFeed
extends EMultiFeed<ENotificationMessage,ESubscribeFeed>
implements IESubscribeFeed

This feeds acts as a proxy for handling multiple ESubscribeFeeds on behalf of a ESubscriber client. A subscriber opens a multi-key subscribe feed for a specified notification message class and zero or more message subjects. There subjects may be specified as a list or a regular expression query If a query is used, then the message class and subject query are used to to search the message key dictionary for all matching subjects. The matching subjects are used to create the initial subordinate ESubjectFeeds.

The multi-key subscribe feed coordinates the subordinate subscribe feeds to they are given the same configuration and are in the same state (open, subscribed, un-subscribed, closed).

While the multi-key feed is open, new subordinate subscribe feeds may be added to or removed from the multi-key feed. Newly added subordinate feeds are configured and put into the same state as the existing subordinate feeds.

Author:

Charles W. Rapp

Nested Class Summary

Nested classes/interfaces inherited from class net.sf.eBus.client.EMultiFeed

EMultiFeed.MultiFeedFactory<M extends EMultiFeed,C extends EMessage,F extends EFeed>, EMultiFeed.SubordinateFeedFactory<R extends EObject,F extends net.sf.eBus.client.ESingleFeed>

Nested classes/interfaces inherited from class net.sf.eBus.client.EFeed

EFeed.AbstractClientTask, EFeed.FeedScope, EFeed.NotifyTask, EFeed.StatusTask<T extends IEFeed>

Field Summary

Fields inherited from class net.sf.eBus.client.EMultiFeed

mCondition, mFeeds, mMsgClass, MULTIFEED_SUBJECT, sLogger

Fields inherited from class net.sf.eBus.client.EFeed

mEClient, mFeedId, mFeedState, mInPlace, mIsActive, mScope, NO_CONDITION, NOTIFY_METHOD

Method Summary

Modifier and Type	Method and Description
protected ESubscribeFeed	createFeed(EMessageKey key) Returns a newly minted subordinate subscribe feed for the given key.
void	notifyCallback(NotifyCallback cb) Puts the notification message callback in place.
static EMultiSubscribeFeed	open(ESubscriber client, Class<? extends ENotificationMessage> mc, List<String> subjects, EFeed.FeedScope scope, ECondition condition) Returns an open multi-key subscribe feed for the given notification message class and multiple subjects.
static EMultiSubscribeFeed	open(ESubscriber client, Class<? extends ENotificationMessage> mc, Pattern query, EFeed.FeedScope scope, ECondition condition) Returns an open multi-key subscribe feed for a given notification message class and multiple message subjects.
protected void	putFeedInPlace(ESubscribeFeed feed) Sets the callbacks and subscribes the feed.
void	statusCallback(FeedStatusCallback<IESubscribeFeed> cb) Puts the feed status callback in place.
void	subscribe() Subscribes each subordinate ESubscribeFeed.
void	unsubscribe() Retracts this multi-key subscribe feed by un-subscribing each subordinate subscribe feed.

Methods inherited from class net.sf.eBus.client.EMultiFeed

addAllFeeds, addAllFeeds, addFeed, closeFeed, feedState, inactivate, isFeedUp, key, keys, messageClass, openList, openQuery, subjects

Methods inherited from class net.sf.eBus.client.EFeed

addAllKeys, addKey, checkScopes, clientId, close, defaultDispatcher, eClient, equals, feedId, feedState, findKeys, findKeys, findKeys, hashCode, inPlace, isActive, isOverridden, loadKeys, location, register, register, register, scope, shutdown, shutdown, shutdownAll, startup, startup, startupAll, storeKeys, storeKeys, storeKeys, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.sf.eBus.client.IEFeed

close, eClient, feedId, inPlace, isActive, isFeedUp, key, scope

Method Detail

statusCallback

public void statusCallback(FeedStatusCallback<IESubscribeFeed> cb)

Puts the feed status callback in place. If cb is not null, feed status updates will be passed to cb rather than ESubscriber.feedStatus(EFeedState, IESubscribeFeed). The reverse is true if cb is null. That is, a null cb means feed status updates are posted to the ESubscriber.feedStatus(EFeedState, IESubscribeFeed) override.

The status callback is applied to all subordinate ESubscribeFeeds. This means that each subordinate feed calls back the same method.

Specified by:

statusCallback in interface IESubscribeFeed

Parameters:

cb - the feed status update callback. May be null.

Throws:

IllegalStateException - if this feed is either closed or subscribed.

notifyCallback

public void notifyCallback(NotifyCallback cb)

Puts the notification message callback in place. If cb is not null, then notification messages will be passed to cb rather than ESubscriber.notify(ENotificationMessage, IESubscribeFeed). A null cb means that notification messages will be passed to the ESubscriber.notify(ENotificationMessage, IESubscribeFeed) override.

The notify callback is applied to all subordinate ESubscribeFeeds. This means that each subordinate feed passes inbound notification messages to the same method.

Specified by:

notifyCallback in interface IESubscribeFeed

Parameters:

cb - pass notification messages back to application via this callback.

Throws:

IllegalStateException - if this feed is either closed or subscribed.

subscribe

public void subscribe()

Subscribes each subordinate ESubscribeFeed. If this feed is currently subscribed, then does nothing. The subscriber client will receive a ESubscriber.feedStatus(EFeedState, IESubscribeFeed) callback from each subordinate subscribe feed.

Specified by:

subscribe in interface IESubscribeFeed

Throws:

IllegalStateException - if this feed is closed or the client did not override ESubscriber methods nor put the required callback in place.

See Also:

unsubscribe(), EFeed.close()

unsubscribe

public void unsubscribe()

Retracts this multi-key subscribe feed by un-subscribing each subordinate subscribe feed. Does nothing if this feed is not currently subscribed.

Specified by:

unsubscribe in interface IESubscribeFeed

Throws:

IllegalStateException - if this multi-key subscribe feed is closed.

See Also:

subscribe(), EFeed.close()

createFeed

protected ESubscribeFeed createFeed(EMessageKey key)

Returns a newly minted subordinate subscribe feed for the given key.

Specified by:

createFeed in class EMultiFeed<ENotificationMessage,ESubscribeFeed>

Parameters:

key - create feed for this key.

Returns:

a subordinate subscribe feed.

putFeedInPlace

protected void putFeedInPlace(ESubscribeFeed feed)

Sets the callbacks and subscribes the feed.

Specified by:

putFeedInPlace in class EMultiFeed<ENotificationMessage,ESubscribeFeed>

Parameters:

feed - subscribe this feed.

open

public static EMultiSubscribeFeed open(ESubscriber client,
                                       Class<? extends ENotificationMessage> mc,
                                       List<String> subjects,
                                       EFeed.FeedScope scope,
                                       ECondition condition)

Returns an open multi-key subscribe feed for the given notification message class and multiple subjects. Once opened, the caller can (optionally) set the status and notify callbacks and subscribe the feed just like ESubscribeFeed.

Note: client receives callbacks for each subordinate ESubscribeFeed as if it opened all those feeds directly. If keys contains a large number of notification message keys, then client must be prepared for feed status and notify callbacks for each of the subordinate subscribe feeds.

subjects may be a non-null, empty list resulting in no initial subordinate subscribe feeds opened. This allows the subscriber to start with an empty multi-key subscriber feed, adding subordinate feeds later.

Parameters:

client - the application object publishing the notification message class and subject.

mc - notification message class. All feeds apply to this message class.

subjects - list of notification message subjects. May not contain null or empty strings.

scope - whether the feed supports local feeds, remote feeds, or both.

condition - accept notification messages only if the messages passes this condition. May be null. If null, then the default condition which accepts all messages is used.

Returns:

a new multiple key subscribe feed for the given application object and notification message keys.

Throws:

NullPointerException - if any of the required arguments is null.

IllegalArgumentException - if subjects contains an empty string.

See Also:

open(ESubscriber, Class, Pattern, EFeed.FeedScope, ECondition), statusCallback(FeedStatusCallback), notifyCallback(NotifyCallback), subscribe(), EMultiFeed.addFeed(String), EMultiFeed.closeFeed(String), EFeed.close()

open

public static EMultiSubscribeFeed open(ESubscriber client,
                                       Class<? extends ENotificationMessage> mc,
                                       Pattern query,
                                       EFeed.FeedScope scope,
                                       ECondition condition)

Returns an open multi-key subscribe feed for a given notification message class and multiple message subjects. Once opened, the caller can (optionally) set the status and notify callbacks and subscribe the feed just like ESubscribeFeed.

The subordinate subscribe feeds are selected based on the given notification message class and the regular expression query. The multi-key subscribe feed is opened whether the message key dictionary entries match the message class and subject query or not. In either case, the application may add more subordinate feeds to the returned multi-key feed.

Note: client receives callbacks from subordinate ESubscribeFeed feeds, not the multi-key feed. If mc and query match 1,000 notification message keys, then client will receive feed status and notify callbacks from those 1,000 subordinate feeds.

Parameters:

client - application object subscribing to the notification message class and matching subjects.

mc - the message key query is for this notification message class only.

query - message key subject query.

scope - whether the feed supports local feeds, remote feeds, or both.

condition - accept notification messages only if the messages passes this condition. May be null. If null, then the default condition which accepts all messages is used.

Returns:

a new multiple key subscribe feed for the given application object and notification message keys matching the notification message class and query.

Throws:

NullPointerException - if any of the arguments are null.

IllegalArgumentException - if any of the arguments is invalid.

See Also:

open(ESubscriber, Class, List, EFeed.FeedScope, ECondition), statusCallback(FeedStatusCallback), notifyCallback(NotifyCallback), EMultiFeed.addFeed(String), EMultiFeed.closeFeed(String), subscribe(), EFeed.close()