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.connection.strategy.connector;
023
024import de.novanic.eventservice.client.config.EventServiceConfigurationTransferable;
025import de.novanic.eventservice.client.event.Event;
026import de.novanic.eventservice.client.event.domain.Domain;
027import de.novanic.eventservice.client.event.filter.EventFilter;
028import de.novanic.eventservice.client.event.listener.EventNotification;
029import de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent;
030import de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener;
031import com.google.gwt.user.client.rpc.AsyncCallback;
032
033import java.util.Set;
034
035/**
036 * The RemoteEventConnector should handle the connection between the client and the server side.
037 *
038 * @author sstrohschein
039 *         <br>Date: 12.10.2008
040 *         <br>Time: 11:16:14
041 */
042public interface RemoteEventConnector
043{
044    /**
045     * That method is called to execute the first server call (for initialization).
046     * @param aCallback callback
047     */
048    void init(AsyncCallback<EventServiceConfigurationTransferable> aCallback);
049
050    /**
051     * Initializes the listen method implementation with a {@link de.novanic.eventservice.client.connection.strategy.connector.ConnectionStrategyClientConnector} from the configuration.
052     * That is required to specify the listen / connection strategy.
053     * @param aConfiguration configuration
054     */
055    ConnectionStrategyClientConnector initListen(EventServiceConfigurationTransferable aConfiguration);
056
057    /**
058     * Activates the connector for the domain. An {@link de.novanic.eventservice.client.event.filter.EventFilter}
059     * to filter events on the server side is optional.
060     * @param aDomain domain to activate
061     * @param anEventFilter EventFilter to filter the events on the server side (optional)
062     * @param anEventNotification supports the notification about incoming events
063     * @param aCallback callback
064     */
065    void activate(Domain aDomain, EventFilter anEventFilter, EventNotification anEventNotification, AsyncCallback<Void> aCallback);
066
067    /**
068     * Deactivates the connector for all domains (no events can be got from the domains).
069     */
070    void deactivate();
071
072    /**
073     * Deactivates the connector for the domains (no events can be got from the domains).
074     * @param aDomains domains to deactivate
075     * @param aCallback callback
076     */
077    void deactivate(Set<Domain> aDomains, AsyncCallback<Void> aCallback);
078
079    /**
080     * Deactivates the connector for the domain (no events can be got from the domain).
081     * @param aDomain domain to deactivate
082     * @param aCallback callback
083     */
084    void deactivate(Domain aDomain, AsyncCallback<Void> aCallback);
085
086    /**
087     * Checks if the connector is active (listening).
088     * @return true when active/listening, otherwise false
089     */
090    boolean isActive();
091
092    /**
093     * Sends an event to a domain. The event will be received from all clients which are registered to that domain.
094     * User-specific events can be sent with the usage of this domain: {@link de.novanic.eventservice.client.event.domain.DomainFactory#USER_SPECIFIC_DOMAIN}.
095     * @param aDomain domain
096     * @param anEvent event
097     * @param aCallback callback
098     */
099    void sendEvent(Domain aDomain, Event anEvent, AsyncCallback<Void> aCallback);
100
101    /**
102     * Registers an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} to the server side which
103     * will be triggered  when a timeout or unlisten/deactivation for a domain occurs.
104     * @param anUnlistenScope scope of the unlisten events to receive
105     * @param anUnlistenEvent {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} which can contain custom data
106     * @param aCallback callback
107     */
108    void registerUnlistenEvent(UnlistenEventListener.Scope anUnlistenScope, UnlistenEvent anUnlistenEvent, AsyncCallback<Void> aCallback);
109
110    /**
111     * Registers an {@link de.novanic.eventservice.client.event.filter.EventFilter} for a domain. That can be used when
112     * the domain is already activated and an {@link de.novanic.eventservice.client.event.filter.EventFilter} is
113     * needed later or isn't available when the domain becomes active.
114     * @param aDomain domain
115     * @param anEventFilter EventFilter to filter the events on the server side (optional)
116     * @param aCallback callback
117     */
118    void registerEventFilter(Domain aDomain, EventFilter anEventFilter, AsyncCallback<Void> aCallback);
119
120    /**
121     * Deregisters the {@link de.novanic.eventservice.client.event.filter.EventFilter} for a domain.
122     * @param aDomain domain to remove the EventFilter from
123     * @param aCallback callback
124     */
125    void deregisterEventFilter(Domain aDomain, AsyncCallback<Void> aCallback);
126}