Session.java 6.35 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
/**
 * $RCSfile$
 * $Revision: 3174 $
 * $Date: 2005-12-08 17:41:00 -0300 (Thu, 08 Dec 2005) $
 *
 * Copyright (C) 2007 Jive Software. All rights reserved.
 *
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
 */

12
package org.jivesoftware.openfire.session;
13

14 15
import org.jivesoftware.openfire.RoutableChannelHandler;
import org.jivesoftware.openfire.StreamID;
16 17 18
import org.xmpp.packet.JID;
import org.xmpp.packet.Packet;

19
import java.net.UnknownHostException;
20 21 22 23 24 25 26 27 28 29 30 31
import java.util.Date;

/**
 * The session represents a connection between the server and a client (c2s) or
 * another server (s2s) as well as a connection with a component. Authentication and
 * user accounts are associated with c2s connections while s2s has an optional authentication
 * association but no single user user.<p>
 *
 * Obtain object managers from the session in order to access server resources.
 *
 * @author Gaston Dombiak
 */
32
public interface Session extends RoutableChannelHandler {
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51

    /**
     * Version of the XMPP spec supported as MAJOR_VERSION.MINOR_VERSION (e.g. 1.0).
     */
	public static final int MAJOR_VERSION = 1;
    public static final int MINOR_VERSION = 0;

    public static final int STATUS_CLOSED = -1;
    public static final int STATUS_CONNECTED = 1;
    public static final int STATUS_AUTHENTICATED = 3;

    /**
      * Obtain the address of the user. The address is used by services like the core
      * server packet router to determine if a packet should be sent to the handler.
      * Handlers that are working on behalf of the server should use the generic server
      * hostname address (e.g. server.com).
      *
      * @return the address of the packet handler.
      */
52
    public JID getAddress();
53 54 55 56 57 58

    /**
     * Obtain the current status of this session.
     *
     * @return The status code for this session
     */
59
    public int getStatus();
60 61 62 63 64 65 66

    /**
     * Obtain the stream ID associated with this sesison. Stream ID's are generated by the server
     * and should be unique and random.
     *
     * @return This session's assigned stream ID
     */
67
    public StreamID getStreamID();
68

69 70 71 72 73 74 75
    /**
     * Obtain the name of the server this session belongs to.
     *
     * @return the server name.
     */
    public String getServerName();
    
76 77 78 79 80
    /**
     * Obtain the date the session was created.
     *
     * @return the session's creation date.
     */
81
    public Date getCreationDate();
82 83 84 85 86 87

    /**
     * Obtain the time the session last had activity.
     *
     * @return The last time the session received activity.
     */
88
    public Date getLastActiveDate();
89 90 91 92 93 94

    /**
     * Obtain the number of packets sent from the client to the server.
     *
     * @return The number of packets sent from the client to the server.
     */
95
    public long getNumClientPackets();
96 97 98 99 100 101

    /**
     * Obtain the number of packets sent from the server to the client.
     *
     * @return The number of packets sent from the server to the client.
     */
102
    public long getNumServerPackets();
103 104
    
    /**
105 106 107 108 109 110 111 112 113
     * Close this session including associated socket connection. The order of
     * events for closing the session is:
     * <ul>
     *      <li>Set closing flag to prevent redundant shutdowns.
     *      <li>Call notifyEvent all listeners that the channel is shutting down.
     *      <li>Close the socket.
     * </ul>
     */
    public void close();
114

115 116 117 118 119 120
    /**
     * Returns true if the connection/session is closed.
     *
     * @return true if the connection is closed.
     */
    public boolean isClosed();
121 122

    /**
123
     * Returns true if this connection is secure.
124
     *
125
     * @return true if the connection is secure (e.g. SSL/TLS)
126
     */
127
    public boolean isSecure();
128

129 130 131 132 133 134 135
    /**
     * Returns the IP address string in textual presentation.
     *
     * @return  the raw IP address in a string format.
     * @throws java.net.UnknownHostException if IP address of host could not be determined.
     */
    public String getHostAddress() throws UnknownHostException;
136 137

    /**
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
     * Gets the host name for this IP address.
     *
     * <p>If this InetAddress was created with a host name,
     * this host name will be remembered and returned;
     * otherwise, a reverse name lookup will be performed
     * and the result will be returned based on the system
     * configured name lookup service. If a lookup of the name service
     * is required, call
     * {@link java.net.InetAddress#getCanonicalHostName() getCanonicalHostName}.
     *
     * <p>If there is a security manager, its
     * <code>checkConnect</code> method is first called
     * with the hostname and <code>-1</code>
     * as its arguments to see if the operation is allowed.
     * If the operation is not allowed, it will return
     * the textual representation of the IP address.
     *
     * @return  the host name for this IP address, or if the operation
     *    is not allowed by the security check, the textual
     *    representation of the IP address.
     * @throws java.net.UnknownHostException if IP address of host could not be determined.
159
     *
160 161
     * @see java.net.InetAddress#getCanonicalHostName
     * @see SecurityManager#checkConnect
162
     */
163
    public String getHostName() throws UnknownHostException;
164

165
    public abstract void process(Packet packet);
166 167

    /**
168 169 170
     * 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 #process(Packet)}.<p>
171
     *
172 173 174 175 176
     * 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.
177
     */
178
    public void deliverRawText(String text);
179

180 181 182 183 184 185 186 187 188
    /**
     * Verifies that the connection is still live. Typically this is done by
     * sending a whitespace character between packets.
     *
     * // TODO No one is sending this message now. Delete it?
     *
     * @return true if the socket remains valid, false otherwise.
     */
    public boolean validate();
189
}