org.refcodes.eventbus.EventBusObservable Maven / Gradle / Ivy
Show all versions of refcodes-eventbus Show documentation
package org.refcodes.eventbus;
import org.refcodes.component.HandleLookup;
import org.refcodes.observer.Event;
import org.refcodes.observer.EventMatcher;
import org.refcodes.observer.EventMatcherByDeclaration;
import org.refcodes.observer.MetaDataEvent;
import org.refcodes.observer.Observable;
import org.refcodes.observer.Observer;
import org.refcodes.observer.impls.MetaDataEventImpl;
/**
* The {@link Observable} part of the {@link EventBus} provides means to
* register {@link Observer} instances.
*
* In case your {@link EventBusObservable} notifies upon events of type
* {@link MetaDataEvent}, you may use the {@link MetaDataEventImpl} and an
* action for distinguishing your various types of notification:
*
* TIPP: In order to distinguish {@link MetaDataEventImpl} instances from each
* other, create an actions enumeration, enumerating the various event actions
* you support. Pass the actual action you intend to notify upon to the
* according constructor, as an {@link Observer} you may use the declarative
* method {@link EventMatcherByDeclaration#actionEqualWith(Object)} to test
* whether your action was notified (or a simple switch case statement).
*/
public interface EventBusObservable, O extends Observer, EM extends EventMatcher, H> extends HandleLookup {
/**
* Subscribes a listener to the event bus. In case the handle is being
* ignored, use the "unsubscribeAll" method where all subscriptions for a
* listener are removed.
*
* @param aObserver The {@link Observer} to subscribe.
* @param aEventMatcher The {@link EventMatcher} to guard the
* {@link Observer}.
*
* @return A handle to unsubscribe this combination.
*/
H subscribe( O aObserver, EM aEventMatcher );
/**
* Unsubscribes all registrations to a specific listener, even if that
* listener is involved in several subscriptions.
*
* @param aObserver
*/
void unsubscribeAll( O aObserver );
/**
* Unsubscribes the listener associated with the given handle.
*
* As of convenience, the type of the reference returned. CAUTION: The
* type being a sub-type of has the drawback that in case you
* specify a sub-type of (), you may end up with a class cast
* exception in case you do not make sure that the handle references the
* expected type .
*
* @param aHandle The handle in question.
*
* @return The event listener descriptor used to describe the listener and
* the provided criteria.
*
* @throws NoSuchHandleRuntimeException in case the handle is unknown by the
* event-bus.
*/
// > T unsubscribe( H aHandle ) throws
// UnknownHandleRuntimeException;
}