java.lang.Object
- net.sf.eBus.client.EFeed
- - net.sf.eBus.client.ENotifyFeed
  - - net.sf.eBus.client.EPublishFeed

All Implemented Interfaces:: IEFeed, IEPublishFeed

public final class EPublishFeed
extends ENotifyFeed
implements IEPublishFeed

EPublishFeed is the application entry point for publishing notification messages to subscribers. Follow these steps to use this feed:

Step 1: Implement the EPublisher interface.

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

Step 3 (optional): Do not override EPublisher interface method. Instead, set callback using statusCallback(FeedStatusCallback) passing in a Java lambda expression.

Step 4: Advertise this publisher to eBus. This allows eBus to match publishers to subscribers. An optional step is to set the feed state to up if the publisher is always able to publish the message.

Step 5: Wait for the EPublisher.publishStatus(EFeedState, IEPublishFeed) callback where the feed state is up. Attempting to publish before this will result in publish(ENotificationMessage) throwing an IllegalStateException.

Step 6: Start publishing notifications. Note that updateFeedState(EFeedState) with an up feed state must be done prior to publishing notifications.

Step 7: When the publisher is shutting down, retract the notification advertisement and close the feed.

Example use of `EPublishFeed`

import net.sf.eBus.client.EFeed.FeedScope;
import net.sf.eBus.client.EFeedState;
import net.sf.eBus.client.EPublisher;
import net.sf.eBus.client.EPublishFeed;
import net.sf.eBus.messages.EMessageKey;
import net.sf.eBus.messages.ENotificationMessage;

// Step 1: Implement EPublisher interface.
public class CatalogPublisher implements EPublisher {
    public CatalogPublisher(final String subject, final FeedScope scope) {
        mKey = new EMessageKey(CatalogUpdate.class, subject); mScope = scope;
        mFeed = null;
    }

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

            // Step 3: Overriding EPublisher interface methods.

            // Step 4: Advertise this publisher to eBus.
            mFeed.advertise();

            // Inform the world that this publisher's feed state is up.
            mFeed.updateFeedState(EFeedState.UP);
        } catch (IllegalArgumentException argex) {
            // Advertisement failed. Place recovery code here.
        }
    }

    // Step 5: Handle publish status update.
    @Override
    public void publishStatus(final EFeedState feedState, final EPublishFeed feed) {
        EFeedState publishState;

        // Are we starting a feed?
        if (feedState == EFeedState.UP) {
            // Yes. Start publishing notifications on the feed.
            publishState = startPublishing();
        } else {
            // We are stopping the feed. stopPublishing();
        }
    }

    public void updateProduct(final String productName, final Money price, final int stockQty) {
        if (mFeed != null && mFeed.isFeedUp()) {
            // Step 6: Start publishing notifications.
            mFeed.publish(new CatalogUpdate(productName, price, stockQty));
        }
    }

    // Retract the notification feed.
    @Override
    public void shutdown() {
        Step 7: On shutdown either unadvertise or close publish feed.
        if (mFeed != null) {
            // unadvertise() unnecessary since close() retracts an in-place advertisement.
            mFeed.close();
            mFeed = null;
        }
    }

    // Starts the notification feed when the feed state is up.
    // Return EFeedState.UP if the notification is successfully started;
    // EFeedState.DOWN if the feed fails to start.
    private EFeedState startPublishing() {
         Application-specific code not shown.
    }

    // Stops the notification feed if up.
    private void stopPublishing() {
        Application-specific code not shown.
    }

    // Publishes this notification message class/subject key.
    private final EMessageKey mKey;

    // Published messages remain within this scope.
    private final FeedScope mScope;

    // Advertise and publish on this feed.
    private EPublishFeed mFeed;
}

Updating Feed State

The reason for separating advertising and feed state is to support uncertain publisher feeds. Uncertain publisher feeds fail into two types 1) unreliable external data source and 2) a combination subscriber and publisher.

The first might be an external device connected to a serial port, providing intermittent data updates. The eBus publisher converts that data into notification messages. If the serial interface is unreliable and goes down, the eBus publisher calls updateFeedState(EFeedState.DOWN) to inform subscribers about the fact.

