net.sergeych.informer

Class Informer

java.lang.Object

net.sergeych.informer.Informer

public class Informer
extends java.lang.Object

The mechanism to convey any type of events to subscribers. Inspired by the EventBus. Unlike the latter provides either strong ot weak references of subscriber objects and an ability to prevent further event processing from the subscripber.

Simple sample:

 public class Foo {
     @Subscriber
     public void onEvent(SomeEvent event) {
         //...
     }
 }

 Foo foo = new Foo();
 Informer informer = new Informer();
 informer.registerStrong(foo);
 // ...
 informer.post(new SomeEvent());

 

It is possible subscriber exceptions and catch unprocessed events, support for Event hierarchies (e.g. subscrive to event superclass or any type with Object). See post(Object), registerStrong(Object), registerWeak(Object) for further details.

Created by sergeych on 13/02/16.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Informer.ExceptionContext Context to carry subscriber exception information
static interface	Informer.ExceptionListener Listener for exceptions thrown by subscribers

Constructor Summary

Constructors

Constructor and Description
Informer()
Informer(Informer.ExceptionListener listener) Create informer that listens to the subscriber exceptions which are otherwise ignored with no report.

Method Summary

Modifier and Type	Method and Description
void	post(java.lang.Object event) Synchronously post an event.
void	postAfter(java.lang.Object event, long millis) Post an event to subscribers after the specified timeout, see post(Object) for details.
void	register(java.lang.Object subscriber, boolean registerWeak) Register a subscriber object as a strong or a weak reference.
void	registerStrong(java.lang.Object subscriber) Register subscriber as a strong reference, and it will be retained at least as long as it is registered and the Informer instance is not collected.
void	registerWeak(java.lang.Object subscriber) Register a subscriber object as a weak reference.
boolean	unregister(java.lang.Object subscriber) Unregister subscriber.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Informer

public Informer()

Informer

public Informer(Informer.ExceptionListener listener)

Create informer that listens to the subscriber exceptions which are otherwise ignored with no report.

Parameters:

listener -

Method Detail

post

public void post(java.lang.Object event)

Synchronously post an event. Will block until all matching subscribers will be called.

Parameters:

event -

postAfter

public void postAfter(java.lang.Object event,
                      long millis)

Post an event to subscribers after the specified timeout, see post(Object) for details. Subscribers will be informed adter specified interval from some other thread. The call returns immediately.

Parameters:

event - event to post

millis - timeout to wait before posting

registerWeak

public void registerWeak(java.lang.Object subscriber)

Register a subscriber object as a weak reference. See register(Object, boolean) for more.

Parameters:

subscriber -

registerStrong

public void registerStrong(java.lang.Object subscriber)

Register subscriber as a strong reference, and it will be retained at least as long as it is registered and the Informer instance is not collected. See register(Object, boolean) for more.

Parameters:

subscriber -

unregister

public boolean unregister(java.lang.Object subscriber)

Unregister subscriber.

Parameters:

subscriber - to unregister.

Returns:

true if this subscriber was previously registered.

register

public void register(java.lang.Object subscriber,
                     boolean registerWeak)

Register a subscriber object as a strong or a weak reference. Strong reference will guarantee that the subscriber object will not be reclaimed as long as it is not unregistered and the informer object is alive.

The old subscription of this object if any will be removed. e.g. you can re-register it as weak, then the strong registration will be thrown. The same, no matter how many time the subscriber was registered, its @Subscriber methods will be called only once per post(Object) invocation.

To receive events, subscriber class declares one or more public methods with @Subscriber annotation and the single argument. Suchm methods should return void or boolean, in which case returning true instructs notifier to not to pass this event to any other subscribers. Subscriber receive only objects that can be casted to its declared argument type, this way you can have subscribers to process different types of events.

It is allowed to have several subsciber methods ofr the same type of argument in the same class. No restrictions :)

In the cases there is no suitable subscribers for some evvent, it will be reposted inside the LostEvent instance that could be subscribed as usual.

Any exceptions inside the subscriber are ignored

See Subscriber for details on event processing.

Parameters:

subscriber - instance, should be of the public class.

registerWeak -