net.sf.eBus.client

Class EMultiRequestFeed

java.lang.Object

net.sf.eBus.client.EFeed

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

net.sf.eBus.client.EMultiRequestFeed

All Implemented Interfaces:

IEFeed, IERequestFeed

public final class EMultiRequestFeed
extends EMultiFeed<ERequestMessage,ERequestFeed>
implements IERequestFeed

This feed acts as a proxy for handling multiple ERequestFeeds on behalf of a ERequestor client. A replier opens a multi-key reply feed for a specified request message class and zero or more message subjects. These 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 search the message key dictionary for all matching subjects. The matching subjects are used to create the initial subordinate ERequestFeeds.

The multi-key request feed coordinates the subordinate request feeds so 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 request 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 ERequestFeed	createFeed(EMessageKey key) Returns a newly minted subordinate request feed for the given key.
static EMultiRequestFeed	open(ERequestor client, Class<? extends ERequestMessage> mc, List<String> subjects, EFeed.FeedScope scope) Returns an open multi-key feed for the given request message class and message subjects list.
static EMultiRequestFeed	open(ERequestor client, Class<? extends ERequestMessage> mc, Pattern query, EFeed.FeedScope scope) Returns an open multi-key request feed for a given request message class and multiple message subjects.
protected void	putFeedInPlace(ERequestFeed feed) Sets the status and reply callbacks as per the multi-key configuration and subscribes the subordinate feeds.
void	replyCallback(Class<? extends EReplyMessage> mc, ReplyCallback cb) Sets the callback for a specific reply message class.
void	replyCallback(ReplyCallback cb) Puts the reply message callback in place for all reply types.
ERequestFeed.ERequest	request(ERequestMessage msg) Posts a request message to all replier via the subordinate request feed matching the message's key.
void	statusCallback(FeedStatusCallback<ERequestFeed> cb) Puts the feed status callback in place.
void	subscribe() Subscribes each subordinate ERequestFeed.
void	unsubscribe() Retracts this multi-key request feed by un-subscribing each subordinate request 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<ERequestFeed> cb)

Puts the feed status callback in place. If cb is not null, feed status updates will be passed to cb rather than ERequestor.feedStatus(EFeedState, ERequestFeed). A null cb results in feed status updates posted to the ERequestor.feedStatus(EFeedState, ERequestFeed) override.

Specified by:

statusCallback in interface IERequestFeed

Parameters:

cb - feed status update callback. May be null.

Throws:

IllegalStateException - if this feed is either closed or subscribed.

replyCallback

public void replyCallback(ReplyCallback cb)

Puts the reply message callback in place for all reply types. If cb is not null, replies will be passed to cb rather than ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest). A null cb results in replies posted to the ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest) override.

Note that this method call overrides all previous calls to replyCallback(Class, ReplyCallback). If the goal is to use a generic callback for all replies except one specific message, then use this method to put the generic callback in place first and then use replyCallback(EMessageKey, ReplyCallback).

Specified by:

replyCallback in interface IERequestFeed

Parameters:

cb - reply message callback. May be null.

Throws:

IllegalStateException - if this feed is either closed or subscribed.

See Also:

replyCallback(Class, ReplyCallback)

replyCallback

public void replyCallback(Class<? extends EReplyMessage> mc,
                          ReplyCallback cb)

Sets the callback for a specific reply message class. If cb is not null, replies will be passed to cb rather than ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest). A cb results in replies posted to the ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest) override.

If the goal is to set a single callback method for all reply message types, then use replyCallback(ReplyCallback). Note that method overrides all previous set reply callbacks.

Specified by:

replyCallback in interface IERequestFeed

Parameters:

mc - the reply message class.

cb - callback for the reply message.

Throws:

NullPointerException - if mc is null.

IllegalArgumentException - if mc is not a reply for this request.

IllegalStateException - if this feed is either closed or subscribed.

createFeed

protected ERequestFeed createFeed(EMessageKey key)

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

Specified by:

createFeed in class EMultiFeed<ERequestMessage,ERequestFeed>

Parameters:

key - create a request feed for this key.

Returns:

a subordinate request feed.

putFeedInPlace

protected void putFeedInPlace(ERequestFeed feed)

Sets the status and reply callbacks as per the multi-key configuration and subscribes the subordinate feeds.

Specified by:

putFeedInPlace in class EMultiFeed<ERequestMessage,ERequestFeed>

Parameters:

feed - advertise this subordinate request feed.

open

public static EMultiRequestFeed open(ERequestor client,
                                     Class<? extends ERequestMessage> mc,
                                     List<String> subjects,
                                     EFeed.FeedScope scope)

Returns an open multi-key feed for the given request message class and message subjects list. Once opened, the caller can (optionally) set the feed status and reply callbacks and subject the feed just like ERequestFeed.

It is the subordinate request feeds which call back to client, not the opened multi-key feed. So if subjects contains 1,000 subjects, then client receives status callbacks from 1,000 subordinate request feeds.

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

Parameters:

client - the eBus requestor opening this feed.

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

subjects - list of request 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 requestor feed for the given application object, request message class,and subjects.

Throws:

NullPointerException - if any of the arguments is null.

IllegalArgumentException - if subjects contains an empty string.

See Also:

open(ERequestor, Class, Pattern, EFeed.FeedScope), subscribe(), EFeed.close(), EMultiFeed.addFeed(String), EMultiFeed.closeFeed(String)

open

public static EMultiRequestFeed open(ERequestor client,
                                     Class<? extends ERequestMessage> mc,
                                     Pattern query,
                                     EFeed.FeedScope scope)

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

The subordinate request feeds are selected based on the given request message class and the regular expression query. The multi-key request 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 ERequestFeed feeds, not the multi-key feed. If mc and query match 1,000 request message keys, then client will receive feed status and notify callbacks from those 1,000 subordinate feeds.

Parameters:

client - application object subscribing to the request message class and matching 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.

Returns:

a new multi-key request feed for the given application object and request message keys matching the request message class and query.

See Also:

open(ERequestor, Class, List, EFeed.FeedScope), subscribe(), EFeed.close(), EMultiFeed.addFeed(String), EMultiFeed.closeFeed(String)

subscribe

public void subscribe()

Subscribes each subordinate ERequestFeed. If this feed is currently subscribed, then does nothing. The requestor client will receive a ERequestor.feedStatus(EFeedState, ERequestFeed) callback from each subordinate request feed.

Specified by:

subscribe in interface IERequestFeed

Throws:

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

See Also:

unsubscribe(), EFeed.close()

unsubscribe

public void unsubscribe()

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

Specified by:

unsubscribe in interface IERequestFeed

Throws:

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

See Also:

subscribe(), EFeed.close()

request

public ERequestFeed.ERequest request(ERequestMessage msg)

Posts a request message to all replier via the subordinate request feed matching the message's key.

Parameters:

msg - post this request message to the matching subordinate feed.

Returns:

the ERequestFeed.ERequest feed used to interact with the active request.

Throws:

NullPointerException - if msg is null.

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

IllegalStateException - if this feed is inactive, not advertised, or there are no repliers available to respond to the request.