The second is a publisher which also subscribes to one or more other feeds, publishing a value-added notification based on the inbound notifications. If one of the subscribed feeds goes down, then the publisher sets its feed state to down. When the subscribed feed is back up, then the publisher is also back up.

The above scenarios could also be accomplished by having the publisher undadvertise() and advertise() when the feed is down and up, respectively. But eBus expends much effort doing this. It is less effort to leave the advertisement in place and update the feed state.

Author:: Charles W. Rapp

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>

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`ESingleFeed.FeedType` Enumerates the supported feed types.

Field Summary

Fields
Modifier and Type	Field and Description
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`activationCount()` Returns the feed activation count.
`void`	`advertise()` Advertises this publisher feed to the associated notification subject.
`protected void`	`inactivate()` If the feed state is up, then informs the notify subject that it is now down.
`boolean`	`isAdvertised()` Returns `true` if this publish feed is both open and advertised; otherwise, returns `false`.
`boolean`	`isFeedUp()` Returns `true` if the publisher is clear to publish a notification and `false` if not clear.
`boolean`	`isFeedUp(String subject)` Returns `true` if `subject` equals this feed's subject and `isFeedUp()` is `true`.
`EMessageKey`	`key()` Returns the feed message key.
`String`	`messageSubject()` Returns the feed `message key subect`.
`static EPublishFeed`	`open(EPublisher client, EMessageKey key, EFeed.FeedScope scope)` Returns a notification publish feed for the specified notification message class and subject.
`static EPublishFeed`	`open(EPublisher cl, EMessageKey key, EFeed.FeedScope scope, EClient.ClientLocation l, boolean isMulti)` Returns a notification publish feed for the specified notification message class and subject.
`void`	`publish(ENotificationMessage msg)` Posts this notification message to all interested subscribers.
`EFeedState`	`publishState()` Returns the publish state.
`void`	`statusCallback(FeedStatusCallback<IEPublishFeed> cb)` Puts the publish status callback in place.
`String`	`toString()` Returns a containing the feed message key and data member values.
`void`	`unadvertise()` Retracts this publisher feed from the associated notification subject.
`void`	`updateFeedState(EFeedState update)` Updates the publish feed state to the given value.

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

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, key, scope

- Field Detail
  - 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 feed state is up, then informs the notify subject that it is now down. If the advertisement is in place, then retracts it.
    
    Specified by:
    
    inactivate in class EFeed
  - isAdvertised
```
public boolean isAdvertised()
```
    Returns true if this publish feed is both open and advertised; otherwise, returns false.
    Note: if true is returned, that does not mean that the publisher is clear to publish notification messages. The publisher should only post messages when isFeedUp() returns true.
    
    Specified by:
    
    isAdvertised in interface IEPublishFeed
    
    Returns:
    
    true if this publish feed is open and advertised.
    
    See Also:
    
    EFeed.isActive(), isFeedUp(), publishState()
  - publishState
```
public EFeedState publishState()
```
    Returns the publish state. The returned state is not to be confused with EFeed.feedState() which returns EFeedState.UP if there is any subscriber to this feed. The publish state specifies whether the publisher is capable of publishing messages for this feed.
    
    Specified by:
    
    publishState in interface IEPublishFeed
    
    Returns:
    
    current publish state.
  - isFeedUp
```
public boolean isFeedUp()
```
    Returns true if the publisher is clear to publish a notification and false if not clear. When true is returned, that means that this feed is 1) open, 2) advertised, 3) the publish state is up, and 4) there are subscribers listening to this notification feed.
    
    Specified by:
    
    isFeedUp in interface IEFeed
    
    Overrides:
    
    isFeedUp in class EFeed
    
    Returns:
    
    true if the publisher feed is up and the publisher is free to publish notification messages.
    
    See Also:
    
    EFeed.isActive(), isAdvertised()
  - isFeedUp
```
public boolean isFeedUp(String subject)
```
    Returns true if subject equals this feed's subject and isFeedUp() is true. Otherwise, returns false.
    
    Specified by:
    
    isFeedUp in interface IEPublishFeed
    
    Parameters:
    
    subject - check if the feed for this subject is up.
    
    Returns:
    
    true if the publisher feed is up for the specified subject and the publisher is free to publish notification messages.
  - open
