EventPublisher.java
001 /*
002  * SPDX-License-Identifier: Apache-2.0
003  *
004  * Copyright 2008-2017 the original author or authors.
005  *
006  * Licensed under the Apache License, Version 2.0 (the "License");
007  * you may not use this file except in compliance with the License.
008  * You may obtain a copy of the License at
009  *
010  *     http://www.apache.org/licenses/LICENSE-2.0
011  *
012  * Unless required by applicable law or agreed to in writing, software
013  * distributed under the License is distributed on an "AS IS" BASIS,
014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015  * See the License for the specific language governing permissions and
016  * limitations under the License.
017  */
018 package griffon.core.event;
019 
020 import griffon.core.CallableWithArgs;
021 import griffon.core.RunnableWithArgs;
022 
023 import javax.annotation.Nonnull;
024 import javax.annotation.Nullable;
025 import java.util.Collection;
026 import java.util.List;
027 import java.util.Map;
028 
029 /**
030  * Base contract for classes that can publish events using their own
031  * event bus.
032  *
033  @author Andres Almiray
034  @since 2.0.0
035  */
036 public interface EventPublisher {
037     /**
038      * Adds an event listener.<p>
039      * Accepted types are: Script, Map and Object.
040      *
041      @param listener an event listener
042      */
043     void addEventListener(@Nonnull Object listener);
044 
045     /**
046      * Adds a callable as an event listener.<p>
047      *
048      @param eventName the name of the event
049      @param listener  an event listener
050      @since 2.3.0
051      */
052     void addEventListener(@Nonnull String eventName, @Nonnull RunnableWithArgs listener);
053 
054     /**
055      * Adds a callable as an event listener.<p>
056      *
057      @param eventName the name of the event
058      @param listener  an event listener
059      @deprecated use the {@code RunnableWithArgs} variant instead.
060      */
061     @Deprecated
062     void addEventListener(@Nonnull String eventName, @Nonnull CallableWithArgs<?> listener);
063 
064     /**
065      * Adds a Map containing event listeners.<p>
066      <p>
067      * An event listener may be<ul>
068      <li><tt>RunnableWithArgs</tt></li>
069      <li><tt>CallableWithArgs</tt></li>
070      </ul>
071      <p>
072      * Maps require handlers to be named as eventName only.<p>
073      * Some examples of eventHandler names are: StartupStart, MyCoolEvent.
074      * Event names must follow the camelCase naming convention.<p>
075      *
076      @param listener an event listener of type Map
077      */
078     void addEventListener(@Nonnull Map<String, Object> listener);
079 
080     /**
081      * Adds a callable as an event listener.<p>
082      *
083      @param eventClass the type of the event
084      @param listener   an event listener
085      @deprecated use the {@code RunnableWithArgs} variant instead.
086      */
087     @Deprecated
088     <E extends Event> void addEventListener(@Nonnull Class<E> eventClass, @Nonnull CallableWithArgs<?> listener);
089 
090     /**
091      * Adds a callable as an event listener.<p>
092      *
093      @param eventClass the type of the event
094      @param listener   an event listener
095      @since 2.3.0
096      */
097     <E extends Event> void addEventListener(@Nonnull Class<E> eventClass, @Nonnull RunnableWithArgs listener);
098 
099     /**
100      * Removes an event listener.<p>
101      * Accepted types are: Script, Map and Object.
102      *
103      @param listener an event listener
104      */
105     void removeEventListener(@Nonnull Object listener);
106 
107     /**
108      * Removes a callable as an event listener.<p>
109      *
110      @param eventName the name of the event
111      @param listener  an event listener
112      @since 2.3.0
113      */
114     void removeEventListener(@Nonnull String eventName, @Nonnull RunnableWithArgs listener);
115 
116     /**
117      * Removes a callable as an event listener.<p>
118      *
119      @param eventName the name of the event
120      @param listener  an event listener
121      @deprecated use the {@code RunnableWithArgs} variant instead.
122      */
123     @Deprecated
124     void removeEventListener(@Nonnull String eventName, @Nonnull CallableWithArgs<?> listener);
125 
126     /**
127      * Removes a Map containing event listeners.<p>
128      <p>
129      * An event listener may be<ul>
130      <li><tt>RunnableWithArgs</tt></li>
131      <li><tt>CallableWithArgs</tt></li>
132      </ul>
133      <p>
134      * Maps require handlers to be named as eventName only.<p>
135      * Some examples of eventHandler names are: StartupStart, MyCoolEvent.
136      * Event names must follow the camelCase naming convention.<p>
137      *
138      @param listener an event listener of type Map
139      */
140     void removeEventListener(@Nonnull Map<String, Object> listener);
141 
142     /**
143      * Removes a callable as an event listener.<p>
144      *
145      @param eventClass the type of the event
146      @param listener   an event listener
147      @since 2.3.0
148      */
149     <E extends Event> void removeEventListener(@Nonnull Class<E> eventClass, @Nonnull RunnableWithArgs listener);
150 
151     /**
152      * Removes a callable as an event listener.<p>
153      *
154      @param eventClass the type of the event
155      @param listener   an event listener
156      @deprecated use the {@code RunnableWithArgs} variant instead.
157      */
158     @Deprecated
159     <E extends Event> void removeEventListener(@Nonnull Class<E> eventClass, @Nonnull CallableWithArgs<?> listener);
160 
161     /**
162      * Publishes an event.<p>
163      * Listeners will be notified in the same thread as the publisher.
164      *
165      @param eventName the name of the event
166      */
167     void publishEvent(@Nonnull String eventName);
168 
169     /**
170      * Publishes an event.<p>
171      * Listeners will be notified in the same thread as the publisher.
172      *
173      @param eventName the name of the event
174      @param args      event arguments sent to listeners
175      */
176     void publishEvent(@Nonnull String eventName, @Nullable List<?> args);
177 
178     /**
179      * Publishes an event.<p>
180      * Listeners will be notified in the same thread as the publisher.
181      *
182      @param event the event to be published
183      */
184     void publishEvent(@Nonnull Event event);
185 
186     /**
187      * Publishes an event.<p>
188      * Listeners will be notified outside of the UI thread.
189      *
190      @param eventName the name of the event
191      */
192     void publishEventOutsideUI(@Nonnull String eventName);
193 
194     /**
195      * Publishes an event.<p>
196      * Listeners will be notified outside of the UI thread.
197      *
198      @param eventName the name of the event
199      @param args      event arguments sent to listeners
200      */
201     void publishEventOutsideUI(@Nonnull String eventName, @Nullable List<?> args);
202 
203     /**
204      * Publishes an event.<p>
205      * Listeners will be notified outside of the UI thread.
206      *
207      @param event the event to be published
208      */
209     void publishEventOutsideUI(@Nonnull Event event);
210 
211     /**
212      * Publishes an event.<p>
213      * Listeners will be notified in a different thread.
214      *
215      @param eventName the name of the event
216      */
217     void publishEventAsync(@Nonnull String eventName);
218 
219     /**
220      * Publishes an event.<p>
221      * Listeners will be notified in a different thread.
222      *
223      @param eventName the name of the event
224      @param args      event arguments sent to listeners
225      */
226     void publishEventAsync(@Nonnull String eventName, @Nullable List<?> args);
227 
228     /**
229      * Publishes an event.<p>
230      * Listeners will be notified in a different thread.
231      *
232      @param event the event to be published
233      */
234     void publishEventAsync(@Nonnull Event event);
235 
236     /**
237      * Returns whether events will be published by the event bus or not.
238      *
239      @return true if event publishing is enabled; false otherwise.
240      */
241     boolean isEventPublishingEnabled();
242 
243     /**
244      * Sets the enabled state for event publishing.</p>
245      * Events will be automatically discarded when the enabled state is set to false.
246      *
247      @param enabled the value fot the enabled state.
248      */
249     void setEventPublishingEnabled(boolean enabled);
250 
251     /**
252      * Returns an immutable snapshot view of all event listeners registered.
253      *
254      @return an immutable collection of all registered listeners.
255      @since 2.6.0
256      */
257     @Nonnull
258     Collection<Object> getEventListeners();
259 
260     /**
261      * Returns an immutable snapshot view of all event listeners registered for the target event name.
262      *
263      @param eventName the name of the event
264      @return an immutable collection of all registered listeners for the target event name.
265      @since 2.6.0
266      */
267     @Nonnull
268     Collection<Object> getEventListeners(@Nonnull String eventName);
269 }