001 /*
002 * Copyright 2008-2015 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.List;
024 import java.util.Map;
025
026 /**
027 * Base contract for classes that can publish events using their own
028 * event bus.
029 *
030 * @author Andres Almiray
031 * @since 2.0.0
032 */
033 public interface EventPublisher {
034 /**
035 * Adds an event listener.<p>
036 * Accepted types are: Script, Map and Object.
037 *
038 * @param listener an event listener
039 */
040 void addEventListener(@Nonnull Object listener);
041
042 /**
043 * Adds a callable as an event listener.<p>
044 *
045 * @param eventName the name of the event
046 * @param listener an event listener
047 * @since 2.3.0
048 */
049 void addEventListener(@Nonnull String eventName, @Nonnull RunnableWithArgs listener);
050
051 /**
052 * Adds a callable as an event listener.<p>
053 *
054 * @param eventName the name of the event
055 * @param listener an event listener
056 * @deprecated use the {@code RunnableWithArgs} variant instead.
057 */
058 @Deprecated
059 void addEventListener(@Nonnull String eventName, @Nonnull CallableWithArgs<?> listener);
060
061 /**
062 * Adds a Map containing event listeners.<p>
063 * <p>
064 * An event listener may be<ul>
065 * <li>a <tt>RunnableWithArgs</tt></li>
066 * <li>a <tt>CallableWithArgs</tt></li>
067 * </ul>
068 * <p>
069 * Maps require handlers to be named as eventName only.<p>
070 * Some examples of eventHandler names are: StartupStart, MyCoolEvent.
071 * Event names must follow the camelCase naming convention.<p>
072 *
073 * @param listener an event listener of type Map
074 */
075 void addEventListener(@Nonnull Map<String, Object> listener);
076
077 /**
078 * Adds a callable as an event listener.<p>
079 *
080 * @param eventClass the type of the event
081 * @param listener an event listener
082 * @deprecated use the {@code RunnableWithArgs} variant instead.
083 */
084 @Deprecated
085 <E extends Event> void addEventListener(@Nonnull Class<E> eventClass, @Nonnull CallableWithArgs<?> listener);
086
087 /**
088 * Adds a callable as an event listener.<p>
089 *
090 * @param eventClass the type of the event
091 * @param listener an event listener
092 * @since 2.3.0
093 */
094 <E extends Event> void addEventListener(@Nonnull Class<E> eventClass, @Nonnull RunnableWithArgs listener);
095
096 /**
097 * Removes an event listener.<p>
098 * Accepted types are: Script, Map and Object.
099 *
100 * @param listener an event listener
101 */
102 void removeEventListener(@Nonnull Object listener);
103
104 /**
105 * Removes a callable as an event listener.<p>
106 *
107 * @param eventName the name of the event
108 * @param listener an event listener
109 * @since 2.3.0
110 */
111 void removeEventListener(@Nonnull String eventName, @Nonnull RunnableWithArgs listener);
112
113 /**
114 * Removes a callable as an event listener.<p>
115 *
116 * @param eventName the name of the event
117 * @param listener an event listener
118 * @deprecated use the {@code RunnableWithArgs} variant instead.
119 */
120 @Deprecated
121 void removeEventListener(@Nonnull String eventName, @Nonnull CallableWithArgs<?> listener);
122
123 /**
124 * Removes a Map containing event listeners.<p>
125 * <p>
126 * An event listener may be<ul>
127 * <li>a <tt>RunnableWithArgs</tt></li>
128 * <li>a <tt>CallableWithArgs</tt></li>
129 * </ul>
130 * <p>
131 * Maps require handlers to be named as eventName only.<p>
132 * Some examples of eventHandler names are: StartupStart, MyCoolEvent.
133 * Event names must follow the camelCase naming convention.<p>
134 *
135 * @param listener an event listener of type Map
136 */
137 void removeEventListener(@Nonnull Map<String, Object> listener);
138
139 /**
140 * Removes a callable as an event listener.<p>
141 *
142 * @param eventClass the type of the event
143 * @param listener an event listener
144 * @since 2.3.0
145 */
146 <E extends Event> void removeEventListener(@Nonnull Class<E> eventClass, @Nonnull RunnableWithArgs listener);
147
148 /**
149 * Removes a callable as an event listener.<p>
150 *
151 * @param eventClass the type of the event
152 * @param listener an event listener
153 * @deprecated use the {@code RunnableWithArgs} variant instead.
154 */
155 @Deprecated
156 <E extends Event> void removeEventListener(@Nonnull Class<E> eventClass, @Nonnull CallableWithArgs<?> listener);
157
158 /**
159 * Publishes an event.<p>
160 * Listeners will be notified in the same thread as the publisher.
161 *
162 * @param eventName the name of the event
163 */
164 void publishEvent(@Nonnull String eventName);
165
166 /**
167 * Publishes an event.<p>
168 * Listeners will be notified in the same thread as the publisher.
169 *
170 * @param eventName the name of the event
171 * @param args event arguments sent to listeners
172 */
173 void publishEvent(@Nonnull String eventName, @Nullable List<?> args);
174
175 /**
176 * Publishes an event.<p>
177 * Listeners will be notified in the same thread as the publisher.
178 *
179 * @param event the event to be published
180 */
181 void publishEvent(@Nonnull Event event);
182
183 /**
184 * Publishes an event.<p>
185 * Listeners will be notified outside of the UI thread.
186 *
187 * @param eventName the name of the event
188 */
189 void publishEventOutsideUI(@Nonnull String eventName);
190
191 /**
192 * Publishes an event.<p>
193 * Listeners will be notified outside of the UI thread.
194 *
195 * @param eventName the name of the event
196 * @param args event arguments sent to listeners
197 */
198 void publishEventOutsideUI(@Nonnull String eventName, @Nullable List<?> args);
199
200 /**
201 * Publishes an event.<p>
202 * Listeners will be notified outside of the UI thread.
203 *
204 * @param event the event to be published
205 */
206 void publishEventOutsideUI(@Nonnull Event event);
207
208 /**
209 * Publishes an event.<p>
210 * Listeners will be notified in a different thread.
211 *
212 * @param eventName the name of the event
213 */
214 void publishEventAsync(@Nonnull String eventName);
215
216 /**
217 * Publishes an event.<p>
218 * Listeners will be notified in a different thread.
219 *
220 * @param eventName the name of the event
221 * @param args event arguments sent to listeners
222 */
223 void publishEventAsync(@Nonnull String eventName, @Nullable List<?> args);
224
225 /**
226 * Publishes an event.<p>
227 * Listeners will be notified in a different thread.
228 *
229 * @param event the event to be published
230 */
231 void publishEventAsync(@Nonnull Event event);
232
233 /**
234 * Returns whether events will be published by the event bus or not.
235 *
236 * @return true if event publishing is enabled; false otherwise.
237 */
238 boolean isEventPublishingEnabled();
239
240 /**
241 * Sets the enabled state for event publishing.</p>
242 * Events will be automatically discarded when the enabled state is set to false.
243 *
244 * @param enabled the value fot the enabled state.
245 */
246 void setEventPublishingEnabled(boolean enabled);
247 }
|