net.sf.eBus.client

Class EMultiPublishFeed

java.lang.Object

net.sf.eBus.client.EFeed

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

net.sf.eBus.client.EMultiPublishFeed

All Implemented Interfaces:

IEFeed, IEPublishFeed

public final class EMultiPublishFeed
extends EMultiFeed<ENotificationMessage,EPublishFeed>
implements IEPublishFeed

This feed allows an EPublisher to open one feed for a given notification message class and multiple message subjects. It acts as a proxy between the publisher and the individual, subordinate feeds. The publisher interacts solely with the multi-key publisher. The publisher client opens, advertises, un-advertises, and closes the multi-key feed. In turn, the multi-key feed opens, advertises, un-advertises, and closes the subordinate EPublishFeeds in unison But the subordinate feeds issue EPublisher.publishStatus(EFeedState, IEPublishFeed) callbacks to the EPublisher registered with the multi-key feed. The multi-key feed does not callback to the publisher client. If the client opens a large number of subordinate feeds, then the client must be prepared for a large number of callbacks.

The subordinate feeds are selected by either passing a message class and subject list to open or a notification message class and regular express query to open(EPublisher, Class, Pattern, EFeed.FeedScope). The first limits the subordinate feeds to exactly those whose message key is listed. The second chooses message keys with the given message class and whose subjects match the regular expression. In either case, the publisher may add or remove feeds dynamically while the multi-key feed is open. When adding a new publish feed, the new feed is configured in the same was as existing feeds and put into the same state (open, advertised, etc.).

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
void	advertise() Advertises each subordinate EPublishFeed.
protected EPublishFeed	createFeed(EMessageKey key) Returns a newly minted subordinate publish feed for the given key.
boolean	isAdvertised() Returns true if this multikey publish feed is both open and advertised; otherwise, returns false.
boolean	isFeedUp(String subject) Returns true if the publisher is clear to publish a notification for the given feed and false if not clear.
static EMultiPublishFeed	open(EPublisher client, Class<? extends ENotificationMessage> mc, List<String> subjects, EFeed.FeedScope scope) Returns an open publish feed for multiple notification message keys.
static EMultiPublishFeed	open(EPublisher client, Class<? extends ENotificationMessage> mc, Pattern query, EFeed.FeedScope scope) Returns an open publish feed for a notification message class and multiple subjects.
void	publish(ENotificationMessage msg) Posts a notification message to all subscribers via the subordinate publish feed which matches the message's key.
EFeedState	publishState() Returns the publish state.
protected void	putFeedInPlace(EPublishFeed feed) Sets the feed status callback, advertises feed, and updates the publish feed state.
void	statusCallback(FeedStatusCallback<IEPublishFeed> cb) Puts the publish status callback in place.
void	unadvertise() Retracts this multi-key publisher feed by un-advertising each subordinate publish feed.
void	updateFeedState(EFeedState update) Updates the publish feed state to the given value.

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

isAdvertised

public boolean isAdvertised()

Returns true if this multikey publish feed is both open and advertised; otherwise, returns false.

Note: if true is returned, that does not mean that the publisher is clear to publish notification messages. The publisher should only post messages when isFeedUp(String) returns true.

Specified by:

isAdvertised in interface IEPublishFeed

Returns:

true if this publish feed is open and advertised.

See Also:

EFeed.isActive(), isFeedUp(String), EMultiFeed.feedState(String)

publishState

public EFeedState publishState()

Returns the publish state. The returned state is not to be confused with EMultiFeed.feedState(String) which returns EFeedState.UP if there is any subscriber to this feed. The publish state specifies whether the publisher is capable of publishing messages for this feed.

An up publish state does not mean that the publisher is clear to post notifications to the feed. See isFeedUp(String) to determine if the publisher may post notifications to a specific subject.

Specified by:

publishState in interface IEPublishFeed

Returns:

current publish state.

See Also:

isFeedUp(String)

isFeedUp

public boolean isFeedUp(String subject)

Returns true if the publisher is clear to publish a notification for the given feed and false if not clear. When true is returned, that means that this feed is 1) open, 2) advertised, 3) the publish state is up, and 4) there are subscribers listening to this notification feed.

Returns false if key does not reference a known message feed.

Specified by:

isFeedUp in interface IEPublishFeed

Parameters:

subject - check the feed status for the feed referenced by this subject.

Returns:

true if the specified publisher feed is up and the publisher is free to publish notification messages for the specified subject.

Throws:

NullPointerException - if subject is null.

IllegalArgumentException - if subject is empty.

IllegalStateException - if this multi-key feed is closed.

See Also:

EFeed.isActive(), isAdvertised()

statusCallback

public void statusCallback(FeedStatusCallback<IEPublishFeed> cb)

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

Specified by:

statusCallback in interface IEPublishFeed

Parameters:

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

Throws:

IllegalStateException - if this feed is either closed or advertised.

advertise

public void advertise()

Advertises each subordinate EPublishFeed. If this feed is currently advertised, then does nothing. The publisher client will receive a EPublisher.publishStatus(EFeedState, IEPublishFeed) callback for each subordinate publish feed.

