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.service;
023
024import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;
025import de.novanic.eventservice.client.config.EventServiceConfigurationTransferable;
026import de.novanic.eventservice.client.event.filter.EventFilter;
027import de.novanic.eventservice.client.event.Event;
028import de.novanic.eventservice.client.event.DomainEvent;
029import de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent;
030import de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener;
031import de.novanic.eventservice.client.event.domain.Domain;
032
033import java.util.List;
034import java.util.Set;
035
036import com.google.gwt.user.client.rpc.RemoteService;
037
038/**
039 * EventService is the server side interface to register listen requests for domains and to add events.
040 *
041 * @author sstrohschein
042 * <br>Date: 05.06.2008
043 * <br>Time: 19:07:07
044 */
045@RemoteServiceRelativePath("gwteventservice")
046public interface EventService extends RemoteService
047{
048    /**
049     * Initializes the {@link de.novanic.eventservice.client.event.service.EventService}.
050     * @return EventServiceConfigurationTransferable a transferable configuration for the client side
051     */
052    EventServiceConfigurationTransferable initEventService();
053
054    /**
055     * Register listen for a domain.
056     * @param aDomain domain to listen to
057     */
058    void register(Domain aDomain);
059
060    /**
061     * Register listen for a domain.
062     * @param aDomain domain to listen to
063     * @param anEventFilter EventFilter to filter events
064     */
065    void register(Domain aDomain, EventFilter anEventFilter);
066
067    /**
068     * Register listen for a domain.
069     * @param aDomains domains to listen to
070     */
071    void register(Set<Domain> aDomains);
072
073    /**
074     * Register listen for domains.
075     * @param aDomains domains to listen to
076     * @param anEventFilter EventFilter to filter events (applied to all domains)
077     */
078    void register(Set<Domain> aDomains, EventFilter anEventFilter);
079
080    /**
081     * Registers an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} which is triggered on a
082     * timeout or when a user/client leaves a {@link de.novanic.eventservice.client.event.domain.Domain}. An
083     * {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} is hold at the server side and can
084     * contain custom data. Other users/clients can use the custom data when the event is for example triggered by a timeout.
085     * @param anUnlistenScope scope of the unlisten events to receive
086     * @param anUnlistenEvent {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} which should
087     * be transferred to other users/clients when a timeout occurs or a domain is leaved.
088     */
089    void registerUnlistenEvent(UnlistenEventListener.Scope anUnlistenScope, UnlistenEvent anUnlistenEvent);
090
091    /**
092     * Registers an {@link EventFilter} for the domain.
093     * @param aDomain domain to register the EventFilter to
094     * @param anEventFilter EventFilter to filter events for the domain
095     */
096    void registerEventFilter(Domain aDomain, EventFilter anEventFilter);
097
098    /**
099     * Deregisters the {@link EventFilter} of the domain.
100     * @param aDomain domain to drop the EventFilters from
101     */
102    void deregisterEventFilter(Domain aDomain);
103
104    /**
105     * Returns the EventFilter for the user domain combination.
106     * @param aDomain domain
107     * @return EventFilter for the domain
108     */
109    EventFilter getEventFilter(Domain aDomain);
110
111    /**
112     * The listen method returns all events for the user (events for all domains where the user is registered and user
113     * specific events). If no events are available, the method waits a defined time before the events are returned.
114     * The client side calls the method with a defined interval to receive all events. If the client doesn't call the
115     * method in that interval, the user will be removed from the EventRegistry. The timeout time and the waiting time
116     * can be configured with EventServiceConfiguration/-Factory (server side) and initialized with the init method of
117     * EventRegistryFactory (server side).
118     * The default listening method is long-polling, but that can be changed with changing the connection strategy.
119     * See the configuration parameter description to configure another connection strategy.
120     * @return list of events
121     */
122    List<DomainEvent> listen();
123
124    /**
125     * Unlisten for events (for the current user) in all domains (deregisters the user from all domains).
126     */
127    void unlisten();
128
129    /**
130     * Unlisten for events
131     * @param aDomain the domain to unlisten
132     */
133    void unlisten(Domain aDomain);
134
135    /**
136     * Unlisten for events (for the current user) in the domains and deregisters the user from the domains.
137     * @param aDomains set of domains to unlisten
138     */
139    void unlisten(Set<Domain> aDomains);
140
141    /**
142     * Checks if the user is registered for event listening.
143     * @param aDomain domain to check
144     * @return true when the user is registered for listening, otherwise false
145     */
146    boolean isUserRegistered(Domain aDomain);
147
148    /**
149     * Adds an event for all users in the domain.
150     * @param aDomain domain to add the event
151     * @param anEvent event to add
152     */
153    void addEvent(Domain aDomain, Event anEvent);
154
155    /**
156     * Adds an event only for the current user.
157     * @param anEvent event to add to the user
158     */
159    void addEventUserSpecific(Event anEvent);
160
161    /**
162     * Returns the domain names, where the user is listening to
163     * @return collection of domain names
164     */
165    Set<Domain> getActiveListenDomains();
166}