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}