001package org.intellimate.izou.system.context;
002
003import org.intellimate.izou.events.EventModel;
004import org.intellimate.izou.events.EventCallable;
005import org.intellimate.izou.events.EventListenerModel;
006import org.intellimate.izou.events.MultipleEventsException;
007import org.intellimate.izou.identification.Identification;
008import org.intellimate.izou.identification.IllegalIDException;
009
010import java.util.List;
011import java.util.Optional;
012
013/**
014 * @author Leander Kurscheidt
015 * @version 1.0
016 */
017public interface Events {
018    /**
019     * Adds an listener for events that gets called before the generation of the resources and the outputPlugins..
020     * <p>
021     * Be careful with this method, it will register the listener for ALL the informations found in the Event. If your
022     * event-type is a common event type, it will fire EACH time!.
023     * It will also register for all Descriptors individually!
024     * It will also ignore if this listener is already listening to an Event.
025     * Method is thread-safe.
026     * </p>
027     * @param event the Event to listen to (it will listen to all descriptors individually!)
028     * @param eventListener the ActivatorEventListener-interface for receiving activator events
029     * @throws IllegalIDException not yet implemented
030     */
031    void registerEventListener(EventModel event, EventListenerModel eventListener) throws IllegalIDException;
032
033    /**
034     * Adds an listener for events that gets called before the generation of the resources and the outputPlugins..
035     * <p>
036     * It will register for all ids individually!
037     * This method will ignore if this listener is already listening to an Event.
038     * Method is thread-safe.
039     * </p>
040     * @param ids this can be type, or descriptors etc.
041     * @param eventListener the ActivatorEventListener-interface for receiving activator events
042     */
043    void registerEventListener(List<String> ids, EventListenerModel eventListener);
044
045    /**
046     * unregister an EventListener that gets called before the generation of the resources and the outputPlugins.
047     *<p>
048     * It will unregister for all Descriptors individually!
049     * It will also ignore if this listener is not listening to an Event.
050     * Method is thread-safe.
051     *
052     * @param event the Event to stop listen to
053     * @param eventListener the ActivatorEventListener used to listen for events
054     * @throws IllegalArgumentException if Listener is already listening to the Event or the id is not allowed
055     */
056    void unregisterEventListener(EventModel event, EventListenerModel eventListener);
057
058    /**
059     * unregister an EventListener that gets called before the generation of the resources and the outputPlugins.
060     *<p>
061     * It will unregister for all Descriptors individually!
062     * It will also ignore if this listener is not listening to an Event.
063     * Method is thread-safe.
064     *
065     * @param eventListener the ActivatorEventListener used to listen for events
066     * @throws IllegalArgumentException if Listener is already listening to the Event or the id is not allowed
067     */
068    void unregisterEventListener(EventListenerModel eventListener);
069
070    /**
071     * Adds an listener for events that gets called when the event finished processing.
072     * <p>
073     * Be careful with this method, it will register the listener for ALL the informations found in the Event. If your
074     * event-type is a common event type, it will fire EACH time!.
075     * It will also register for all Descriptors individually!
076     * It will also ignore if this listener is already listening to an Event.
077     * Method is thread-safe.
078     * </p>
079     * @param event the Event to listen to (it will listen to all descriptors individually!)
080     * @param eventListener the ActivatorEventListener-interface for receiving activator events
081     * @throws IllegalIDException not yet implemented
082     */
083    void registerEventFinishedListener(EventModel event, EventListenerModel eventListener) throws IllegalIDException;
084
085    /**
086     * Adds an listener for events that gets called when the event finished processing.
087     * <p>
088     * It will register for all ids individually!
089     * This method will ignore if this listener is already listening to an Event.
090     * Method is thread-safe.
091     * </p>
092     * @param ids this can be type, or descriptors etc.
093     * @param eventListener the ActivatorEventListener-interface for receiving activator events
094     */
095    void registerEventFinishedListener(List<String> ids, EventListenerModel eventListener);
096
097    /**
098     * unregister an EventListener that got called when the event finished processing.
099     *<p>
100     * It will unregister for all Descriptors individually!
101     * It will also ignore if this listener is not listening to an Event.
102     * Method is thread-safe.
103     *
104     * @param event the Event to stop listen to
105     * @param eventListener the ActivatorEventListener used to listen for events
106     * @throws IllegalArgumentException if Listener is already listening to the Event or the id is not allowed
107     */
108    void unregisterEventFinishedListener(EventModel event, EventListenerModel eventListener);
109
110    /**
111     * unregister an EventListener that got called when the event finished processing.
112     *<p>
113     * It will unregister for all Descriptors individually!
114     * It will also ignore if this listener is not listening to an Event.
115     * Method is thread-safe.
116     *
117     * @param eventListener the ActivatorEventListener used to listen for events
118     * @throws IllegalArgumentException if Listener is already listening to the Event or the id is not allowed
119     */
120    void unregisterEventFinishedListener(EventListenerModel eventListener);
121
122    /**
123     * Registers with the LocalEventManager to fire an event.
124     * <p>
125     * Note: the same Event can be fired from multiple sources.
126     * Method is thread-safe.
127     * @param identification the Identification of the the instance
128     * @return an Optional, empty if already registered
129     * @throws IllegalIDException not yet implemented
130     */
131    Optional<EventCallable> registerEventCaller(Identification identification) throws IllegalIDException;
132
133    /**
134     * Unregister with the LocalEventManager.
135     * <p>
136     * Method is thread-safe.
137     * @param identification the Identification of the the instance
138     */
139    void unregisterEventCaller(Identification identification);
140
141    /**
142     * This method fires an Event
143     *
144     * @param event the fired Event
145     * @throws java.lang.IllegalAccessError not yet implemented
146     * @throws IllegalIDException not yet implemented
147     * @throws MultipleEventsException if there is currently another Event processing
148     */
149    void fireEvent(EventModel event) throws IllegalIDException, MultipleEventsException;
150
151    /**
152     * returns the API for the EventsDistributor
153     * @return Distributor
154     */
155    public EventsDistributor distributor();
156
157    /**
158     * returns the ID of the Manager (LocalEventManager)
159     * @return an instance of Identification
160     */
161    Identification getManagerIdentification();
162}