001package org.intellimate.izou.system.context;
002
003import org.intellimate.izou.events.EventCallable;
004import org.intellimate.izou.events.EventModel;
005import org.intellimate.izou.events.EventsControllerModel;
006import org.intellimate.izou.identification.Identification;
007import org.intellimate.izou.identification.IllegalIDException;
008
009import java.util.Optional;
010
011/**
012 * @author Leander Kurscheidt
013 * @version 1.0
014 */
015public interface EventsDistributor {
016    /**
017     * with this method you can register EventPublisher add a Source of Events to the System.
018     * <p>
019     * This method represents a higher level of abstraction! Use the EventManager to fire Events!
020     * This method is intended for use cases where you have an entire new source of events (e.g. network)
021     * @param identification the Identification of the Source
022     * @return An Optional Object which may or may not contains an EventPublisher
023     * @throws IllegalIDException not yet implemented
024     */
025    Optional<EventCallable> registerEventPublisher(Identification identification) throws IllegalIDException;
026
027    /**
028     * with this method you can unregister EventPublisher add a Source of Events to the System.
029     * <p>
030     * This method represents a higher level of abstraction! Use the EventManager to fire Events!
031     * This method is intended for use cases where you have an entire new source of events (e.g. network)
032     * @param identification the Identification of the Source
033     */
034    void unregisterEventPublisher(Identification identification);
035
036    /**
037     * Registers an EventController to control EventDispatching-Behaviour
038     * <p>
039     * Method is thread-safe.
040     * It is expected that this method executes quickly.
041     *
042     * @param eventsController the EventController Interface to control event-dispatching
043     * @throws IllegalIDException not yet implemented
044     */
045    void registerEventsController(EventsControllerModel eventsController) throws IllegalIDException;
046
047    /**
048     * Unregisters an EventController
049     * <p>
050     * Method is thread-safe.
051     *
052     * @param eventsController the EventController Interface to remove
053     */
054    void unregisterEventsController(EventsControllerModel eventsController);
055
056    /**
057     * fires the event concurrently, this is generally discouraged.
058     * <p>
059     * This method should not be used for normal Events, for for events which obey the following laws:<br>
060     * 1. they are time critical.<br>
061     * 2. addons are not expected to react in any way beside a small update<br>
062     * 3. they are few.<br>
063     * if your event matches the above laws, you may consider firing it concurrently.
064     * </p>
065     * @param eventModel the EventModel
066     */
067    void fireEventConcurrently(EventModel<?> eventModel);
068
069    /**
070     * returns the ID of the Manager (EventsDistributor)
071     * @return an instance of Identification
072     */
073    Identification getManagerIdentification();
074}