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.service.registry; 023 024import de.novanic.eventservice.service.connection.strategy.connector.ConnectionStrategyServerConnector; 025import de.novanic.eventservice.client.event.filter.EventFilter; 026import de.novanic.eventservice.client.event.DomainEvent; 027import de.novanic.eventservice.client.event.domain.Domain; 028import de.novanic.eventservice.client.event.Event; 029import de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent; 030import de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener; 031import de.novanic.eventservice.config.EventServiceConfiguration; 032 033import java.util.List; 034import java.util.Set; 035 036/** 037 * The EventRegistry handles the users/clients and the events per domain. Users can be registered for a domain/context 038 * to receive events for the corresponding domain. 039 * User specific events can be handled domain-less, when the user is registered. 040 * The EventRegistry is used by {@link de.novanic.eventservice.service.EventServiceImpl}. 041 * 042 * <br>The client id is required, because the connection to every client must be kept open. 043 * 044 * @see de.novanic.eventservice.service.EventServiceImpl 045 * 046 * @author sstrohschein 047 * <br>Date: 09.08.2008 048 * <br>Time: 22:28:24 049 */ 050public interface EventRegistry 051{ 052 /** 053 * Checks if the user is registered for any domain. 054 * @param aUserId the user to check 055 * @return true if registered, false if not registered 056 */ 057 boolean isUserRegistered(String aUserId); 058 059 /** 060 * Checks if the user is registered for the corresponding domain. 061 * @param aDomain the domain to check 062 * @param aUserId the user to check 063 * @return true if registered, false if not registered 064 */ 065 boolean isUserRegistered(Domain aDomain, String aUserId); 066 067 /** 068 * Registers a user for listening for the corresponding domain. From now all events for the domain are recognized and 069 * will be returned when listen ({@link EventRegistry#listen(de.novanic.eventservice.service.connection.strategy.connector.ConnectionStrategyServerConnector , String)}) is called. The {@link de.novanic.eventservice.client.event.filter.EventFilter} 070 * is optional and can be NULL. 071 * @param aDomain the domain to listen 072 * @param aUserId the user to register 073 * @param anEventFilter EventFilter to filter the domain events (optional, can be NULL) 074 */ 075 void registerUser(Domain aDomain, String aUserId, EventFilter anEventFilter); 076 077 /** 078 * The EventFilter for a user domain combination can be set or changed with that method. 079 * @param aDomain domain 080 * @param aUserId user 081 * @param anEventFilter new EventFilter 082 */ 083 void setEventFilter(Domain aDomain, String aUserId, EventFilter anEventFilter); 084 085 /** 086 * Returns the EventFilter for the user domain combination. 087 * @param aDomain domain 088 * @param aUserId user 089 * @return EventFilter for the user domain combination 090 */ 091 EventFilter getEventFilter(Domain aDomain, String aUserId); 092 093 /** 094 * EventFilters can be removed for a user domain combination with that method. 095 * @param aUserId user 096 * @param aDomain domain 097 */ 098 void removeEventFilter(Domain aDomain, String aUserId); 099 100 /** 101 * The listen method returns all events for the user (events for all domains where the user is registered and user 102 * specific events). If no events are available, the method waits a defined time before the events are returned. 103 * The listen method is designed for the EventService functionality. The client side calls the method with a defined 104 * interval to receive all events. If the client don't call the method in the interval, the user will be removed 105 * from the EventRegistry. The timeout time and the min and max waiting time can be configured by 106 * {@link de.novanic.eventservice.config.EventServiceConfiguration}. 107 * @param aServerEventListener {@link de.novanic.eventservice.service.connection.strategy.connector.ConnectionStrategyServerConnector} for the listening method 108 * @param aUserId user 109 * @return list of events 110 */ 111 List<DomainEvent> listen(ConnectionStrategyServerConnector aServerEventListener, String aUserId); 112 113 /** 114 * This method causes a stop of listening for a domain ({@link EventRegistry#listen(de.novanic.eventservice.service.connection.strategy.connector.ConnectionStrategyServerConnector , String)}). 115 * @param aDomain domain to stop listening 116 * @param aUserId user 117 */ 118 void unlisten(Domain aDomain, String aUserId); 119 120 /** 121 * This method causes a stop of listening for all domains ({@link EventRegistry#listen(de.novanic.eventservice.service.connection.strategy.connector.ConnectionStrategyServerConnector , String)}). 122 * @param aUserId user 123 */ 124 void unlisten(String aUserId); 125 126 /** 127 * Returns all domains where the user is registered to. 128 * @param aUserId user 129 * @return domains where the user is registered to 130 */ 131 Set<Domain> getListenDomains(String aUserId); 132 133 /** 134 * Returns all registered/activated domains. 135 * @return all registered/activated domains 136 */ 137 Set<Domain> getListenDomains(); 138 139 /** 140 * Returns all registered users/clients. 141 * To get only the registered users/client of a specific {@link de.novanic.eventservice.client.event.domain.Domain}, 142 * the method {@link de.novanic.eventservice.service.registry.EventRegistry#getRegisteredUserIds(de.novanic.eventservice.client.event.domain.Domain)} 143 * can be used instead. 144 * @return registered users/clients 145 */ 146 Set<String> getRegisteredUserIds(); 147 148 /** 149 * Returns all registered users/client of a specific {@link de.novanic.eventservice.client.event.domain.Domain}. 150 * To get all the registered users/client (of all domains), the method {@link EventRegistry#getRegisteredUserIds()} 151 * can be used instead. 152 * @param aDomain domain 153 * @return registered users/client of the specific domain 154 */ 155 Set<String> getRegisteredUserIds(Domain aDomain); 156 157 /** 158 * Adds an event to a domain. 159 * @param aDomain domain for the event 160 * @param anEvent event to add 161 */ 162 void addEvent(Domain aDomain, Event anEvent); 163 164 /** 165 * Adds an event directly to a user. The user must be registered to any domain. 166 * @param aUserId user 167 * @param anEvent event 168 */ 169 void addEventUserSpecific(String aUserId, Event anEvent); 170 171 /** 172 * Registers an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} which is triggered on a 173 * timeout or when a user/client leaves a {@link de.novanic.eventservice.client.event.domain.Domain}. An 174 * {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} is hold at the server side and can 175 * contain custom data. Other users/clients can use the custom data when the event is for example triggered by a timeout. 176 * @param aUserId user to register the {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} to 177 * @param anUnlistenScope scope of the unlisten events to receive 178 * @param anUnlistenEvent {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} which should 179 * be transferred to other users/clients when a timeout occurs or a domain is leaved. 180 */ 181 void registerUnlistenEvent(String aUserId, UnlistenEventListener.Scope anUnlistenScope, UnlistenEvent anUnlistenEvent); 182 183 /** 184 * Returns the initialized {@link de.novanic.eventservice.config.EventServiceConfiguration} 185 * @return configuration {@link de.novanic.eventservice.config.EventServiceConfiguration} 186 */ 187 EventServiceConfiguration getConfiguration(); 188}