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>a <tt>RunnableWithArgs</tt></li>
069 * <li>a <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>a <tt>RunnableWithArgs</tt></li>
131 * <li>a <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 }
|