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}