EventPublisher.java
001 /*
002  * Copyright 2009-2012 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;
017 
018 import griffon.util.RunnableWithArgs;
019 import groovy.lang.Closure;
020 
021 import java.util.List;
022 
023 /**
024  * Base contract for classes that can publish events using their own
025  * event bus.
026  *
027  @author Andres Almiray
028  @since 0.9.3
029  */
030 public interface EventPublisher {
031     /**
032      * Adds an event listener.<p>
033      * Accepted types are: Script, Map and Object.
034      *
035      @param listener an event listener
036      */
037     void addEventListener(Object listener);
038 
039     /**
040      * Adds a closure as an event listener.<p>
041      *
042      @param eventName the name of the event
043      @param listener  an event listener
044      */
045     void addEventListener(String eventName, Closure listener);
046 
047     /**
048      * Adds a runnable as an event listener.<p>
049      *
050      @param eventName the name of the event
051      @param listener  an event listener
052      */
053     void addEventListener(String eventName, RunnableWithArgs listener);
054 
055     /**
056      * Removes an event listener.<p>
057      * Accepted types are: Script, Map and Object.
058      *
059      @param listener an event listener
060      */
061     void removeEventListener(Object listener);
062 
063     /**
064      * Removes a closure as an event listener.<p>
065      *
066      @param eventName the name of the event
067      @param listener  an event listener
068      */
069     void removeEventListener(String eventName, Closure listener);
070 
071     /**
072      * Removes a runnable as an event listener.<p>
073      *
074      @param eventName the name of the event
075      @param listener  an event listener
076      */
077     void removeEventListener(String eventName, RunnableWithArgs listener);
078 
079     /**
080      * Publishes an event.<p>
081      * Listeners will be notified in the same thread as the publisher.
082      *
083      @param eventName the name of the event
084      */
085     void publishEvent(String eventName);
086 
087     /**
088      * Publishes an event.<p>
089      * Listeners will be notified in the same thread as the publisher.
090      *
091      @param eventName the name of the event
092      @param args      event arguments sent to listeners
093      */
094     void publishEvent(String eventName, List args);
095 
096     /**
097      * Publishes an event.<p>
098      * Listeners will be notified outside of the UI thread.
099      *
100      @param eventName the name of the event
101      @deprecated use #publishEventOutsideUI() instead
102      */
103     @Deprecated
104     void publishEventOutside(String eventName);
105 
106     /**
107      * Publishes an event.<p>
108      * Listeners will be notified outside of the UI thread.
109      *
110      @param eventName the name of the event
111      @param args      event arguments sent to listeners
112      @deprecated use #publishEventOutsideUI() instead
113      */
114     @Deprecated
115     void publishEventOutside(String eventName, List args);
116 
117     /**
118      * Publishes an event.<p>
119      * Listeners will be notified outside of the UI thread.
120      *
121      @param eventName the name of the event
122      */
123     void publishEventOutsideUI(String eventName);
124 
125     /**
126      * Publishes an event.<p>
127      * Listeners will be notified outside of the UI thread.
128      *
129      @param eventName the name of the event
130      @param args      event arguments sent to listeners
131      */
132     void publishEventOutsideUI(String eventName, List args);
133 
134     /**
135      * Publishes an event.<p>
136      * Listeners will be notified in a different thread.
137      *
138      @param eventName the name of the event
139      */
140     void publishEventAsync(String eventName);
141 
142     /**
143      * Publishes an event.<p>
144      * Listeners will be notified in a different thread.
145      *
146      @param eventName the name of the event
147      @param args      event arguments sent to listeners
148      */
149     void publishEventAsync(String eventName, List args);
150 
151     /**
152      * Returns whether events will be published by the event bus or not.
153      *
154      @return true if event publishing is enabled; false otherwise.
155      */
156     boolean isEventPublishingEnabled();
157 
158     /**
159      * Sets the enabled state for event publishing.</p>
160      * Events will be automatically discarded when the enabled state is set to false.
161      *
162      @param enabled the value fot the enabled state.
163      */
164     void setEventPublishingEnabled(boolean enabled);
165 }