net.sf.eBus.client

Class EMultiReplyFeed

java.lang.Object

net.sf.eBus.client.EFeed

net.sf.eBus.client.EMultiFeed<ERequestMessage,EReplyFeed>

net.sf.eBus.client.EMultiReplyFeed

All Implemented Interfaces:

IEFeed, IEReplyFeed

public final class EMultiReplyFeed
extends EMultiFeed<ERequestMessage,EReplyFeed>
implements IEReplyFeed

This feed allows an EReplier to open one feed for a given request message class and multiple message subjects. It acts as a proxy between the replier and the individual, subordinate feeds. The replier interacts solely with the multi-key reply feed and is unable to access the underlying EReplyFeeds. The replier 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 EReplyFeeds. But the subordinate feeds issue EReplier.request(EReplyFeed.ERequest) callbacks to the EReplier registered with the multi-key feed. The multi-key feed does not callback to the replier 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 reply message class and subject list to open or a notification message class and regular express query to open(EReplier, Class, Pattern, EFeed.FeedScope, ECondition). 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 reply 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 EReplyFeed.
void	cancelRequestCallback(CancelRequestCallback cb) Puts the cancel request callback in place.
protected EReplyFeed	createFeed(EMessageKey key) Returns a newly minted subordinate reply feed for the given key.
boolean	isAdvertised() Returns true if this reply feed is both open and advertised; otherwise, returns false.
static EMultiReplyFeed	open(EReplier client, Class<? extends ERequestMessage> mc, List<String> subjects, EFeed.FeedScope scope, ECondition condition) Returns an open reply feed for multiple request message keys.
static EMultiReplyFeed	open(EReplier client, Class<? extends ERequestMessage> mc, Pattern query, EFeed.FeedScope scope, ECondition condition) Returns an open reply feed for a request message class and multiple subjects.
protected void	putFeedInPlace(EReplyFeed feed) Sets the feed status callback, advertises feed, and updates the reply feed state.
EFeedState	replyState() Returns the reply state which specifies whether this multi-key reply feed (and its subordinate feeds) are ready to handle requests or not.
void	requestCallback(RequestCallback cb) Puts the new request callback in place.
void	unadvertise() Retracts this multi-key replier feed by un-advertising each subordinate reply feed.
void	updateFeedState(EFeedState update) Updates the reply 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 reply feed is both open and advertised; otherwise, returns false.

Specified by:

isAdvertised in interface IEReplyFeed

Returns:

true if this reply feed is open and advertised.

requestCallback

public void requestCallback(RequestCallback cb)

Puts the new request callback in place. If cb is not null, requests will be passed to cb rather than EReplier.request(EReplyFeed.ERequest). A null cb means that requests are passed to the EReplier.request(EReplyFeed.ERequest) override.

Specified by:

requestCallback in interface IEReplyFeed

Parameters:

cb - the request callback. May be null.

Throws:

IllegalStateException - if this feed is either closed or advertised.

cancelRequestCallback

public void cancelRequestCallback(CancelRequestCallback cb)

Puts the cancel request callback in place. If cb is not null, requests will be passed to cb rather than EReplier.cancelRequest(EReplyFeed.ERequest). A null cb means that cancellations are passed to the EReplier.cancelRequest(EReplyFeed.ERequest) override.

Specified by:

cancelRequestCallback in interface IEReplyFeed

Parameters:

cb - the cancel request callback. May be null.

Throws:

IllegalStateException - if this feed is either closed or advertised.

advertise

public void advertise()

Advertises each subordinate EReplyFeed. If this feed is currently advertised, then does nothing. If the cancel request and request callbacks were previously set for this feed, then these callbacks are set in the subordinate feeds prior to advertising them.

Specified by:

advertise in interface IEReplyFeed

Throws:

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

See Also:

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

unadvertise

public void unadvertise()

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

Specified by:

unadvertise in interface IEReplyFeed

Throws:

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

See Also:

advertise(), EFeed.close()

updateFeedState

public void updateFeedState(EFeedState update)

Updates the reply 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 reply feed states are updated as well.

The reply 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 IEReplyFeed

Parameters:

update - the new reply feed state.

Throws:

NullPointerException - if update is null.

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

createFeed

protected EReplyFeed createFeed(EMessageKey key)

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

Specified by:

createFeed in class EMultiFeed<ERequestMessage,EReplyFeed>

Parameters:

key - create feed for this key.

Returns:

a subordinate reply feed.

putFeedInPlace

protected void putFeedInPlace(EReplyFeed feed)

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

Specified by:

putFeedInPlace in class EMultiFeed<ERequestMessage,EReplyFeed>

Parameters:

feed - advertise this feed.

replyState

public EFeedState replyState()

Returns the reply state which specifies whether this multi-key reply feed (and its subordinate feeds) are ready to handle requests or not. An update reply state does not mean that the replier will receive requests but only that the replier is capable of handling requests at this time.

Returns:

current reply state.

See Also:

EMultiFeed.feedState(String)

open

public static EMultiReplyFeed open(EReplier client,
                                   Class<? extends ERequestMessage> mc,
                                   List<String> subjects,
                                   EFeed.FeedScope scope,
                                   ECondition condition)

Returns an open reply feed for multiple request message keys. Once opened, the caller can (optionally) set the cancel and request callbacks and advertise the feed just like EReplyFeed.

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

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

Parameters:

client - the application object handling request feeds.

mc - message class for all subordinate feeds.

subjects - list of request message class and subject. May not contain null or empty strings but this list may be empty.

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

condition - accept request 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 reply feed for the given application object and request message keys.

Throws:

NullPointerException - if any of the required arguments is null.

IllegalArgumentException - if subjects contains an empty string.

See Also:

open(EReplier, Class, Pattern, EFeed.FeedScope, ECondition), cancelRequestCallback(CancelRequestCallback), requestCallback(RequestCallback), advertise(), unadvertise(), EFeed.close()

open

public static EMultiReplyFeed open(EReplier client,
                                   Class<? extends ERequestMessage> mc,
                                   Pattern query,
                                   EFeed.FeedScope scope,
                                   ECondition condition)

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

The subordinate reply feeds are selected based on the given request 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 reply feed will have no initial subordinate feeds. If that is the case, new reply feeds may be dynamically added while the multi-key feed is open.

Note: client receives callbacks for each subordinate EReplyFeed as if it opened those feeds directly. If mc and query matches a large number of request message keys, then client must be prepared for a large number of callbacks.

Parameters:

client - the application object replying to the request message class and subjects.

mc - the message key query is for this request 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 publisher feed for the given application object and request 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(EReplier, Class, List, EFeed.FeedScope, ECondition), cancelRequestCallback(CancelRequestCallback), requestCallback(RequestCallback), advertise(), unadvertise()