discord4j.core.event

Class EventDispatcher

java.lang.Object

discord4j.core.event.EventDispatcher

public class EventDispatcher
extends Object

Distributes events to subscribers. Event instances can be published over this class and dispatched to all subscribers.

Individual events can be published to subscribers using publish(Event) while they can be used to consumed through on(Class) giving the proper Event class as argument.

Uses an underlying FluxProcessor that must be supplied on construction, as well as a Scheduler to define subscriber thread affinity.

Each event can be consumed using the following pattern:

     dispatcher.on(MessageCreatedEvent.class)
           .subscribe(event -> event.getMessage());
 

While events can be published through:

     fluxOfEvents.doOnNext(dispatcher::publish)
           .subscribe();
 

Constructor Summary

Constructors

Constructor and Description
EventDispatcher(FluxProcessor<Event,Event> processor, Scheduler scheduler) Creates a new event dispatcher using the given processor and thread model.

Method Summary

Modifier and Type	Method and Description
<E extends Event> Flux<E>	on(Class<E> eventClass) Retrieves a Flux with elements of the given Event type.
<E extends Event,T> Flux<T>	on(Class<E> eventClass, Function<E,Publisher<T>> mapper) Retrieves a Flux with elements of the given Event type, processing them through a given Function.
void	publish(Event event) Publishes an Event to the dispatcher.

Methods inherited from class java.lang.Object

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

Constructor Detail

EventDispatcher

public EventDispatcher(FluxProcessor<Event,Event> processor,
                       Scheduler scheduler)

Creates a new event dispatcher using the given processor and thread model.

Parameters:

processor - a FluxProcessor of Event types, used to bridge gateway events to the dispatcher subscribers

scheduler - a Scheduler to ensure a certain thread model on each published signal

Method Detail

on

public <E extends Event> Flux<E> on(Class<E> eventClass)

Retrieves a Flux with elements of the given Event type.

Note: Errors occurring while processing events will terminate your sequence. If you wish to use a version capable of handling errors for you, use on(Class, Function). See Reactive Streams Spec explaining this behavior.

A recommended pattern to use this method is wrapping your code that may throw exceptions within a flatMap block and use Mono.onErrorResume(Function), Flux.onErrorResume(Function) or equivalent methods to maintain the sequence active:

 client.getEventDispatcher().on(MessageCreateEvent.class)
     .flatMap(event -> myCodeThatMightThrow(event)
             .onErrorResume(error -> {
                 // log and then discard the error to keep the sequence alive
                 log.error("Failed to handle event!", error);
                 return Mono.empty();
             }))
     .subscribe();
 

For more alternatives to handling errors, please see Error Handling wiki page.

Type Parameters:

E - the type of the event class

Parameters:

eventClass - the event class to obtain events from

Returns:

a new Flux with the requested events

on

public <E extends Event,T> Flux<T> on(Class<E> eventClass,
                                      Function<E,Publisher<T>> mapper)

Retrieves a Flux with elements of the given Event type, processing them through a given Function. Errors occurring within the mapper will be logged and discarded, preventing the termination of the "infinite" event sequence.

There are multiple ways of using this event handling method, for example:

 client.getEventDispatcher()
     .on(MessageCreateEvent.class, event -> {
         // myCodeThatMightThrow should return a Reactor type (Mono or Flux)
         return myCodeThatMightThrow(event);
     })
     .subscribe();

 client.getEventDispatcher()
     .on(MessageCreateEvent.class, event -> {
         // myCodeThatMightThrow *can* be blocking
         myCodeThatMightThrow(event);
         return Mono.empty(); // but we have to return a Reactor type
     })
     .subscribe();
 

Continuing the chain after on(class, event -> ...) will require your own error handling strategy. Check the docs for on(Class) for more details.

Type Parameters:

E - the type of the event class

T - the type of the event mapper function

Parameters:

eventClass - the event class to obtain events from

mapper - an event mapping function called on each event. If you do not wish to perform further operations you can return Mono.empty().

Returns:

a new Flux with the type resulting from the given event mapper

publish

public void publish(Event event)

Publishes an Event to the dispatcher.

Parameters:

event - the Event to publish