net.sf.eBus.client

Class EMultiFeed<C extends EMessage,F extends net.sf.eBus.client.ESingleFeed>

java.lang.Object

net.sf.eBus.client.EFeed

net.sf.eBus.client.EMultiFeed<C,F>

Type Parameters:

C - all feeds are for this message type.

F - the subordinate feed type.

All Implemented Interfaces:

IEFeed

Direct Known Subclasses:

EMultiPublishFeed, EMultiReplyFeed, EMultiRequestFeed, EMultiSubscribeFeed

public abstract class EMultiFeed<C extends EMessage,F extends net.sf.eBus.client.ESingleFeed>
extends EFeed

Multiple key feeds act as a proxy between application objects and multiple subordinate simple feeds (EPublishFeed, ESubscribeFeed, EReplyFeed, and ERequestFeed), all for a single message class. The multi-key feed keeps the subordinate feeds in the same state: open, advertised/subscribed, or closed. The subordinate feeds are configured with the same eBus client and callback methods.

This base class tracks all currently open subordinate feeds and the overall feed state.

Author:

Charles W. Rapp

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static interface	EMultiFeed.MultiFeedFactory<M extends EMultiFeed,C extends EMessage,F extends EFeed> This interface is used by EMultiFeed to instantiate a new multi-key, sub-class feed.
protected static interface	EMultiFeed.SubordinateFeedFactory<R extends EObject,F extends net.sf.eBus.client.ESingleFeed> This interface is used by EMultiFeed to instantiate a new subordinate feed for a multi-key feed.

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

Modifier and Type	Field and Description
protected ECondition	mCondition Use this condition to check if received message should be forwarded to client.
protected Map<CharSequence,F>	mFeeds Contains the subordinate feeds currently opened by this multi-key feed.
protected Class<? extends C>	mMsgClass All subordindate feeds apply to this message class.
static String	MULTIFEED_SUBJECT key() returns a message key with the subject "__MULTIFEED__".
protected static Logger	sLogger Logging subsystem interface.

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

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EMultiFeed(EClient client, Class<? extends C> msgClass, EFeed.FeedScope scope, ECondition condition, Map<CharSequence,F> feeds) Creates a new multiple key feed for the given eBus client, message class, scope, and initial feeds.

Method Summary

Modifier and Type	Method and Description
void	addAllFeeds(List<String> subjects) Adds new feeds based on the configured message class and the subjects list.
void	addAllFeeds(Pattern query) Adds new feeds for each of the subjects matching the given query.
void	addFeed(String subject) Adds a new feed based on the configured message class and the given subject.
void	closeFeed(String subject) Removes and closes the feed for the given message subject.
protected abstract F	createFeed(EMessageKey key) Returns a newly minted subordinate feed for the given message key.
EFeedState	feedState(String subject) Returns the specified feed's state.
protected void	inactivate() Closes all currently open subordinate feeds and clears the feeds map.
boolean	isFeedUp() Returns true if all subordinate feeds are up and false otherwise.
EMessageKey	key() Returns a message key with messageClass() as the class and MULTIFEED_SUBJECT as the subject.
List<EMessageKey>	keys() Returns the current subordinate feed message keys.
Class<? extends C>	messageClass() Returns the multi-key feed message class.
protected static <R extends EObject,C extends EMessage,F extends net.sf.eBus.client.ESingleFeed,M extends EMultiFeed<C,F>> M	openList(R client, Class<? extends C> mc, List<String> subjects, EFeed.FeedScope scope, ECondition condition, EMultiFeed.SubordinateFeedFactory<R,F> subFactory, EMultiFeed.MultiFeedFactory<M,C,F> multiFactory) Returns a new, opened multi-key feed for the given parameters.
protected static <R extends EObject,C extends EMessage,F extends net.sf.eBus.client.ESingleFeed,M extends EMultiFeed<C,F>> M	openQuery(R client, Class<? extends C> mc, Pattern query, EFeed.FeedScope scope, ECondition condition, EMultiFeed.SubordinateFeedFactory<R,F> subFactory, EMultiFeed.MultiFeedFactory<M,C,F> multiFactory) Returns a new, opened multi-key feed for the given message class and subject regular expression query.
protected abstract void	putFeedInPlace(F feed) Advertises/subscribes the given feed.
List<String>	subjects() Returns the current subordinate feed message 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

Field Detail

MULTIFEED_SUBJECT

