Connection.java 5.9 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision$
 * $Date$
 *
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
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
 */
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 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
package org.jivesoftware.net;

import org.jivesoftware.messenger.auth.UnauthorizedException;

import java.net.InetAddress;
import java.util.Date;

/**
 * <p>Generic representation of a network connection.</p>
 *
 * <p>This interface intentionally tries to abstract the underlying socket
 * to enable generic use with traditional and nio style sockets.</p>
 *
 * @author Iain Shigeoka
 */
public interface Connection {

    /**
     * <p>Obtain the date/time the connection was initially made.</p>
     */
    Date getConnectDate();

    /**
     * <p>Obtain the number of milliseconds the connection has been open.</p>
     *
     * <p>If the connection is still open, this is the time difference between
     * the result of getConnectDate() and the current time
     * (e.g. System.currentTimeMillis() otherwise it returns the
     * number of milliseconds between the opening and closing of the connection.</p>
     *
     * @return The number of milliseconds the connection has been open
     */
    long getUptime();

    /**
     * <p>Obtain the InetAddress describing the connection.</p>
     *
     * @return The InetAddress describing the underlying connection properties
     * access this resource
     */
    InetAddress getInetAddress();

    /**
     * <p>Obtain the InetAddress describing the local side of the connection.</p>
     *
     * @return The InetAddress describing the underlying connection properties
     */
    InetAddress getLocalInetAddress();

    /**
     * <p>Obtain the data consumer that will is used by the connection
     * to send outgoing data out of it's underlying socket.</p>
     *
     * @return The DataConsumer that sends data using this connection
     * @throws IllegalStateException If the connection is closed
     */
    DataConsumer getDataConsumer() throws IllegalStateException;

    /**
     * <p>Obtain the data producer that the connection will send
     * data read from the connection out on. The producer may
     * not have a thread dedicated to it so consumers attached to
     * this producer should return from their consume() method as
     * quickly as possible.</p>
     *
     * @return The DataProducer that reads data using this connection
     * @throws IllegalStateException If the connection is closed
     */
    DataProducer getDataProducer();

    /**
     * Close this session including associated socket connection.
     *
     * 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>
     */
    void close();

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

    /**
     * Retrieve the mechanism used to open this connection
     *
     * @return True if the connection was created as a server accept call,
     * false otherwise
     */
    boolean isAcceptCreated();

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

    /**
     * <p>Sets the security status of this connection.</p>
     *
     * <p>Ordinarily a connection is either insecure (standard Socket
     * or SocketChannel) or secure (SSLSocket). However, many protocols
     * including XMPP and NNTP allow the use of SASL where transport
     * layer security can be established after the connection is created.
     * So application level objects must be able to change the security
     * status of a connection during such negotiations.</p>
     *
     * @param secure True if the connection is secure (e.g. SSL/TLS)
     */
    void setSecure(boolean secure);

    /**
     * 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;

    /**
     * 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;

    /**
     * <p>Sets the connection manager this connection belongs to.</p>
     *
     * <p>Connections may only have on connection manager at a time.</p>
     *
     * @param manager The connection manager for the connection
     */
    void setConnectionManager(ConnectionManager manager);
}