/protocols/smpp/src/main/java/org/mobicents/protocols/smpp/event/EventDispatcher.java

  1/*
  2 * JBoss, Home of Professional Open Source
  3 * Copyright 2011, Red Hat, Inc. and individual contributors
  4 * by the @authors tag. See the copyright.txt in the distribution for a
  5 * full listing of individual contributors.
  6 *
  7 * This is free software; you can redistribute it and/or modify it
  8 * under the terms of the GNU Lesser General Public License as
  9 * published by the Free Software Foundation; either version 2.1 of
 10 * the License, or (at your option) any later version.
 11 *
 12 * This software is distributed in the hope that it will be useful,
 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 15 * Lesser General Public License for more details.
 16 *
 17 * You should have received a copy of the GNU Lesser General Public
 18 * License along with this software; if not, write to the Free
 19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 21 */
 22
 23package org.mobicents.protocols.smpp.event;
 24
 25import java.util.Collection;
 26import java.util.Iterator;
 27
 28import org.mobicents.protocols.smpp.Session;
 29import org.mobicents.protocols.smpp.message.SMPPPacket;
 30
 31/**
 32 * This interface defines the observable side of the observer pattern for
 33 * asynchronous SMPP event notification. Each {@link com.adenki.smpp.Session}
 34 * object will have an implementation of the <code>EventDispatcher</code>
 35 * interface which it uses to deliver events to interested listeners. By
 36 * removing the actual dispatching of events from the internals of the
 37 * Connection, applications may provide their own event dispatch implementations
 38 * for their <code>Connection</code> objects which better suit how those
 39 * applications work.
 40 * 
 41 * @version $Id: EventDispatcher.java 457 2009-01-15 17:37:42Z orank $
 42 * @see com.adenki.smpp.event.SimpleEventDispatcher
 43 */
 44public interface EventDispatcher {
 45
 46    /**
 47     * Initialise the event dispatcher. The <code>init</code> method will be
 48     * called by the <code>Connection</code> before it makes any attempt to
 49     * add any observers or deliver any events via the dispatcher.
 50     */
 51    void init();
 52
 53    /**
 54     * Event dispatcher clean up. The <code>destroy</code> method will be
 55     * called by the <code>Connection</code> when it is finished delivering
 56     * events to it and the receiver daemon thread is exiting. Any initialising
 57     * done in the <code>init</code> method can be cleaned up here.
 58     * <p>
 59     * The <code>destroy</code> method <b>must not </b> interfere with the
 60     * delivery of any events notified to the event dispatcher before the call
 61     * to this method.
 62     * </p>
 63     */
 64    void destroy();
 65
 66    /**
 67     * Add an observer to this event dispatcher.
 68     * 
 69     * @param observer
 70     *            the observer object to add.
 71     */
 72    void addObserver(SessionObserver observer);
 73
 74    /**
 75     * Remove an observer from this event dispatcher.
 76     * 
 77     * @param observer
 78     *            the observer object to remove from the registered observers.
 79     */
 80    void removeObserver(SessionObserver observer);
 81
 82    /**
 83     * Get a read-only collection view of all the observers registered with
 84     * this event dispatcher. This is useful for copying all of the observers
 85     * registered on one EventDispatcher into another.
 86     * @return A read-only collection of all the observers registered with
 87     * this dispatcher.
 88     */
 89    Collection<SessionObserver> getObservers();
 90    
 91    /**
 92     * Get an iterator over the currently registered observers.
 93     * 
 94     * @return an iterator object which iterates over all registered observers.
 95     */
 96    Iterator<SessionObserver> observerIterator();
 97
 98    /**
 99     * Notify all registered observers of an SMPP event.
100     * 
101     * @param event
102     *            the SMPP event to notify observers of.
103     */
104    void notifyObservers(Session conn, SMPPEvent event);
105
106    /**
107     * Notify all registered observers of a received SMPP packet.
108     * 
109     * @param packet
110     *            the SMPP packet to notify observers of.
111     */
112    void notifyObservers(Session conn, SMPPPacket packet);
113}
114