public static final String MULTIFEED_SUBJECT

key() returns a message key with the subject "__MULTIFEED__".

See Also:

Constant Field Values

sLogger

protected static final Logger sLogger

Logging subsystem interface. Shared by all subclasses.

mMsgClass

protected final Class<? extends C extends EMessage> mMsgClass

All subordindate feeds apply to this message class. This message class is used when adding new feeds to this multi-key feed.

mCondition

protected final ECondition mCondition

Use this condition to check if received message should be forwarded to client. This condition is applied to all subordinate feeds which use conditions. This data member is null if the subordinate feed does not support message condition.

mFeeds

protected final Map<CharSequence,F extends net.sf.eBus.client.ESingleFeed> mFeeds

Contains the subordinate feeds currently opened by this multi-key feed. Maps the EMessageKey.subject() to the subordinate feed.

Constructor Detail

EMultiFeed

protected EMultiFeed(EClient client,
                     Class<? extends C> msgClass,
                     EFeed.FeedScope scope,
                     ECondition condition,
                     Map<CharSequence,F> feeds)

Creates a new multiple key feed for the given eBus client, message class, scope, and initial feeds. Subordinate feeds use the same client, msgClass, scope, and (optionally) condition.

Parameters:

client - connect this client to the subordinate feeds.

msgClass - all feeds apply to this message class.

scope - feed scope.

feeds - initial subordinate feeds.

condition - condition applied to all subordinate feeds. Will be null for feeds which do not use a condition.

Method Detail

createFeed

protected abstract F createFeed(EMessageKey key)

Returns a newly minted subordinate feed for the given message key. This method is used by addFeed(String) to create a subordinate feed.

Parameters:

key - create feed for this key.

Returns:

a subordinate feed.

putFeedInPlace

protected abstract void putFeedInPlace(F feed)

Advertises/subscribes the given feed. This method is used by addFeed(String) to adverise/subscribe the added feed.

Parameters:

feed - feed to advertised/subscribed.

inactivate

protected final void inactivate()

Closes all currently open subordinate feeds and clears the feeds map.

Specified by:

inactivate in class EFeed

messageClass

public final Class<? extends C> messageClass()

Returns the multi-key feed message class. All added feeds are created with this class.

Returns:

feed message class.

isFeedUp

public final boolean isFeedUp()

Returns true if all subordinate feeds are up and false otherwise.

Specified by:

isFeedUp in interface IEFeed

Overrides:

isFeedUp in class EFeed

Returns:

true if all subordinate feeds are up.

key

public final EMessageKey key()

Returns a message key with messageClass() as the class and MULTIFEED_SUBJECT as the subject.

Returns:

multi-feed message key.

feedState

public final EFeedState feedState(String subject)

Returns the specified feed's state. A down state means that messages may not be sent on or received from this feed. An up state means that messages may possibly be sent on or received from this feed.

If subject references an unknown feed or the feed is not in place, then EFeedState.UNKNOWN is returned.

Parameters:

subject - return the publish state for this message subject.

Returns:

the specified feed's state or UNKNOWN if subject does not reference a known feed.

Throws:

NullPointerException - if subject is null.

IllegalArgumentException - if subject is empty.

IllegalStateException - if this multi-key feed is closed.

subjects

public final List<String> subjects()

Returns the current subordinate feed message subjects. The returned list is a copy of the actual message subjects list. Modifying the returned list has no impact on eBus operations.

Returns:

subordinate feed message subjects.

Throws:

IllegalStateException - if this multi-key feed is closed.

keys

public final List<EMessageKey> keys()

Returns the current subordinate feed message keys. The returned list is a copy of the actual message key list. Modifying the returned list has no impact on eBus operations.

Returns:

subordinate feed message keys.

Throws:

IllegalStateException - if this multi-key feed is closed.

addFeed

public final void addFeed(String subject)

Adds a new feed based on the configured message class and the given subject. If this multi-key feed is advertised or subscribed, then the new subordinate feed is advertised/subscribed. This method does nothing if there is a subordinate feed for subject in place.

The newly created feed references the same client, message class, scope and (optional) condition as all the other subordinate feeds in this multi-key feed. It will also use the same callbacks as existing subordinate feeds.

Parameters:

subject - add key with this message subject.

Throws:

NullPointerException - if subject is null.

IllegalArgumentException - if subject is empty.

IllegalStateException - if this multi-key feed is closed.

