001 /*
002 * Copyright 2009-2013 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
017 package griffon.core;
018
019 import griffon.util.RunnableWithArgs;
020 import groovy.lang.Closure;
021
022 import java.util.List;
023 import java.util.Map;
024
025 /**
026 * An event handling helper.<p>
027 * Listeners may be of type<ul>
028 * <li>a <tt>Script</tt></li>
029 * <li>a <tt>Map</tt></li>
030 * <li>a <tt>Closure</tt></li>
031 * <li>a <tt>RunnableWithArgs</tt></li>
032 * <li>a <tt>Object</tt> (a Java bean)</li>
033 * </ul>
034 * <p/>
035 * With the exception of Maps and Closures, the naming convention for an eventHandler is
036 * "on" + eventName, Maps and Closures require handlers to be named as eventName only.<p>
037 * Some examples of eventHandler names are: onStartupStart, onMyCoolEvent.
038 * Event names must follow the camelCase naming convention.<p>
039 *
040 * @author Andres Almiray
041 */
042 public interface EventRouter {
043 /**
044 * Returns the current enabled state.
045 *
046 * @return true if the router is enabled; false otherwise.
047 */
048 boolean isEnabled();
049
050 /**
051 * Sets the enabled state of this router.</p>
052 * A disabled router will simply discard all events that are sent to it, in other
053 * words listeners will never be notified. Discarded events cannot be recovered, even
054 * if the router is enabled at a later point in time.
055 *
056 * @param enabled the value for the enabled state
057 */
058 void setEnabled(boolean enabled);
059
060 /**
061 * Publishes an event with optional arguments.</p>
062 * Event listeners will be notified in the same thread
063 * that originated the event.
064 *
065 * @param eventName the name of the event
066 */
067 void publish(String eventName);
068
069 /**
070 * Publishes an event with optional arguments.</p>
071 * Event listeners will be notified in the same thread
072 * that originated the event.
073 *
074 * @param eventName the name of the event
075 * @param params the event's arguments
076 */
077 void publish(String eventName, List params);
078
079 /**
080 * Publishes an event with optional arguments.</p>
081 * Event listeners are guaranteed to be notified
082 * outside of the UI thread always.
083 *
084 * @param eventName the name of the event
085 */
086 void publishOutsideUI(String eventName);
087
088 /**
089 * Publishes an event with optional arguments.</p>
090 * Event listeners are guaranteed to be notified
091 * outside of the UI thread always.
092 *
093 * @param eventName the name of the event
094 * @param params the event's arguments
095 */
096 void publishOutsideUI(String eventName, List params);
097
098 /**
099 * Publishes an event with optional arguments.</p>
100 * Event listeners are guaranteed to be notified
101 * in a different thread than the publisher's, always.
102 *
103 * @param eventName the name of the event
104 */
105 void publishAsync(String eventName);
106
107 /**
108 * Publishes an event with optional arguments.</p>
109 * Event listeners are guaranteed to be notified
110 * in a different thread than the publisher's, always.
111 *
112 * @param eventName the name of the event
113 * @param params the event's arguments
114 */
115 void publishAsync(String eventName, List params);
116
117 /**
118 * Adds an event listener.<p>
119 * <p/>
120 * A listener may be a<ul>
121 * <li>a <tt>Script</tt></li>
122 * <li>a <tt>Map</tt></li>
123 * <li>a <tt>Object</tt> (a Java bean)</li>
124 * </ul>
125 * <p/>
126 * With the exception of Maps, the naming convention for an eventHandler is
127 * "on" + eventName, Maps require handlers to be named as eventName only.<p>
128 * Some examples of eventHandler names are: onStartupStart, onMyCoolEvent.
129 * Event names must follow the camelCase naming convention.<p>
130 *
131 * @param listener an event listener of type Script, Map or Object
132 */
133 void addEventListener(Object listener);
134
135 /**
136 * Adds a Map containing event listeners.<p>
137 * <p/>
138 * An event listener may be a<ul>
139 * <li>a <tt>Closure</tt></li>
140 * <li>a <tt>RunnableWithArgs</tt></li>
141 * </ul>
142 * <p/>
143 * Maps require handlers to be named as eventName only.<p>
144 * Some examples of eventHandler names are: StartupStart, MyCoolEvent.
145 * Event names must follow the camelCase naming convention.<p>
146 *
147 * @param listener an event listener of type Script, Map or Object
148 */
149 void addEventListener(Map<String, Object> listener);
150
151 /**
152 * Removes an event listener.<p>
153 * <p/>
154 * A listener may be a<ul>
155 * <li>a <tt>Script</tt></li>
156 * <li>a <tt>Map</tt></li>
157 * <li>a <tt>Object</tt> (a Java bean)</li>
158 * </ul>
159 * <p/>
160 * With the exception of Maps, the naming convention for an eventHandler is
161 * "on" + eventName, Maps require handlers to be named as eventName only.<p>
162 * Some examples of eventHandler names are: onStartupStart, onMyCoolEvent.
163 * Event names must follow the camelCase naming convention.<p>
164 *
165 * @param listener an event listener of type Script, Map or Object
166 */
167 void removeEventListener(Object listener);
168
169 /**
170 * Removes a Map containing event listeners.<p>
171 * <p/>
172 * An event listener may be a<ul>
173 * <li>a <tt>Closure</tt></li>
174 * <li>a <tt>RunnableWithArgs</tt></li>
175 * </ul>
176 * <p/>
177 * Maps require handlers to be named as eventName only.<p>
178 * Some examples of eventHandler names are: StartupStart, MyCoolEvent.
179 * Event names must follow the camelCase naming convention.<p>
180 *
181 * @param listener an event listener of type Script, Map or Object
182 */
183 void removeEventListener(Map<String, Object> listener);
184
185 /**
186 * Adds a Closure as an event listener.<p>
187 * Event names must follow the camelCase naming convention.
188 *
189 * @param eventName the name of the event
190 * @param listener the event listener
191 */
192 void addEventListener(String eventName, Closure listener);
193
194 /**
195 * Adds a Runnable as an event listener.<p>
196 * Event names must follow the camelCase naming convention.
197 *
198 * @param eventName the name of the event
199 * @param listener the event listener
200 */
201 void addEventListener(String eventName, RunnableWithArgs listener);
202
203 /**
204 * Removes a Closure as an event listener.<p>
205 * Event names must follow the camelCase naming convention.
206 *
207 * @param eventName the name of the event
208 * @param listener the event listener
209 */
210 void removeEventListener(String eventName, Closure listener);
211
212 /**
213 * Removes a Runnable as an event listener.<p>
214 * Event names must follow the camelCase naming convention.
215 *
216 * @param eventName the name of the event
217 * @param listener the event listener
218 */
219 void removeEventListener(String eventName, RunnableWithArgs listener);
220 }
|