net.sf.eBus.client

Class ESubscribeFeed

java.lang.Object

net.sf.eBus.client.EFeed

net.sf.eBus.client.ENotifyFeed

net.sf.eBus.client.ESubscribeFeed

All Implemented Interfaces:

IEFeed, IESubscribeFeed

public final class ESubscribeFeed
extends ENotifyFeed
implements IESubscribeFeed

ESubscribeFeed is the application entry point for receiving notification messages. Follow these steps to use this feed:

Step 1: Implement the ESubscriber interface.

Step 2: Open a subscribe feed for a given ESubscriber instance and type+topic message key. The condition is optional and may be null. If provided, then only notification messages satisfying the condition are forwarded to the subscriber.

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

Step 4: Subscribe to the open feed.

Step 5: Wait for an up feed status. This callback will occur before any notification messages are delivered. If the feed state is down, then no notifications will be delivered until the feed state comes back up.

Step 6: Once the feed state is up, wait for notification messages to arrive.

Step 7: When the subscriber is shutting down, retract the subscription and close the feed.

Example use of ESubscribeFeed

import net.sf.eBus.client.EFeed.FeedScope;
import net.sf.eBus.client.EFeedState;
import net.sf.eBus.client.ESubscribeFeed;
import net.sf.eBus.client.ESubscriber;
import net.sf.eBus.messages.EMessageKey;
import net.sf.eBus.messages.ENotificationMessage;

Step 1: Implement the ESubscriber interface.
public class CatalogSubscriber implements ESubscriber
{
    // Subscribe to this notification message class/subject key and feed scope.
    private final EMessageKey mKey;
    private final FeedScope mScope;

    // Store the feed here so it can be used to unsubscribe.
    private ESubscribeFeed mFeed;

    public CatalogSubscriber(final String subject, final FeedScope scope) {
        mKey = new EMessageKey(CatalogUpdate.class, subject); mScope = scope;
        mFeed = null;
    }

    @Override public void startup() {
        try {
        Step 2: Open the ESubscribe feed.
            // This subscription has no associated ECondition; passing in null.
            mFeed = ESubscribeFeed.open(this, mKey, mScope, null);

            Step 3: ESubscriber interface method overridden.

            Step 4: Subscribe to the feed.
            mFeed.subscribe();
        } catch(IllegalArgumentException argex) {
            // Feed open failed. Place recovery code here.
        }
    }

    Step 5: Wait for EFeedState.UP feed status.
    @Override public void feedStatus(final EFeedState feedState, final IESubscribeFeed feed) {
        // What is the feed state?
        if (feedState == EFeedState.DOWN) {
            // Down. There are no publishers. Expect no notifications until a
            // publisher is found. Put error recovery code here.
        } else {
            // Up. There is at least one publisher. Expect to receive notifications.
        }
    }

    Step 6: Wait for notifications to arrive.
    @Override public void notify(final ENotificationMessage msg, final IESubscribeFeed feed) {
        Notification handling code here.
    }

    @Override public void shutdown() {
    Step 7: When subscriber is shutting down, retract subscription feed.
        // mFeed.unsubscribe() is not necessary since close() will unsubscribe.
        if (mFeed != null) {
            mFeed.close();
            mFeed = null;
        }
    }
}

Author:

Charles W. Rapp

See Also:

ESubscriber, EPublisher, EPublishFeed

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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 ESubscriber.feedStatus(EFeedState, IESubscribeFeed) 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.

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
int	activationCount() Returns the feed activation count.
protected void	inactivate() If the advertisement is in place, then retracts it.
EMessageKey	key() Returns the feed message key.
String	messageSubject() Returns the feed message key subect.
void	notifyCallback(NotifyCallback cb) Puts the notification message callback in place.
static ESubscribeFeed	open(ESubscriber client, EMessageKey key, EFeed.FeedScope scope, ECondition condition) Returns a notification subscriber feed for the specified notification message class and subject.
void	statusCallback(FeedStatusCallback<IESubscribeFeed> cb) Puts the feed status callback in place.
void	subscribe() Activates this notification subscription.
String	toString() Returns a containing the feed message key and data member values.
void	unsubscribe() De-activates this subscriber feed.

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

ESubscriber.feedStatus(EFeedState, IESubscribeFeed) 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()

If the advertisement is in place, then retracts it.

Specified by:

inactivate in class EFeed

statusCallback

public void statusCallback(FeedStatusCallback<IESubscribeFeed> cb)

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

Specified by:

statusCallback in interface IESubscribeFeed

Parameters:

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

Throws:

IllegalStateException - if this feed is either closed or subscribed.

notifyCallback

public void notifyCallback(NotifyCallback cb)

Puts the notification message callback in place. If cb is not null, then notification messages will be passed to cb rather than ESubscriber.notify(ENotificationMessage, IESubscribeFeed). A null cb means that notification messages will be passed to the ESubscriber.notify(ENotificationMessage, IESubscribeFeed) override.

Specified by:

notifyCallback in interface IESubscribeFeed

Parameters:

cb - pass notification messages back to application via this callback.

Throws:

IllegalStateException - if this feed is either closed or subscribed.

subscribe

public void subscribe()

Activates this notification subscription. The caller will be asynchronously informed of the current feed state via the feed stateupdate callback method.

Nothing is done if already subscribed.

Specified by:

subscribe in interface IESubscribeFeed

Throws:

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

See Also:

unsubscribe(), EFeed.close()

unsubscribe

public void unsubscribe()

De-activates this subscriber feed. Does nothing if this feed is not currently subscribed.

Note that the client may still receive notification messages which were posted concurrently as this unsubscribe.

Specified by:

unsubscribe in interface IESubscribeFeed

See Also:

subscribe, EFeed.close()

open

public static ESubscribeFeed open(ESubscriber client,
                                  EMessageKey key,
                                  EFeed.FeedScope scope,
                                  ECondition condition)

Returns a notification subscriber feed for the specified notification message class and subject. The client calls subscribe() on the returned feed in order to start receiving the specified notification messages.

Parameters:

client - the application object subscribing to the notification. May not be null.

key - the notification message class and subject. May not be null and must reference a notification message class.

scope - whether this subscription feed matches local publishers only, remote publishers only, 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:

the newly created, unplaced, subscribe feed. Must call subscribe() in order to receive messages.

Throws:

NullPointerException - if client, key, or scope is null.

IllegalArgumentException - if any of the given parameters is invalid.

See Also:

subscribe(), EFeed.close()

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.