net.sf.eBus.client.ESubscriber Maven / Gradle / Ivy
//
// Copyright 2008, 2011, 2013, 2015, 2016 Charles W. Rapp
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
package net.sf.eBus.client;
import net.sf.eBus.messages.ENotificationMessage;
/**
* Classes wanting to receive eBus notification messages need to
* implement this interface. The application subscriber first
* open an {@link ESubscribeFeed} using a
* {@link ESubscribeFeed.Builder} instance (acquired by calling
* {@link ESubscribeFeed#builder()}) and
* {@link ESubscribeFeed#subscribe() subscribes} to the
* notification. eBus calls
* {@link #feedStatus(EFeedState, IESubscribeFeed)} to inform the
* subscriber about whether the notification feed is
* {@link EFeedState#UP up} or {@link EFeedState#DOWN down}. If
* down, then the subscriber will not receive calls to
* {@link #notify(ENotificationMessage, IESubscribeFeed)} until
* the feed comes back up. If up, then subscriber may receive
* notifications depending on whether the publisher(s) send any
* messages. When a subscriber shuts down, it should
* {@link ESubscribeFeed#unsubscribe() unsubscribe} or
* {@link EFeed#close() close} the feed. If the subscriber does
* not do this, eBus will automatically retract the subscription
* when it detects the subscriber 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 subscriber callbacks. This is done by calling
* {@link ESubscribeFeed.Builder#statusCallback(FeedStatusCallback)}
* and/or
* {@link ESubscribeFeed.Builder#notifyCallback(NotifyCallback)}
* passing in a lambda expression to specify the callback target.
* Still, the application must either override {@code EReplier}
* interface methods or put callbacks in place. Failure
* to do either results in {@link ESubscribeFeed#subscribe()}
* failing. A class wishing to subscribe to notification
* messages must still implement {@code ESubscriber} even though
* it is no longer necessary to override the interface methods.
*
*
* It is possible to mix and match {@code ESubscriber} overrides
* and callbacks. That is, a notify callback can be used in
* conjunction with a
* {@link ESubscriber#feedStatus(EFeedState, IESubscribeFeed)}
* override.
*
*
* @see ENotifySubject
* @see EPublisher
* @see ESubscribeFeed
* @see ENotificationMessage
* @see IESubscribeFeed
*
* @author Charles Rapp
*/
public interface ESubscriber
extends EObject
{
/**
* eBus calls this method to inform the subscriber that the
* subscribe notification feed is either
* {@link EFeedState#UP up} or {@link EFeedState#DOWN down}.
* If down, then
* {@link #notify(ENotificationMessage, IESubscribeFeed)} will
* not be called until the feed comes back up. If up, then
* the subscriber will receive all notifications published on
* {@code feed} until the subscription is retracted or the
* feed goes down.
* @param feedState the subscription's new feed state.
* @param feed the status applies to this feed.
* @throws UnsupportedOperationException
* if implementing class does not override this method nor
* uses a callback.
*
* @see #notify(ENotificationMessage, IESubscribeFeed)
*/
default void feedStatus(EFeedState feedState,
IESubscribeFeed feed)
{
throw (
new UnsupportedOperationException(
"feedStatus not implemented"));
} // end of feedStatus(EFeedState, ESubscribeFeed)
/**
* An incoming notification message from {@code feed}.
* @param msg eBus notification message.
* @param feed the associated subscription feed.
* @throws UnsupportedOperationException
* if implementing class does not override this method nor
* uses a callback.
*
* @see #feedStatus(EFeedState, IESubscribeFeed)
*/
default void notify(ENotificationMessage msg,
IESubscribeFeed feed)
{
throw (
new UnsupportedOperationException(
"notify not implemented"));
} // end of notify(ENotificationMessage, ESubscribeFeed)
} // end of interface ESubscriber