net.sf.eBus.feed

Class EPatternFeed

java.lang.Object

net.sf.eBus.client.EFeed

net.sf.eBus.feed.EPatternFeed

All Implemented Interfaces:

EObject, ESubscriber, IEFeed, IESubscribeFeed

public abstract class EPatternFeed
extends EFeed
implements ESubscriber, IESubscribeFeed

eBus pattern feeds sit between eBus notification events and an eBus client, searching for a client-specified event pattern in the notification event stream. When a match is found, a MatchEvent is posted to the client via the configured notification callback, just like any other notification.

Follow these steps when using a pattern feed:

Step 1: Implement the ESubscriber interface.

Step 2: Define an EventPattern.

Step 3: Open a pattern feed for the subscriber and pattern defined above.

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

Step 5: Subscribe to the open pattern feed.

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

Step 7: When the pattern feed is up, wait for MatchEvents to arrive.

Step 8: When the subsceriber is shutting down, close the feed.

Example use of EPatternFeed

import net.sf.eBus.client.EFeedState;
import net.sf.eBus.client.EPatternFeed;
import net.sf.eBus.client.ESubscriber;
import net.sf.eBus.messages.EventPattern;
import net.sf.eBus.messages.MatchEvent;

Step 1: Implement the ESubscriber interface.
public final class TradeAlgo implements ESubscriber
{
    // Monitor this stock symbol.
    private final String mSymbol;

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

    public TradeAlgo(final String symbol) {
        mSymbol = symbol;
    }

    @Override public void startup() {
        Step 2: Define event pattern.
        final EventPattern pattern = (see EventPattern to learn how to create a pattern.)

        Step 3: Open the pattern feed.
        mFeed = EPatternFeed.open(this, pattern);

        Step 4: ESubscriber interface method overridden.

        Step 5: Subscribe to the pattern feed.
        mFeed.subscribe();
    }