```
public static EPublishFeed open(EPublisher client,
                                EMessageKey key,
                                EFeed.FeedScope scope)
```
    Returns a notification publish feed for the specified notification message class and subject.
    
    Parameters:
    
    client - the application object publishing 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 the feed supports local feeds, remote feeds, or both.
    
    Returns:
    
    a new notification feed for the given application object and message key.
    
    Throws:
    
    NullPointerException - if any of the arguments are null.
    
    IllegalArgumentException - if any of the arguments is invalid.
    
    See Also:
    
    statusCallback(FeedStatusCallback), advertise()
  - statusCallback
```
public void statusCallback(FeedStatusCallback<IEPublishFeed> cb)
```
    Puts the publish status callback in place. If cb is not null, publish status updates will be passed to cb rather than EPublisher.publishStatus(EFeedState, IEPublishFeed). The reverse is true if cb is null. That is, a null cb means publish status updates are posted to the EPublisher.publishStatus(EFeedState, IEPublishFeed) override.
    
    Specified by:
    
    statusCallback in interface IEPublishFeed
    
    Parameters:
    
    cb - the publish status update callback. May be null.
    
    Throws:
    
    IllegalStateException - if this feed is either closed or advertised.
    
    See Also:
    
    advertise()
  - advertise
```
public void advertise()
```
    Advertises this publisher feed to the associated notification subject. If this feed is currently advertised to the subject, then does nothing. The publisher may publish messages to this feed only after:
    - eBus calls EPublisher.publishStatus(EFeedState, IEPublishFeed) with an up feed state.
    - the publisher client calls updateFeedState(EFeedState) with an EFeedState.UP up publish state.
    These two steps may occur in any order. Both states must be up before publish(ENotificationMessage) may be called.
    Specified by:
    
    advertise in interface IEPublishFeed
    
    Throws:
    
    IllegalStateException - if this feed is closed or the client did not override EPublisher methods nor put the required callback in place.
    
    See Also:
    
    unadvertise(), updateFeedState(EFeedState), EFeed.close()
  - unadvertise
```
public void unadvertise()
```
    Retracts this publisher feed from the associated notification subject. Does nothing if this feed is not currently advertised.
    
    Specified by:
    
    unadvertise in interface IEPublishFeed
    
    Throws:
    
    IllegalStateException - if this feed was closed and is inactive.
    
    See Also:
    
    advertise(), EFeed.close()
  - updateFeedState
```
public void updateFeedState(EFeedState update)
```
    Updates the publish feed state to the given value. If update equals the currently stored publish feed state, nothing is done. Otherwise, the updated value is stored. If this feed is advertised to the server and the subscription feed is up, then this update is forwarded to the subject.
    
    Specified by:
    
    updateFeedState in interface IEPublishFeed
    
    Parameters:
    
    update - the new publish feed state.
    
    Throws:
    
    NullPointerException - if update is null.
    
    IllegalStateException - if this feed was closed and is inactive or is not advertised.
  - publish
```
public void publish(ENotificationMessage msg)
```
    Posts this notification message to all interested subscribers.
    
    Specified by:
    
    publish in interface IEPublishFeed
    
    Parameters:
    
    msg - post this message to subscribers.
    
    Throws:
    
    NullPointerException - if msg is null.
    
    IllegalArgumentException - if msg message key does not match the feed message key.
    
    IllegalStateException - if this feed is inactive, not advertised or the publisher has not declared the feed to be up.
  - open
```
public static EPublishFeed open(EPublisher cl,
                                EMessageKey key,
                                EFeed.FeedScope scope,
                                EClient.ClientLocation l,
                                boolean isMulti)
```
    Returns a notification publish feed for the specified notification message class and subject.
    This method does not parameter validation since this is a package private method.
    
    Parameters:
    
    cl - the application object publishing 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 the feed supports local feeds, remote feeds, 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:
    
    a new notification feed for the given application object and message key.
  - 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 EPublishFeed

Example use of EPublishFeed

Updating Feed State

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

mAdvertisers

mFeedType

mSubject

mActivationCount

Method Detail

inactivate

isAdvertised

publishState

isFeedUp

isFeedUp

open

statusCallback

advertise

unadvertise

updateFeedState

publish

open

toString

key

messageSubject

activationCount

Example use of `EPublishFeed`