ERequestFeed (eBus Core 5.2.1 API)

java.lang.Object
- net.sf.eBus.client.EFeed
- - net.sf.eBus.client.ERequestFeed

All Implemented Interfaces:: IEFeed, IERequestFeed

public final class ERequestFeed
extends EFeed
implements IERequestFeed

ERequestFeed is the application entry point for posting request messages to repliers. Follow these steps to use this feed:

Step 1: Implement the ERequestor interface.

Step 2: Open a request feed for a given ERequestor instance and type+topic message key.

Step 3 (optional): Do not override ERequestor interface methods. Instead, set callbacks using statusCallback(FeedStatusCallback) and/or replyCallback(ReplyCallback) passing in Java lambda expressions.

Step 4: Subscribe to reply message key.

Step 5: Send a request to one or more advertised repliers. If there are no advertised repliers, then request(ERequestMessage) returns ERequestFeed.RequestState.DONE, signaling that the requestor will not receive any replies.

Step 6: Wait for replies to arrive. When the remaining parameter is zero, that means this is the final reply from all repliers. When EReplyMessage.replyStatus is EReplyMessage.ReplyStatus.ERROR or EReplyMessage.ReplyStatus.OK_FINAL, then this is the final reply from that replier.

Step 7: A requestor may terminate a request prior to completion by calling EFeed.close(). No more replies should be received once this is done. (Note: there is a possibility that an in-flight reply will still be posted to the requestor.)

Step 8: When requestor is shutting down, retract the subscription and close the feed.

Example use of `ERequestFeed`

import java.util.ArrayList;
import java.util.List;
import net.sf.eBus.client.EFeed.FeedScope;
import net.sf.eBus.client.ERequestFeed;
import net.sf.eBus.client.ERequestor;
import net.sf.eBus.messages.EMessageKey;
import net.sf.eBus.messages.EReplyMessage;

Step 1: Implement the ERequestor interface.
public class CatalogRequestor implements ERequestor {
    public CatalogRequestor(final String subject, final FeedScope scope) {
        mKey = new EMessageKey(com.acme.CatalogOrder.class, subject);
        mScope = scope;
        mFeed = null;
        mRequests = new ArrayList<>();
    }

    @Override
    public void startup() {
        try {
            Step 2: Open request feed.
            mFeed = ERequestFeed.open(this, mKey, mScope);

            Step 3: ERequestor interface methods overridden.

            Step 4: Subscribe to reply message key.
            mFeed.subscribe();
        } catch (IllegalArgumentException argex) {
            // Open failed. Place recovery code here.
        }
    }

    @Override
    public void shutdown() {
        synchronized (mRequests) {
            for (ERequestFeed.ERequest request : mRequests) {
                Step 7: Cancel request by closing request.
                request.close();
            }

            mRequests.clear();
        }

        Step 8: On shutdown, close request feed.
        if (mFeed != null) {
            mFeed.close();
            mFeed = null;
        }
    }

    @Override
    public void feedStatus(final EFeedState feedState, final ERequestFeed feed) {
        if (feedState == EFeedState.DOWN) {
            // Down. There are no repliers.
        } else {
            // Up. There is at least one replier.
        }
    }

    Step 6: Wait for replies to request.
    @Override
    public void reply(final int remaining,
                       final EReplyMessage reply,
                       final ERequestFeed.ERequest request) {
        final String reason = msg.replyReason();

        if (msg.replyStatus == EReplyMessage.ReplyStatus.ERROR)
        {
            // The replier rejected the request. Report the reason
        } else if (msg.replyStatus == EReplyMessage.ReplyStatus.OK_CONTINUING) {
            // The replier will be sending more replies.
        } else {
            // This is the replier's last reply.
        }

        if (remaining == 0) {
            synchronized (mRequests) {
                mRequests.remove(request);
            }
        }
    }

    Step 5: Send a request message.
    public void placeOrder(final String product,
                            final int quantity,
                            final Price price,
                            final ShippingEnum shipping,
                            final ShippingAddress address) {
        final CatalogOrder msg =
            new CatalogOrder(product, quantity, price, shipping, address);

        try {
            synchronized (mRequests) {
                mRequests.add(mFeed.request(msg));
            }
        } catch (Exception jex) {
            // Request failed. Put recovery code here.
        }
    }

