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}