    Step 6: 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. At least one pattern is down. Expect no matches until all
            // subordinate pattern feeds are up.
        } else {
            // Up. Expect to receive match notifications.
        }
    }

    Step 7: Wait for matches to arrive.
    @Override public void notify(final ENotificationMessage msg, final IESubscribeFeed feed) {
        final MatchEvent match = (MatchEvent) msg;

        Match handling code here.
    }

    @Override public void shutdown() {
        Step 8: 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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	EPatternFeed.AbstractMatchFrame A match frame tracks an in-progress match.

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
protected long	mAllSubFeedsMask Bit mask for all subordinate feeds.
protected Predicate<MatchEvent>	mCondition Match event is posted to subscriber if-and-only-if the match event satisfies this condition.
protected Map<ENotificationMessage,List<EPatternFeed.AbstractMatchFrame>>	mEventFrames Maps an accepted notification event to the match frames in which it appears.
protected boolean	mIsExclusive Set to true if an event may be used for only one match.
protected NotifyCallback	mNotifyCallback Notification message callback.
protected String	mPatternName Pattern name used as the MatchEvent subject.
protected EMessageKey	mPubKey Publish match events on this message key.
protected FeedStatusCallback<IESubscribeFeed>	mStatusCallback Feed status callback.
protected long	mSubFeedMask Bit mask used to determine if all subordinate feeds are up.
protected List<ESubscribeFeed>	mSubFeeds Maps the feed identifier to the subordinate notify feed.
protected BiPredicate<List<ENotificationMessage>,ENotificationMessage>	mUntil Collected matching events must satisfy this until predicate.
protected static Logger	sLogger Logging subsystem interface.

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

mEClient, mFeedId, mFeedState, mInPlace, mIsActive, mScope, NO_CONDITION, NOTIFY_METHOD

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EPatternFeed(EClient client, EventPattern pattern) Creates a new eBus pattern feed for the given subscriber client and event pattern.

Method Summary

Modifier and Type	Method and Description
protected void	addMapping(ENotificationMessage event, EPatternFeed.AbstractMatchFrame mf) Adds a mapping from the given event to the match frame which now contains the event.
protected static boolean	componentTest(ENotificationMessage e, EPatternFeed.AbstractMatchFrame mf, MatchCondition mc)
protected void	inactivate() Retracts all in place, subordinate feed subscriptions.
boolean	isExclusive() Returns true if this is an exclusive pattern feed.
EMessageKey	key() Returns a message key with MatchEvent as the class and the event pattern name as the subject.
protected void	markDefunct(List<ENotificationMessage> events) Marks all of the match frames associated with the given events as defunct.
protected abstract void	matchEvent(ENotificationMessage event, int eventId) Applies event to the pattern.
void	notifyCallback(NotifyCallback cb) Puts the MatchEvent notification message callback in place.
static EPatternFeed	open(ESubscriber client, EventPattern pattern) Opens either an ordered pattern or unordered pattern based on pattern type.
void	statusCallback(FeedStatusCallback<IESubscribeFeed> cb) Puts the subscription feed status callback in place.
void	subscribe() Activates this event pattern feed by putting the subordinate subscription feeds in place.
void	unsubscribe()

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

addAllKeys, addKey, 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, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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

feedStatus, notify

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

shutdown, startup

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

close, eClient, feedId, inPlace, isActive, isFeedUp, scope

Field Detail

sLogger

protected static final Logger sLogger

Logging subsystem interface.

mPatternName

protected final String mPatternName

Pattern name used as the MatchEvent subject.

mPubKey

protected final EMessageKey mPubKey

Publish match events on this message key. The message key subject is mPatternName.

mUntil

protected final BiPredicate<List<ENotificationMessage>,ENotificationMessage> mUntil

Collected matching events must satisfy this until predicate. The collected events list and latest event are the predicate parameters. This condition may be based on any event field but will most likely use EMessage.timestamp.

mIsExclusive

protected final boolean mIsExclusive

Set to true if an event may be used for only one match. If this is the case, then all extant match frames are cleared when a single match completes.

Note: exclusivity applies only within a pattern and not between patterns. Even if two patterns are marked exclusive, a single event may still be used to satisfy those two patterns.

mCondition

protected final Predicate<MatchEvent> mCondition

Match event is posted to subscriber if-and-only-if the match event satisfies this condition. While this condition may appear to play the same role as a feed condition, the difference is that if this condition returns true and the pattern is exclusive, that all related match frames are removed.

mSubFeeds

protected final List<ESubscribeFeed> mSubFeeds

Maps the feed identifier to the subordinate notify feed. These feeds are defined by the EventPattern.parameters().

mEventFrames

protected final Map<ENotificationMessage,List<EPatternFeed.AbstractMatchFrame>> mEventFrames

Maps an accepted notification event to the match frames in which it appears. This map is used only for exclusive pattern feeds. When a match frame completely matches the pattern, then this map is used to find the match frames referencing the same events.

Set to null for non-exclusive.

mAllSubFeedsMask

protected long mAllSubFeedsMask

Bit mask for all subordinate feeds. Bits are mapped to feed identifiers.

mSubFeedMask

protected long mSubFeedMask

Bit mask used to determine if all subordinate feeds are up. When a feed is up, its matching bit is set in this bit mask. When this mask equals mAllSubFeedsMask, then this event feed is up.

mStatusCallback

protected FeedStatusCallback<IESubscribeFeed> mStatusCallback

Feed status callback. If not explicitly set by client, then defaults to ESubscriber.feedStatus(EFeedState, IESubscribeFeed).

mNotifyCallback

protected NotifyCallback mNotifyCallback

Notification message callback. If not explicity set by client, then defaults to ESubscriber.notify(ENotificationMessage, IESubscribeFeed).

Constructor Detail

EPatternFeed

protected EPatternFeed(EClient client,
                       EventPattern pattern)

Creates a new eBus pattern feed for the given subscriber client and event pattern.

Parameters:

client - post match events to this client.

pattern - event pattern.

Method Detail

matchEvent

protected abstract void matchEvent(ENotificationMessage event,
                                   int eventId)

Applies event to the pattern. If this event completes the pattern, then a MatchEvent is created, tested with the match condition, and, if the match event satisfies the condition, the match event is forwarded to the subscriber.

Parameters:

event - apply this event to the pattern.

eventId - unique identifier associated with the event type.

inactivate

protected final void inactivate()

Retracts all in place, subordinate feed subscriptions.

Specified by:

inactivate in class EFeed

key

public final EMessageKey key()

Returns a message key with MatchEvent as the class and the event pattern name as the subject.

Specified by:

key in interface IEFeed

Returns:

pattern feed key.

statusCallback

public final void statusCallback(FeedStatusCallback<IESubscribeFeed> cb)

Puts the subscription feed status callback in place. If cb is not null, feed status updates are passed to cb rather than to 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 - feed status update callback. May be null.

Throws:

IllegalStateException - if this feed is either closed or subscribed.

notifyCallback

public final void notifyCallback(NotifyCallback cb)

Puts the MatchEvent 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 final void subscribe()

Activates this event pattern feed by putting the subordinate subscription feeds in place.

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 final void unsubscribe()

Specified by:

unsubscribe in interface IESubscribeFeed

isExclusive

public final boolean isExclusive()

Returns true if this is an exclusive pattern feed. Exclusive match events do not share events between instances of the same pattern feed.

Events may be shared between different pattern feeds.

Returns:

true if the match pattern is exclusive.

addMapping

protected final void addMapping(ENotificationMessage event,
                                EPatternFeed.AbstractMatchFrame mf)

Adds a mapping from the given event to the match frame which now contains the event. Note: this method assumes that the caller previously determined this is an exclusive pattern feed.

Parameters:

event - event added to the given match frame.

mf - match frame containing the event.

markDefunct

protected final void markDefunct(List<ENotificationMessage> events)

Marks all of the match frames associated with the given events as defunct. Note: this method assumes that the caller previously determined this is an exclusive pattern feed. Also removes each of the listed events from the event-to-match frame map.

Marking a match frame as defunct allows frames to be lazily removed from the frames list when encountered during the match process.

Parameters:

events - the events comprising a completely matched, exclusive pattern.

open

public static EPatternFeed open(ESubscriber client,
                                EventPattern pattern)

Opens either an ordered pattern or unordered pattern based on pattern type.

Parameters:

client - forward MatchEvents to this subscriber.

pattern - event pattern definition.

Returns:

event pattern feed instance.

componentTest

protected static boolean componentTest(ENotificationMessage e,
                                       EPatternFeed.AbstractMatchFrame mf,
                                       MatchCondition mc)