net.sf.eBus.client

Interface EPublisher

All Superinterfaces:

EObject

All Known Implementing Classes:

ERemoteApp, EServer

public interface EPublisher
extends EObject

Classes wanting to send eBus notifications need to implement this interface. A publisher must open and advertise the notification feeds it supports. Once eBus accepts the advertisement, a publisher has two options:

1. Wait for a call to its publishStatus(EFeedState, IEPublishFeed) method where feedState set to up before publishing feed. In this option, it is necessary to call IEPublishFeed.updateFeedState(EFeedState) with up status before publishing the first notification.

   When there are no more subscribers, eBus calls publishStatus(EFeedState, IEPublishFeed) with a down feed state. The publisher must then stop publishing on the IEPublishFeed.

2. Call IEPublishFeed.updateFeedState(EFeedState) with up feed state and then start publishing notifications on that feed after checking that IEFeed.isFeedUp() returns true before calling IEPublishFeed.publish(net.sf.eBus.messages.ENotificationMessage). Alternatively, catch IllegalStateException thrown by IEPublishFeed.publish() when the feed is down.

When the application publisher shuts down, then it should unadvertise or IEFeed.close() the feed. There is no need to call IEPublishFeed.updateFeedState(EFeedState.DOWN) as this is automatically done by unadvertise and close. If the publisher does not do this, eBus will automatically retract the advertisement when it detects the publisher is finalized.

As of eBus v. 4.2.0, implementing the interface methods is no longer necessary. Instead, Java lambda expressions may be used to handle publisher callbacks. This is done by calling IEPublishFeed.statusCallback(FeedStatusCallback) and using a lambda expression to specify the callback target. Still, the application must either override EPublisher callback method or put the status callback in place. Failure to do either results in IEPublishFeed.advertise() failing. A class wishing to publish notification messages must still implement EPublisher even though it is no longer necessary to override the interface method.

The reason for separate IEPublishFeed.advertise() and IEPublishFeed.updateFeedState(EFeedState) methods is to distinguish between the publisher existing or not and whether the publisher is able to publish the notification. Here are two examples of how to use updateFeedState.

Example 1: External Monitor Publisher

An eBus-based application routinely reads input from a serial port and publishes those readings in a notification message. On start up, the application publisher opens its notification feed and advertises it. Once the application publisher opens the serial port and establishes communication with the monitor, the publisher then reports the feed is up. If communication to the monitor is lost, then a down feed state is reported. This feed state continues until monitor communications is re-established.

Example 2: Value-added Publisher

An application instance implements both ESubscriber and EPublisher. This instance performs value-added computation on the received notifications and publishes the results. Again, the instance opens and advertises its feed but leaves its initial publish status in the down state. The instance then subscribes to its inbound feeds. When all those feeds are up, the instance then sets its outbound feed state to up. If any of the inbound feeds receives a feed state update with a down state, then the published feed is then set to down. This continues until the inbound feed comes back up. This is an example of a publish state change cascading along a publisher, subscriber chain.

If the application publisher is always capable of publishing its feed without interruption, then it is sufficient to call IEPublishFeed.updateFeedState(FeedState.UP) immediately after IEPublishFeed.advertise().

Author:

Charles Rapp

See Also:

ENotifySubject, ESubscriber, EPublishFeed, IEPublishFeed, ENotificationMessage

Method Summary

Modifier and Type	Method and Description
default void	publishStatus(EFeedState feedState, IEPublishFeed feed) eBus is requesting that the publisher either start or stop publishing the specified feed.

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

shutdown, startup

Method Detail

publishStatus

default void publishStatus(EFeedState feedState,
                           IEPublishFeed feed)

eBus is requesting that the publisher either start or stop publishing the specified feed. If feedState is up, the publisher is free to start publishing notification messages on the feed when IEPublishFeed.updateFeedState(EFeedState) is called with an up state. If feedState is down, then the publisher may not publish notifications on the feed.

Note: a publisher is allowed to publish notifications feed after publishStatus is called with an up state and the publisher calls IEPublishFeed.updateFeedState(EFeedState) with an up state. There is no order for these two events and are independent of each other.

Method publishStatus(EFeedState, IEPublishFeed) has a default definition which throws an UnsupportedOperationException. The reason for this default method implementation is to allow users to define a separate method with the signature void (EFeedState, IEPublishFeed) and then use IEPublishFeed.statusCallback(FeedStatusCallback) to use that defined method for publishStatus callbacks.

Parameters:

feedState - up to start the feed and down to stop the feed.

feed - start or stop publishing this feed.

Throws:

UnsupportedOperationException - if implementing class does not override this method nor uses a callback.