    private final EMessageKey mKey;
    private final FeedScope mScope;
    private final List<ERequestFeed.ERequest> mRequests;
    private ERequestFeed mFeed;
}

Author:: Charles Rapp
See Also:: ERequestor, EReplier, EReplyFeed

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ERequestFeed.ERequest` This class represents an individual request, tracking the current request state and the remaining repliers.
`static class`	`ERequestFeed.RequestState` A request is either not placed, active, done, or canceled.
`protected static class`	`ESingleFeed.FeedType` Enumerates the supported feed types.

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
`static String`	`FEED_STATUS_METHOD` `ERequestor.feedStatus(EFeedState, ERequestFeed)` method name.
`protected int`	`mActivationCount` Tracks the number of contra-feeds matched to this feed.
`protected static List<EFeed>`	`mAdvertisers` Track the advertised feeds in order to generate `advertise messages`.
`protected ESingleFeed.FeedType`	`mFeedType` Specifies whether this is a publish, subscribe, request, or reply feed.
`protected net.sf.eBus.client.ESubject`	`mSubject` The feed interfaces with this eBus subject.
`static String`	`REPLY_METHOD` `ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest)` method name.

Fields inherited from class net.sf.eBus.client.EFeed
mEClient, mFeedId, mFeedState, mInPlace, mIsActive, mScope, NO_CONDITION, NOTIFY_METHOD

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`activationCount()` Returns the feed activation count.
`protected void`	`inactivate()` Cancels this feed's active requests
`EMessageKey`	`key()` Returns the feed message key.
`String`	`messageSubject()` Returns the feed `message key subect`.
`static ERequestFeed`	`open(ERequestor client, EMessageKey key, EFeed.FeedScope scope)` Creates a new request feed for the given client, message key, and feed scope.
`static ERequestFeed`	`open(ERequestor cl, EMessageKey key, EFeed.FeedScope scope, EClient.ClientLocation l, boolean isMulti)` Creates a new request feed for the given client, message key, and feed scope.
`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)` Forwards the request to all matching repliers, returning the request instance.
`void`	`statusCallback(FeedStatusCallback<ERequestFeed> cb)` Puts the feed status callback in place.
`void`	`subscribe()` Subscribes this request feed to the eBus subject.
`String`	`toString()` Returns a containing the feed message key and data member values.
`void`	`unsubscribe()` Retracts this request feed from the associated subject.

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, isFeedUp, isOverridden, loadKeys, location, register, register, register, scope, shutdown, shutdown, shutdownAll, startup, startup, startupAll, storeKeys, storeKeys, storeKeys

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

- Field Detail
  - FEED_STATUS_METHOD
```
public static final String FEED_STATUS_METHOD
```
    ERequestor.feedStatus(EFeedState, ERequestFeed) method name.
    
    See Also:
    
    Constant Field Values
  - REPLY_METHOD
```
public static final String REPLY_METHOD
```
    ERequestor.reply(int, EReplyMessage, ERequestFeed.ERequest) method name.
    
    See Also:
    
    Constant Field Values
  - mAdvertisers
```
protected static final List<EFeed> mAdvertisers
```
    Track the advertised feeds in order to generate advertise messages.
  - mFeedType
```
protected final ESingleFeed.FeedType mFeedType
```
    Specifies whether this is a publish, subscribe, request, or reply feed.
  - mSubject
```
protected final net.sf.eBus.client.ESubject mSubject
```
    The feed interfaces with this eBus subject. The subject type is based on feed type.
  - mActivationCount
```
protected int mActivationCount
```
    Tracks the number of contra-feeds matched to this feed. If this is a publisher feed, then counts subscriber feeds. If a subscriber feed, then counts publisher feeds.
- Method Detail
  - inactivate
```
protected void inactivate()
```
    Cancels this feed's active requests
    
    Specified by:
    
    inactivate in class EFeed
  - 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.
  - open
```
public static ERequestFeed open(ERequestor client,
                                EMessageKey key,
                                EFeed.FeedScope scope)
