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