EventPublisher.java
001 /*
002  * Copyright 2008-2014 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><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><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 }