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

14
import org.xmpp.packet.Packet;
15
import org.jivesoftware.messenger.auth.UnauthorizedException;
16

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

/**
Matt Tucker's avatar
Matt Tucker committed
22
 * Represents a connection on the server.
Matt Tucker's avatar
Matt Tucker committed
23 24 25 26 27 28
 *
 * @author Iain Shigeoka
 */
public interface Connection {

    /**
29 30
     * Verifies that the connection is still live. Typically this is done by
     * sending a whitespace character between packets.
Matt Tucker's avatar
Matt Tucker committed
31
     *
32
     * @return true if the socket remains valid, false otherwise.
Matt Tucker's avatar
Matt Tucker committed
33
     */
34
    public boolean validate();
Matt Tucker's avatar
Matt Tucker committed
35 36 37 38 39 40

    /**
     * Initializes the connection with it's owning session. Allows the
     * connection class to configure itself with session related information
     * (e.g. stream ID).
     *
41
     * @param session the session that owns this connection
Matt Tucker's avatar
Matt Tucker committed
42
     */
43
    public void init(Session session);
Matt Tucker's avatar
Matt Tucker committed
44 45

    /**
46
     * Returns the InetAddress describing the connection.
Matt Tucker's avatar
Matt Tucker committed
47
     *
48
     * @return the InetAddress describing the underlying connection properties.
Matt Tucker's avatar
Matt Tucker committed
49
     */
50
    public InetAddress getInetAddress() throws UnknownHostException;
Matt Tucker's avatar
Matt Tucker committed
51

Derek DeMoro's avatar
Derek DeMoro committed
52
     /**
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
      * Returns the Writer used to send data to the connection. The writer should be
      * used with caution. In the majority of cases, the {@link #deliver(Packet)}
      * method should be used to send data instead of using the writer directly.
      * You must synchronize on the writer before writing data to it to ensure
      * data consistency:
      *
      * <pre>
      * Writer writer = connection.getWriter();
      * synchronized(writer) {
      *     // write data....
      * }</pre>
      *
      * @return the Writer for this connection.
      */
    public Writer getWriter();
Derek DeMoro's avatar
Derek DeMoro committed
68

Matt Tucker's avatar
Matt Tucker committed
69
    /**
70 71
     * Close this session including associated socket connection. The order of
     * events for closing the session is:
Matt Tucker's avatar
Matt Tucker committed
72
     * <ul>
73 74 75
     *      <li>Set closing flag to prevent redundant shutdowns.
     *      <li>Call notifyEvent all listeners that the channel is shutting down.
     *      <li>Close the socket.
Matt Tucker's avatar
Matt Tucker committed
76 77
     * </ul>
     */
78
    public void close();
Matt Tucker's avatar
Matt Tucker committed
79 80

    /**
81
     * Returns true if the connection/session is closed.
Matt Tucker's avatar
Matt Tucker committed
82
     *
83
     * @return true if the connection is closed.
Matt Tucker's avatar
Matt Tucker committed
84
     */
85
    public boolean isClosed();
Matt Tucker's avatar
Matt Tucker committed
86 87

    /**
88
     * Returns true if this connection is secure.
Matt Tucker's avatar
Matt Tucker committed
89
     *
90
     * @return true if the connection is secure (e.g. SSL/TLS)
Matt Tucker's avatar
Matt Tucker committed
91
     */
92
    public boolean isSecure();
Matt Tucker's avatar
Matt Tucker committed
93 94

    /**
95
     * Registers a listener for close event notification. Registrations after
Matt Tucker's avatar
Matt Tucker committed
96 97 98 99 100 101
     * 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.
     *
102 103 104 105
     * @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 <tt>null</tt>
     *      if no registration existed
Matt Tucker's avatar
Matt Tucker committed
106
     */
107
    public Object registerCloseListener(ConnectionCloseListener listener, Object handbackMessage);
Matt Tucker's avatar
Matt Tucker committed
108 109

    /**
110
     * Removes a registered close event listener. Registered listeners must
Matt Tucker's avatar
Matt Tucker committed
111
     * be able to receive close events up until the time this method returns.
112
     * (i.e. it is possible to call unregister, receive a close event registration,
Matt Tucker's avatar
Matt Tucker committed
113 114
     * and then have the unregister call return.)
     *
115 116 117
     * @param listener the listener to deregister for close events.
     * @return the Message registered with this listener or <tt>null</tt> if the
     *      channel was never registered.
Matt Tucker's avatar
Matt Tucker committed
118
     */
119
    public Object removeCloseListener(ConnectionCloseListener listener);
Matt Tucker's avatar
Matt Tucker committed
120 121

    /**
122 123
     * Delivers the packet to this connection without checking the recipient.
     * The method essentially calls <code>socket.send(packet.getWriteBuffer())</code>.
Matt Tucker's avatar
Matt Tucker committed
124
     *
125
     * @param packet the packet to deliver.
Matt Tucker's avatar
Matt Tucker committed
126
     */
127
    public void deliver(Packet packet) throws UnauthorizedException;
128

129 130 131 132 133 134 135 136 137 138 139 140 141
    /**
     * Delivers raw text to this connection. This is a very low level way for sending
     * XML stanzas to the client. This method should not be used unless you have very
     * good reasons for not using {@link #deliver(org.xmpp.packet.Packet)}.<p>
     *
     * This method avoids having to get the writer of this connection and mess directly
     * with the writer. Therefore, this method ensures a correct delivery of the stanza
     * even if other threads were sending data concurrently.
     *
     * @param text the XML stanzas represented kept in a String.
     */
    public void deliverRawText(String text);

142
    /**
143 144 145 146
     * 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".
147
     *
148
     * @return true if the connected client is a flash client.
149
     */
150
    public boolean isFlashClient();
151 152

    /**
153 154 155 156
     * Returns the major version of XMPP being used by this connection
     * (major_version.minor_version. In most cases, the version should be
     * "1.0". However, older clients using the "Jabber" protocol do not set a
     * version. In that case, the version is "0.0".
157
     *
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
     * @return the major XMPP version being used by this connection.
     */
    public int getMajorXMPPVersion();

    /**
     * Returns the minor version of XMPP being used by this connection
     * (major_version.minor_version. In most cases, the version should be
     * "1.0". However, older clients using the "Jabber" protocol do not set a
     * version. In that case, the version is "0.0".
     *
     * @return the minor XMPP version being used by this connection.
     */
    public int getMinorXMPPVersion();

    /**
     * Returns the language code that should be used for this connection
     * (e.g. "en").
     *
     * @return the language code for the connection.
177
     */
178
    public String getLanguage();
Matt Tucker's avatar
Matt Tucker committed
179
}