Connection.java 6.03 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
package org.jivesoftware.messenger;

import org.jivesoftware.messenger.auth.UnauthorizedException;
15
import org.xmpp.packet.Packet;
Derek DeMoro's avatar
Derek DeMoro committed
16
import org.dom4j.io.XMLWriter;
17

Matt Tucker's avatar
Matt Tucker committed
18 19
import java.net.InetAddress;
import java.net.UnknownHostException;
Derek DeMoro's avatar
Derek DeMoro committed
20
import java.io.Writer;
Matt Tucker's avatar
Matt Tucker committed
21 22

/**
Matt Tucker's avatar
Matt Tucker committed
23
 * Represents a connection on the server.
Matt Tucker's avatar
Matt Tucker committed
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
 *
 * @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
     */
Derek DeMoro's avatar
Derek DeMoro committed
65
    XMLWriter getSerializer() throws UnauthorizedException;
Matt Tucker's avatar
Matt Tucker committed
66

Derek DeMoro's avatar
Derek DeMoro committed
67 68 69 70 71 72 73
     /**
     * <p>Obtain the Writer used to send data to the client.</p>
     * <P>The writer should be used with caution.</p>
     *
     * @return The Writer underlying this connection
     * @throws UnauthorizedException If caller doesn't have permission to access this resource
     */
Derek DeMoro's avatar
Derek DeMoro committed
74 75
    Writer getWriter() throws UnauthorizedException;

Matt Tucker's avatar
Matt Tucker committed
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 133 134 135 136 137 138 139 140
    /**
     * 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
     */
Matt Tucker's avatar
Matt Tucker committed
141
    void deliver(Packet packet) throws UnauthorizedException;
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161

    /**
     * Sets whether the connected client is a flash client or not. Flash clients need to receive
     * a special character (i.e. \0) at the end of each xml packet. Flash clients may send the
     * character \0 in incoming packets and may start a connection using another openning tag
     * such as: "flash:client".
     *
     * @param flashClient flag that indicates if the client is a flash client.
     */
    void setFlashClient(boolean flashClient);

    /**
     * Returns true if the connected client is a flash client. Flash clients need to receive
     * a special character (i.e. \0) at the end of each xml packet. Flash clients may send the
     * character \0 in incoming packets and may start a connection using another openning tag
     * such as: "flash:client".
     *
     * @return true if the connected client is a flash client.
     */
    boolean isFlashClient();
Matt Tucker's avatar
Matt Tucker committed
162
}