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