```
    Creates a new request feed for the given client, message key, and feed scope. The feed is assigned a unique identifier within the client's scope. This feed is used to create new requests.
    
    Parameters:
    
    client - the eBus requestor opening this feed.
    
    key - the request message key.
    
    scope - whether this request matches local repliers, remote repliers, or both.
    
    Returns:
    
    the newly opened request feed.
    
    Throws:
    
    NullPointerException - if any of the required parameters is null.
    
    IllegalArgumentException - if key is not a request message.
    
    See Also:
    
    request(ERequestMessage), EFeed.close()
  - subscribe
```
public void subscribe()
```
    Subscribes this request feed to the eBus subject. There is no callback associated with request subscription. This subscription must be in place before request(ERequestMessage) may be called.
    
    Specified by:
    
    subscribe in interface IERequestFeed
    
    Throws:
    
    IllegalStateException - if this feed is closed or the client did not override ERequestor methods nor put the required callback in place.
    
    See Also:
    
    unsubscribe(), EFeed.close()
  - unsubscribe
```
public void unsubscribe()
```
    Retracts this request feed from the associated subject. Does nothing if this feed is not currently subscribed. This feed may be re-subscribed after un-subscribing.
    Note that un-subscribing does not cancel any active requests or prevent delivery of replies to those requests.
    
    Specified by:
    
    unsubscribe in interface IERequestFeed
    
    See Also:
    
    subscribe(), EFeed.close()
  - request
```
public ERequestFeed.ERequest request(ERequestMessage msg)
```
    Forwards the request to all matching repliers, returning the request instance. Throws IllegalStateException if no matching repliers are found and, consequently, no replies will be received. Use the returned ERequestFeed.ERequest instance to query the request state or cancel the request.
    Note: once the ERequestFeed.ERequest is returned, the application is responsible for tracking all active request instances. This request feed does not store or track requests on behalf of the application. Closing this requests feed does not automatically cancel active requests created by this feed. The application is responsible for canceling active requests.
    
    Parameters:
    
    msg - send this request message to the repliers.
    
    Returns:
    
    the resulting request.
    
    Throws:
    
    NullPointerException - if msg is null.
    
    IllegalArgumentException - if msg does not match the request subject key.
    
    IllegalStateException - if there are currently no repliers for this request.
    
    See Also:
    
    EFeed.close()
  - open
```
public static ERequestFeed open(ERequestor cl,
                                EMessageKey key,
                                EFeed.FeedScope scope,
                                EClient.ClientLocation l,
                                boolean isMulti)
```
    Creates a new request feed for the given client, message key, and feed scope. The feed is assigned a unique identifier within the client's scope.
    This method does not parameter validation since this is a package private method.
    
    Parameters:
    
    cl - the eBus requestor opening this feed.
    
    key - the request message key.
    
    scope - whether this request matches local repliers, remote repliers, or both.
    
    l - client location.
    
    isMulti - true if this is part of a multiple key feed. If true, this feed is not added to the client feed list.
    
    Returns:
    
    the newly opened request feed.
  - toString
```
public String toString()
```
    Returns a containing the feed message key and data member values.
    
    Overrides:
    
    toString in class EFeed
    
    Returns:
    
    textual representation of this feed.
  - key
```
public final EMessageKey key()
```
    Returns the feed message key. The message key type matches the feed type. If this is a EPublishFeed, then a notification message key is returned.
    
    Returns:
    
    message key.
  - messageSubject
```
public final String messageSubject()
```
    Returns the feed message key subect.
    
    Returns:
    
    message key subject.
  - activationCount
```
public final int activationCount()
```
    Returns the feed activation count.
    
    Returns:
    
    value ≥ zero.

Class ERequestFeed

Example use of ERequestFeed

Nested Class Summary

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

Field Summary

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

Method Summary

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

Methods inherited from class java.lang.Object

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

Field Detail

FEED_STATUS_METHOD

REPLY_METHOD

mAdvertisers

mFeedType

mSubject

mActivationCount

Method Detail

inactivate

statusCallback

replyCallback

replyCallback

open

subscribe

unsubscribe

request

open

toString

key

messageSubject

activationCount

Example use of `ERequestFeed`