EventRouter.java
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><tt>Script</tt></li>
029  <li><tt>Map</tt></li>
030  <li><tt>Closure</tt></li>
031  <li><tt>RunnableWithArgs</tt></li>
032  <li><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><tt>Script</tt></li>
122      <li><tt>Map</tt></li>
123      <li><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><tt>Closure</tt></li>
140      <li><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><tt>Script</tt></li>
156      <li><tt>Map</tt></li>
157      <li><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><tt>Closure</tt></li>
174      <li><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 }