001/*
002 * GWTEventService
003 * Copyright (c) 2011 and beyond, strawbill UG (haftungsbeschr?nkt)
004 *
005 * This is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU Lesser General Public License as
007 * published by the Free Software Foundation; either version 3 of
008 * the License, or (at your option) any later version.
009 * Other licensing for GWTEventService may also be possible on request.
010 * Please view the license.txt of the project for more information.
011 *
012 * This software is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this software; if not, write to the Free
019 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021 */
022package de.novanic.eventservice.client.event;
023
024import de.novanic.eventservice.client.event.listener.RemoteEventListener;
025import de.novanic.eventservice.client.event.filter.EventFilter;
026import de.novanic.eventservice.client.event.domain.Domain;
027import de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener;
028import de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent;
029
030import java.util.List;
031import java.util.Set;
032
033import com.google.gwt.user.client.rpc.AsyncCallback;
034
035/**
036 * The RemoteEventService supports listening to the server via RemoteEventListeners ({@link de.novanic.eventservice.client.event.listener.RemoteEventListener}).
037 * It keeps a connection to the server. When an event occurred at the server, the RemoteEventService informs the RemoteEventListeners
038 * about the event and starts listening at the server again. When no RemoteEventListeners registered anymore, the
039 * RemoteEventService stops listening till new RemoteEventListeners are registered.
040 * The listening works with a domain/context scope. See the documentation/manual to get more information about the
041 * listening concept.
042 *
043 * @author sstrohschein
044 * <br>Date: 09.08.2008
045 * <br>Time: 22:22:14
046 */
047public interface RemoteEventService
048{
049    /**
050     * Adds a listener for a domain.
051     * It activates the RemoteEventService if it was inactive.
052     * @param aDomain domain
053     * @param aRemoteListener new listener
054     */
055    void addListener(Domain aDomain, RemoteEventListener aRemoteListener);
056
057    /**
058     * Adds a listener for a domain.
059     * It activates the RemoteEventService if it was inactive.
060     * @param aDomain domain
061     * @param aRemoteListener new listener
062     * @param aCallback callback (only called when no listener is registered for the domain)
063     */
064    void addListener(Domain aDomain, RemoteEventListener aRemoteListener, AsyncCallback<Void> aCallback);
065
066    /**
067     * Adds a listener for a domain. The EventFilter is applied to the domain to filter events before the
068     * RemoteEventListener recognizes the event.
069     * It activates the RemoteEventService if it was inactive.
070     * @param aDomain domain
071     * @param aRemoteListener new listener
072     * @param anEventFilter EventFilter to filter the events before RemoteEventListener
073     */
074    void addListener(Domain aDomain, RemoteEventListener aRemoteListener, EventFilter anEventFilter);
075
076    /**
077     * Adds a listener for a domain. The EventFilter is applied to the domain to filter events before the
078     * RemoteEventListener recognizes the event.
079     * It activates the RemoteEventService if it was inactive.
080     * @param aDomain domain
081     * @param aRemoteListener new listener
082     * @param anEventFilter EventFilter to filter the events before RemoteEventListener
083     * @param aCallback callback (only called when no listener is registered for the domain)
084     */
085    void addListener(Domain aDomain, RemoteEventListener aRemoteListener, EventFilter anEventFilter, AsyncCallback<Void> aCallback);
086
087    /**
088     * Registers an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} to listen for all
089     * user/client domain deregistrations and timeouts. The scope for unlisten events to receive is set to
090     * {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener.Scope#UNLISTEN} by default.
091     * To use other scopes see
092     * {@link de.novanic.eventservice.client.event.RemoteEventService#addUnlistenListener(de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener.Scope, de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener, com.google.gwt.user.client.rpc.AsyncCallback)}.
093     * @param anUnlistenEventListener {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener}
094     * to listen for all user/client domain deregistrations and timeouts.
095     * @param aCallback callback
096     */
097    void addUnlistenListener(UnlistenEventListener anUnlistenEventListener, AsyncCallback<Void> aCallback);
098
099    /**
100     * Registers an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} to listen for all
101     * user/client domain deregistrations and timeouts.
102     * @param anUnlistenEventListener {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener}
103     * to listen for all user/client domain deregistrations and timeouts.
104     * @param anUnlistenScope scope of the unlisten events to receive
105     * @param aCallback callback
106     */
107    void addUnlistenListener(UnlistenEventListener.Scope anUnlistenScope, UnlistenEventListener anUnlistenEventListener, AsyncCallback<Void> aCallback);
108
109    /**
110     * Registers an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} to listen for all
111     * user/client domain deregistrations and timeouts. The custom {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent}
112     * will be registered at the server side and transferred to all users/clients which have an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener}
113     * registered. That {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} can for example contain user information
114     * of your specific user-system to recover the user in your user-system on a timeout. The scope for unlisten events to receive is set to
115     * {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener.Scope#UNLISTEN} by default.
116     * To use other scopes see
117     * {@link de.novanic.eventservice.client.event.RemoteEventService#addUnlistenListener(de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener.Scope, de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener, de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent, com.google.gwt.user.client.rpc.AsyncCallback)}.
118     * @param anUnlistenEventListener {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener}
119     * to listen for all user/client domain deregistrations and timeouts.
120     * @param anUnlistenEvent {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} which can contain custom data
121     * @param aCallback callback
122     */
123    void addUnlistenListener(UnlistenEventListener anUnlistenEventListener, UnlistenEvent anUnlistenEvent, AsyncCallback<Void> aCallback);
124
125    /**
126     * Registers an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} to listen for all
127     * user/client domain deregistrations and timeouts. The custom {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent}
128     * will be registered at the server side and transferred to all users/clients which have an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener}
129     * registered. That {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} can for example contain user information
130     * of your specific user-system to recover the user in your user-system on a timeout.
131     * @param anUnlistenScope scope of the unlisten events to receive
132     * @param anUnlistenEventListener {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener}
133     * to listen for all user/client domain deregistrations and timeouts.
134     * @param anUnlistenEvent {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} which can contain custom data
135     * @param aCallback callback
136     */
137    void addUnlistenListener(UnlistenEventListener.Scope anUnlistenScope, UnlistenEventListener anUnlistenEventListener, UnlistenEvent anUnlistenEvent, AsyncCallback<Void> aCallback);
138
139    /**
140     * Removes a listener for a domain.
141     * The RemoteEventService will get inactive, when no other listeners are registered.
142     * @param aDomain domain
143     * @param aRemoteListener listener to remove
144     */
145    void removeListener(Domain aDomain, RemoteEventListener aRemoteListener);
146
147    /**
148     * Removes a listener for a domain.
149     * The RemoteEventService will get inactive, when no other listeners are registered.
150     * @param aDomain domain
151     * @param aRemoteListener listener to remove
152     * @param aCallback callback
153     */
154    void removeListener(Domain aDomain, RemoteEventListener aRemoteListener, AsyncCallback<Void> aCallback);
155
156    /**
157     * Registers an EventFilter for a domain. This can be used when a listener is already added and an EventFilter
158     * needed later or isn't available when the listener is added.
159     * @param aDomain domain
160     * @param anEventFilter EventFilter to filter the events before RemoteEventListener
161     */
162    void registerEventFilter(Domain aDomain, EventFilter anEventFilter);
163
164    /**
165     * Registers an EventFilter for a domain. This can be used when a listener is already added and an EventFilter
166     * needed later or isn't available when the listener is added.
167     * @param aDomain domain
168     * @param anEventFilter EventFilter to filter the events before RemoteEventListener
169     * @param aCallback callback
170     */
171    void registerEventFilter(Domain aDomain, EventFilter anEventFilter, AsyncCallback<Void> aCallback);
172
173    /**
174     * Deregisters the EventFilter for a domain.
175     * @param aDomain domain to remove the EventFilter from
176     */
177    void deregisterEventFilter(Domain aDomain);
178
179    /**
180     * Deregisters the EventFilter for a domain.
181     * @param aDomain domain to remove the EventFilter from
182     * @param aCallback callback
183     */
184    void deregisterEventFilter(Domain aDomain, AsyncCallback<Void> aCallback);
185
186    /**
187     * Checks if the RemoteEventService is active (listening).
188     * @return true when active/listening, otherwise false
189     */
190    boolean isActive();
191
192    /**
193     * Returns all active domains (all domains where the client has listeners registered).
194     * @return all active domains
195     */
196    Set<Domain> getActiveDomains();
197
198    /**
199     * Returns all registered listeners of a domain.
200     * @param aDomain domain
201     * @return all registered listeners of the domain
202     */
203    List<RemoteEventListener> getRegisteredListeners(Domain aDomain);
204
205    /**
206     * Removes all RemoteEventListeners and deactivates the RemoteEventService (stop listening).
207     */
208    void removeListeners();
209
210    /**
211     * Removes all RemoteEventListeners and deactivates the RemoteEventService (stop listening).
212     * @param aCallback callback (only called when a listener is registered for the domain)
213     */
214    void removeListeners(AsyncCallback<Void> aCallback);
215
216    /**
217     * Calls unlisten for a set of domains (stop listening for these domains). The RemoteEventListeners for these
218     * domains will also be removed.
219     * {@link RemoteEventService#removeListeners()} can be used to call unlisten for all domains.
220     * @param aDomains domains to unlisten
221     */
222    void removeListeners(Set<Domain> aDomains);
223
224    /**
225     * Calls unlisten for a set of domains (stop listening for these domains). The RemoteEventListeners for these
226     * domains will also be removed.
227     * {@link DefaultRemoteEventService#removeListeners()} can be used to call unlisten for all domains.
228     * @param aDomains domains to unlisten
229     * @param aCallback callback (only called when a listener is registered for the domain)
230     */
231    void removeListeners(Set<Domain> aDomains, AsyncCallback<Void> aCallback);
232
233    /**
234     * Stops listening for the corresponding domain. The RemoteEventFilters for the domain will also be removed.
235     * {@link RemoteEventService#removeListeners()} can be used to call unlisten for all domains.
236     * @param aDomain domain to unlisten
237     */
238    void removeListeners(Domain aDomain);
239
240    /**
241     * Stops listening for the corresponding domain. The RemoteEventFilters for the domain will also be removed.
242     * {@link DefaultRemoteEventService#removeListeners()} can be used to call unlisten for all domains.
243     * @param aDomain domain to unlisten
244     * @param aCallback callback (only called when a listener is registered for the domain)
245     */
246    void removeListeners(Domain aDomain, AsyncCallback<Void> aCallback);
247
248    /**
249     * Removes an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener}.
250     * The RemoteEventService will get inactive, when no other listeners are registered.
251     * @param anUnlistenEventListener {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} to remove
252     * @param aCallback callback
253     */
254    void removeUnlistenListener(UnlistenEventListener anUnlistenEventListener, AsyncCallback<Void> aCallback);
255
256    /**
257     * Stops listening for {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} instances.
258     * @param aCallback callback (only called when an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} is registered)
259     */
260    void removeUnlistenListeners(AsyncCallback<Void> aCallback);
261
262    /**
263     * Adds / sends an event to a domain. The event will be received from all clients which are registered to that domain.
264     * User-specific events can be added with the usage of this domain: {@link de.novanic.eventservice.client.event.domain.DomainFactory#USER_SPECIFIC_DOMAIN}.
265     * @param aDomain domain
266     * @param anEvent event
267     */
268    void addEvent(Domain aDomain, Event anEvent);
269
270    /**
271     * Adds / sends an event to a domain. The event will be received from all clients which are registered to that domain.
272     * User-specific events can be added with the usage of this domain: {@link de.novanic.eventservice.client.event.domain.DomainFactory#USER_SPECIFIC_DOMAIN}.
273     * @param aDomain domain
274     * @param anEvent event
275     * @param aCallback callback
276     */
277    void addEvent(Domain aDomain, Event anEvent, AsyncCallback<Void> aCallback);
278}