Package net.sf.eBus.feed.pattern

Class 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 EPatternFeed.PatternBuilder.statusCallback(FeedStatusCallback) and/or EPatternFeed.PatternBuilder.notifyCallback(NotifyCallback) 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 subscriber 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

    • Field Detail

      • sLogger

        protected static final org.slf4j.Logger sLogger
        Logging subsystem interface.

      • mPatternName

        protected final String mPatternName
        Pattern name used as the MatchEvent subject.

      • 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.

      • 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.

    • Constructor Detail

      • EPatternFeed

        protected EPatternFeed​(EPatternFeed.PatternBuilder builder)
        Creates a new eBus pattern feed based on builder settings.
        Parameters:
        builder - contains pattern feed settings.

    • 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.

      • 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()

      • onFeedStateUpdate

        protected final void onFeedStateUpdate​(EFeedState state,
                                       IESubscribeFeed feed)
        Updates the feed bit in the subordinate feed mask. If the feed state is up, then the feed bit is set; otherwise the feed bit is cleared. If the composite subordinate feed mask changes state, then this feed posts an update to its publish state.
        Parameters:
        state - subordinate feed's new state.
        feed - subordinate subscription feed.

      • onEvent

        protected final void onEvent​(ENotificationMessage event,
                             IESubscribeFeed feed)
        Runs event through the state machine if-and-only-if all the subordinate feeds are up.
        Parameters:
        event - inbound notification event.
        feed - event is from this subordinate feed.

      • 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.