The publisher may publish messages to this feed only after:

• eBus calls EPublisher.publishStatus(EFeedState, IEPublishFeed) with an up feed state.
• the publisher client calls updateFeedState(EFeedState) with an EFeedState.UP up publish state. Note this feed state is applied to all subordinate feeds. It is not necessary for the publisher to call set the feed state for individual feeds.

These two steps may occur in any order. Both states must be up before publish(ENotificationMessage) may be called.

Specified by:

advertise in interface IEPublishFeed

Throws:

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

See Also:

unadvertise(), updateFeedState(EFeedState), EFeed.close()

unadvertise

public void unadvertise()

Retracts this multi-key publisher feed by un-advertising each subordinate publish feed. Does nothing if this feed is not currently advertised.

Specified by:

unadvertise in interface IEPublishFeed

Throws:

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

See Also:

advertise(), EFeed.close()

updateFeedState

public void updateFeedState(EFeedState update)

Updates the publish feed state to the given value. If update equals the currently stored publish feed state, nothing is done. Otherwise, the updated value is stored and the subordinate publish feed states are updated as well.

The publish feed state may be updated only when this feed is open and advertised. The method may not be called when the feed is closed or un-advertised.

Specified by:

updateFeedState in interface IEPublishFeed

Parameters:

update - the new publish feed state.

Throws:

NullPointerException - if update is null.

IllegalStateException - if this feed was closed or is not advertised.

publish

public void publish(ENotificationMessage msg)

Posts a notification message to all subscribers via the subordinate publish feed which matches the message's key.

Specified by:

publish in interface IEPublishFeed

Parameters:

msg - post this message to the matching subordinate feed.

Throws:

NullPointerException - if msg is null.

IllegalArgumentException - if msg message key does not reference a known subordinate publish feed.

IllegalStateException - if this feed is inactive, not advertised, the publisher has not declared the feed to be up, or there are no subscribers listening to the subordinate feed.

createFeed

protected EPublishFeed createFeed(EMessageKey key)

Returns a newly minted subordinate publish feed for the given key. The returned feed's configuration is the same as existing subordinate feeds.

Specified by:

createFeed in class EMultiFeed<ENotificationMessage,EPublishFeed>

Parameters:

key - create feed for this key.

Returns:

a subordinate publish feed.

putFeedInPlace

protected void putFeedInPlace(EPublishFeed feed)

Sets the feed status callback, advertises feed, and updates the publish feed state. The publish feed state is taken from the most recent updateFeedState(EFeedState) setting. If the publish feed state has never been updated, then the state is EFeedState.UNKNOWN.

Specified by:

putFeedInPlace in class EMultiFeed<ENotificationMessage,EPublishFeed>

Parameters:

feed - advertise this feed.

See Also:

updateFeedState(EFeedState)

open

public static EMultiPublishFeed open(EPublisher client,
                                     Class<? extends ENotificationMessage> mc,
                                     List<String> subjects,
                                     EFeed.FeedScope scope)

Returns an open publish feed for multiple notification message keys. Once opened, the caller can (optionally) set the status callback and advertise the feed just like EPublishFeed.

Note: client receives callbacks for each subordinate EPublishFeed as if it opened those feeds directly. If subjects is large, then client must be prepared for a large number of EPublisher.publishStatus(EFeedState, IEPublishFeed) callbacks.

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

Parameters:

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

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

subjects - list of notification message subjects. May not contain null or empty strings but this list may be empty.

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

Returns:

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

Throws:

NullPointerException - if any of the arguments is null.

IllegalArgumentException - if subjects contains an empty string.

See Also:

open(EPublisher, Class, Pattern, EFeed.FeedScope), statusCallback(FeedStatusCallback), advertise(), EFeed.close(), EMultiFeed.addFeed(String), EMultiFeed.closeFeed(String)

open

public static EMultiPublishFeed open(EPublisher client,
                                     Class<? extends ENotificationMessage> mc,
                                     Pattern query,
                                     EFeed.FeedScope scope)

Returns an open publish feed for a notification message class and multiple subjects. Once opened, the caller can (optionally) set the status callback and advertise the feed just like EPublishFeed.

The subordinate publish feeds are selected based on the given notification message class and the regular expression pattern. If message class and query do not match any entries in the message key dictionary, then the returned multi-key publish feed will have no initial subordinate feeds. If that is the case, new publish feeds may be dynamically added while the multi-key feed is open.

Note: client receives callbacks for each subordinate EPublishFeed as if it opened those feeds directly. If mc and query matches a large number of notification message keys, then client must be prepared for a large number of EPublisher.publishStatus(EFeedState, IEPublishFeed) callbacks.

Parameters:

client - the application object publishing the notification message class and 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.

Returns:

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

Throws:

NullPointerException - if any of the arguments are null.

IllegalArgumentException - if any of the arguments is invalid.

See Also:

open(EPublisher, Class, List, EFeed.FeedScope), statusCallback(FeedStatusCallback), advertise(), EFeed.close(), EMultiFeed.addFeed(String), EMultiFeed.closeFeed(String)