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