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:
Build
a publish feed for a given EPublisher
instance and
type+topic message key
.
Use EPublishFeed.Builder.statusCallback(FeedStatusCallback)
to set Java lamdba expression used in place of
EPublisher
interface method.
Step 3: 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 4: 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 5: Start publishing notifications. Note
that
updateFeedState(EFeedState)
with an up feed state
must be done prior to publishing notifications.
Step 6: When the publisher is shutting down,
retract
the notification advertisement
and close
the feed.
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 {
// 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;
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. Place EPublisher interface method overrides here.
// This publisher overrides EPublisher interface method.
mFeed = (EPublishFeed.builder()).target(this)
.messageKey(mKey)
.scope(mScope)
.build();
// Step 3: 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 4: Handle publish status update.
@Override
public void publishStatus(final EFeedState feedState, final IEPublishFeed feed) {
// Are we starting a feed?
if (feedState == EFeedState.UP) {
// Yes. Start publishing notifications on the feed.
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 5: Start publishing notifications.
mFeed.publish((CatalogUpdate.builder()).subject(mKey.subject)
.timestamp(Instant.now())
.productName(productName)
.price(price)
.inStockQuantity(stockQty)
.build());
}
}
// Retract the notification feed.
@Override
public void shutdown() {
Step 6: 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.
}
}
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.
Modifier and Type | Class and Description |
---|---|
static class |
EPublishFeed.Builder
EPublishFeed.Builder is now the preferred
mechanism for creating a EPublishFeed instance. |
protected static class |
net.sf.eBus.client.ESingleFeed.FeedType
Enumerates the supported feed types.
|
EFeed.AbstractClientTask, EFeed.FeedScope, EFeed.NotifyTask, EFeed.StatusTask<T extends IEFeed>
Modifier and Type | Field and Description |
---|---|
protected int |
mActivationCount
Tracks the number of contra-feeds matched to this feed.
|
protected net.sf.eBus.client.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.
|
FEED_IS_INACTIVE, FEED_NOT_ADVERTISED, mEClient, mFeedId, mFeedState, mInPlace, mIsActive, mScope, NO_CONDITION, NOTIFY_METHOD, NULL_CLIENT
Modifier and Type | Method and Description |
---|---|
int |
activationCount()
Returns the feed activation count.
|
void |
advertise()
Advertises this publisher feed to the associated
notification subject.
|
static EPublishFeed.Builder |
builder()
Returns a new
EPublishFeed builder instance. |
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(java.lang.String subject)
|
EMessageKey |
key()
Returns the feed message key.
|
java.lang.String |
messageSubject()
Returns the feed
message key subect . |
void |
publish(ENotificationMessage msg)
Posts this notification message to all interested
subscribers.
|
EFeedState |
publishState()
Returns the publish state.
|
java.lang.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.
|
protected static void |
validateOpenParams(EPublisher client,
EMessageKey key,
EFeed.FeedScope scope)
Verifies that meet the required feed opening constraints;
if this verification fails, then the appropriate
exception is thrown.
|
addAllKeys, addKey, addListener, checkScopes, clientId, close, createDispatcher, defaultDispatcher, eClient, equals, feedId, feedState, findKeys, findKeys, findKeys, hashCode, inPlace, isActive, isOverridden, loadKeys, location, register, register, register, removeListener, scope, setExhaust, shutdown, shutdown, shutdownAll, startup, startup, startupAll, storeKeys, storeKeys, storeKeys, subclassDistance
protected final net.sf.eBus.client.ESingleFeed.FeedType mFeedType
protected final net.sf.eBus.client.ESubject mSubject
feed type
.protected int mActivationCount
protected void inactivate()
inactivate
in class EFeed
public boolean isAdvertised()
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
.
isAdvertised
in interface IEPublishFeed
true
if this publish feed is open and
advertised.EFeed.isActive()
,
isFeedUp()
,
publishState()
public EFeedState publishState()
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.publishState
in interface IEPublishFeed
public boolean isFeedUp(java.lang.String subject)
true
if subject
equals this feed's
subject and isFeedUp()
is true
. Otherwise,
returns false
.isFeedUp
in interface IEPublishFeed
subject
- check if the feed for this subject is up.true
if the publisher feed is up for the
specified subject and the publisher is free to publish
notification messages.public final boolean isFeedUp()
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.isFeedUp
in interface IEFeed
isFeedUp
in class EFeed
true
if the publisher feed is up and the
publisher is free to publish notification messages.EFeed.isActive()
,
isAdvertised()
public void advertise()
EPublisher.publishStatus(EFeedState, IEPublishFeed)
with an up
feed state.
updateFeedState(EFeedState)
with an
EFeedState.UP up
publish state.
publish(ENotificationMessage)
may
be called.advertise
in interface IEPublishFeed
java.lang.IllegalStateException
- if this feed is closed or the client did not override
EPublisher
methods nor put the required callback
in place.unadvertise()
,
updateFeedState(EFeedState)
,
EFeed.close()
public void unadvertise()
unadvertise
in interface IEPublishFeed
java.lang.IllegalStateException
- if this feed was closed and is inactive.advertise()
,
EFeed.close()
public void updateFeedState(EFeedState update)
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.updateFeedState
in interface IEPublishFeed
update
- the new publish feed state.java.lang.NullPointerException
- if update
is null
.java.lang.IllegalStateException
- if this feed was closed and is inactive or is not
advertised.public void publish(ENotificationMessage msg)
publish
in interface IEPublishFeed
msg
- post this message to subscribers.java.lang.NullPointerException
- if msg
is null
.java.lang.IllegalArgumentException
- if msg
message key does not match the feed message
key.java.lang.IllegalStateException
- if this feed is inactive, not advertised or the publisher
has not declared the feed to be up.public static EPublishFeed.Builder builder()
EPublishFeed
builder instance. This
instance should be used to build a single notification
publish feed instance and not used to create multiple
such feeds.protected static void validateOpenParams(EPublisher client, EMessageKey key, EFeed.FeedScope scope)
client
- application object publishing notification
messages. May not be null
.key
- 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. May not be null
.java.lang.NullPointerException
- if any of the arguments are null
.java.lang.IllegalArgumentException
- if any of the arguments is invalid.public java.lang.String toString()
public final EMessageKey key()
EPublishFeed
, then a
notification
message key is returned.public final java.lang.String messageSubject()
message key subect
.public final int activationCount()
Copyright © 2001 - 2024. Charles W. Rapp. All rights reserved.