Connection.java 4.93 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
Matt Tucker's avatar
Matt Tucker committed
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
Matt Tucker's avatar
Matt Tucker committed
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10
 */
Matt Tucker's avatar
Matt Tucker committed
11

Matt Tucker's avatar
Matt Tucker committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
package org.jivesoftware.messenger;

import org.jivesoftware.messenger.auth.UnauthorizedException;
import java.net.InetAddress;
import java.net.UnknownHostException;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;

/**
 * <p>Represents a connection on the server.</p>
 *
 * @author Iain Shigeoka
 */
public interface Connection {

    /**
     * <p>Verify that the connection is still live.</p>
     * <p>Typically this is done by sending a whitespace character between packets.</p>
     *
     * @return True if the socket remains valid, false otherwise
     */
    boolean validate();

    /**
     * Initializes the connection with it's owning session. Allows the
     * connection class to configure itself with session related information
     * (e.g. stream ID).
     *
     * @param session The session that owns this connection
     */
    void init(Session session);

    /**
     * <p>Obtain the InetAddress describing the connection.</p>
     *
     * @return The InetAddress describing the underlying connection properties
     * @throws UnauthorizedException If caller doesn't have permission to
     *                               access this resource
     */
    InetAddress getInetAddress() throws UnauthorizedException, UnknownHostException;

    /**
     * <p>Obtain the XmlSerializer used to send data to the client.</p>
     * <P>The serializer should only be used to obtain information about the
     * serialization and should not be written to directly. Other threads maybe
     * trying to write to the serializer so it is important that all writes are
     * properly synchronized.</p>
     *
     * @return The XmlSerializer underlying this connection
     * @throws UnauthorizedException If caller doesn't have permission to access this resource
     */
    XMLStreamWriter getSerializer() throws UnauthorizedException;

    /**
     * Close this session including associated socket connection.
     * <p/>
     * Any selector registrations (if using nio) are also removed.
     * The order of events for closing the session is:
     * <ul>
     * <li>set closing flag to prevent redundant shutdowns
     * <li>notifyEvent all listeners that the channel is shutting down
     * <li>close the socket
     * </ul>
     *
     * @throws UnauthorizedException If caller doesn't have permission to access this resource
     */
    void close() throws UnauthorizedException;

    /**
     * Retrieve the closed state of the Session.
     *
     * @return True if the session is closed
     */
    boolean isClosed();

    /**
     * <p>Determines if this connection is secure.</p>
     *
     * @return True if the connection is secure (e.g. SSL/TLS)
     */
    boolean isSecure();

    /**
     * Register a listener for close event notification.  Registrations after
     * the Session is closed will be immediately notified <em>before</em>
     * the registration call returns (within the context of the
     * registration call). An optional handback object can be associated with
     * the registration if the same listener is registered to listen for multiple
     * connection closures.
     *
     * @param listener        The listener to register for events
     * @param handbackMessage The object to send in the event notification
     * @return The message previously registered for this channel or null if no registration existed
     * @throws UnauthorizedException If caller doesn't have permission to access this resource
     */
    Object registerCloseListener(ConnectionCloseListener listener, Object handbackMessage) throws UnauthorizedException;

    /**
     * 9
     * Remove a registered close event listener.  Registered listeners must
     * be able to receive close events up until the time this method returns.
     * (i.e. It is possible to call unregister, receive a close event registration,
     * and then have the unregister call return.)
     *
     * @param listener The listener  to deregister for close events
     * @return The Message registered with this listener or null if the channel was never registered
     * @throws UnauthorizedException If caller doesn't have permission to access this resource
     */
    Object removeCloseListener(ConnectionCloseListener listener) throws UnauthorizedException;

    /**
     * Delivers the packet to this XMPPAddress without checking the recipient.
     * The method essentially calls
     * <code>socket.send(packet.getWriteBuffer())</code>
     *
     * @param packet The packet to deliver.
     * @throws UnauthorizedException If caller doesn't have permission to access this resource
     * @throws XMLStreamException    if there was a problem sending the packet
     */
    void deliver(XMPPPacket packet) throws UnauthorizedException, XMLStreamException;
}