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.listener.unlisten;
023
024import de.novanic.eventservice.client.event.listener.RemoteEventListener;
025
026import java.io.Serializable;
027
028/**
029 * The UnlistenEventListener can be implemented to listen for {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent}
030 * instances. An {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} is for example triggered on a timeout
031 * or when a user/client leaves a domain. The {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListenerAdapter}
032 * provides the apply method ({@link de.novanic.eventservice.client.event.listener.RemoteEventListener#apply(de.novanic.eventservice.client.event.Event)})
033 * and a default implementation of {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener}.
034 *
035 * @author sstrohschein
036 *         <br>Date: 08.06.2009
037 *         <br>Time: 22:36:20
038 */
039public interface UnlistenEventListener extends RemoteEventListener
040{
041    /**
042     * Scopes for listening to {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} instances.
043     * See the various scopes ({@link Scope#LOCAL},
044     * {@link Scope#TIMEOUT} and
045     * {@link Scope#UNLISTEN}) for the according description.
046     */
047    enum Scope implements Serializable {
048        /**
049         * An {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} registered with the local scope
050         * does only recognize local unlisten events for example caused by local timeouts or a lost connection to the server side.
051         * Therefore it isn't necessary to register it to the server side, but unlisten events of other users / clients
052         * can't be get with the local scope.
053         */
054        LOCAL,
055        /**
056         * An {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} registered with the timeout scope
057         * does recognize local unlisten events (for example caused by local timeouts or a lost connection to the server side) and
058         * unlisten events of other users / clients caused by a connection timeout of the specified user / client.
059         */
060        TIMEOUT,
061        /**
062         * An {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEventListener} registered with the unlisten scope
063         * does recognize all unlisten events: Local unlisten events (for example caused by local timeouts or a lost connection to the server side),
064         * unlisten events of other users / clients caused by a timeout and domain unlisten events of other users / clients for
065         * example caused by removing a listener for a domain.
066         */
067        UNLISTEN
068    }
069
070    /**
071     * The method onUnlisten is called when an {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent} occurs.
072     * @param anUnlistenEvent triggered {@link de.novanic.eventservice.client.event.listener.unlisten.UnlistenEvent}
073     */
074    void onUnlisten(UnlistenEvent anUnlistenEvent);
075}