See Also:

addAllFeeds(List), addAllFeeds(Pattern), closeFeed(String)

addAllFeeds

public final void addAllFeeds(List<String> subjects)

Adds new feeds based on the configured message class and the subjects list. If this multi-key feed is in place (advertised or subscribed), then the new subordinate feeds are put in place as well. If subjects contains feeds that already exist, the existing feed is neither replaced or modified.

The newly created feeds reference the same client, message class, scope and (optional) condition as all the other subordinate feeds in this multi-key feed. They will also use the same callbacks as existing subordinate feeds.

Parameters:

subjects - create new feeds for these subjects.

Throws:

NullPointerException - if subjects is null or contains a null element.

IllegalArgumentException - if subjects contains an empty string.

IllegalStateException - if this multi-key feed is closed.

See Also:

addFeed(String), addAllFeeds(Pattern), closeFeed(String)

addAllFeeds

public final void addAllFeeds(Pattern query)

Adds new feeds for each of the subjects matching the given query. If there are no matching subjects, then no feeds are added. If query matches an existing feed subject, then the existing feed is neither modified not replaced. The new feeds are for this multi-key feed's message class.

Parameters:

query - find all subjects matching this query.

Throws:

NullPointerException - if query is null.

IllegalStateException - if this multi-key feed is closed.

See Also:

addFeed(String), addAllFeeds(List), closeFeed(String)

closeFeed

public final void closeFeed(String subject)

Removes and closes the feed for the given message subject. Does nothing if subject does not reference a known subordinate feed.

Parameters:

subject - remove and close the feed for this subject.

Throws:

NullPointerException - if subject is null.

IllegalArgumentException - if subject is empty.

IllegalStateException - if this multi-key feed is closed.

See Also:

addFeed(String)

openList

protected static <R extends EObject,C extends EMessage,F extends net.sf.eBus.client.ESingleFeed,M extends EMultiFeed<C,F>> M openList(R client,
                                                                                                                                      Class<? extends C> mc,
                                                                                                                                      List<String> subjects,
                                                                                                                                      EFeed.FeedScope scope,
                                                                                                                                      ECondition condition,
                                                                                                                                      EMultiFeed.SubordinateFeedFactory<R,F> subFactory,
                                                                                                                                      EMultiFeed.MultiFeedFactory<M,C,F> multiFactory)

Returns a new, opened multi-key feed for the given parameters. Does the actual work of validating the parameters and creating the initial subordinate feeds.

Type Parameters:

R - eBus role used with this multi-key feed.

C - feed based on this message class.

F - subordinate feed class.

M - multi-key feed class.

Parameters:

client - application object interacting with the feed.

mc - feed message class.

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

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

condition - the optional condition used by the subordinate feed.

subFactory - used to instantiate a new subordinate feed.

multiFactory - used to instantiate a new multi-key feed.

Returns:

a new, open multiple key feed for the given application object, message class, and subjects.

Throws:

NullPointerException - if any of the arguments is null.

IllegalArgumentException - if subjects contains an empty string.

openQuery

protected static <R extends EObject,C extends EMessage,F extends net.sf.eBus.client.ESingleFeed,M extends EMultiFeed<C,F>> M openQuery(R client,
                                                                                                                                       Class<? extends C> mc,
                                                                                                                                       Pattern query,
                                                                                                                                       EFeed.FeedScope scope,
                                                                                                                                       ECondition condition,
                                                                                                                                       EMultiFeed.SubordinateFeedFactory<R,F> subFactory,
                                                                                                                                       EMultiFeed.MultiFeedFactory<M,C,F> multiFactory)

Returns a new, opened multi-key feed for the given message class and subject regular expression query. A subordinate feed is opened for all message keys matching the message class and subject query. If there are no matching message keys, then the feed is opened with no initial subordinate feeds.

Type Parameters:

R - eBus role used with this multi-key feed.

C - feed based on this message class.

F - subordinate feed class.

M - multi-key feed class.

Parameters:

client - application object interacting with the feed.

mc - feed message class.

query - message subject regular expression query.

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

condition - the optional condition used by the subordinate feed.

subFactory - used to instantiate a new subordinate feed.

multiFactory - used to instantiate a new multi-key feed.

Returns:

a new, open multiple key feed for the given application object, message class, and subject query. May have no feeds initially.

Throws:

NullPointerException - if any of the arguments is null.