Session.java 6.78 KB
Newer Older
1 2 3 4 5
/**
 * $RCSfile$
 * $Revision: 3174 $
 * $Date: 2005-12-08 17:41:00 -0300 (Thu, 08 Dec 2005) $
 *
6
 * Copyright (C) 2005-2008 Jive Software. All rights reserved.
7
 *
8 9 10 11 12 13 14 15 16 17 18
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
19 20
 */

21
package org.jivesoftware.openfire.session;
22

23 24
import org.jivesoftware.openfire.RoutableChannelHandler;
import org.jivesoftware.openfire.StreamID;
25 26 27
import org.xmpp.packet.JID;
import org.xmpp.packet.Packet;

28
import java.net.UnknownHostException;
29 30 31 32 33 34 35 36 37 38 39 40
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
 */
41
public interface Session extends RoutableChannelHandler {
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60

    /**
     * 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.
      */
61
    public JID getAddress();
62 63 64 65 66 67

    /**
     * Obtain the current status of this session.
     *
     * @return The status code for this session
     */
68
    public int getStatus();
69 70 71 72 73 74 75

    /**
     * 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
     */
76
    public StreamID getStreamID();
77

78 79 80 81 82 83 84
    /**
     * Obtain the name of the server this session belongs to.
     *
     * @return the server name.
     */
    public String getServerName();
    
85 86 87 88 89
    /**
     * Obtain the date the session was created.
     *
     * @return the session's creation date.
     */
90
    public Date getCreationDate();
91 92 93 94 95 96

    /**
     * Obtain the time the session last had activity.
     *
     * @return The last time the session received activity.
     */
97
    public Date getLastActiveDate();
98 99 100 101 102 103

    /**
     * Obtain the number of packets sent from the client to the server.
     *
     * @return The number of packets sent from the client to the server.
     */
104
    public long getNumClientPackets();
105 106 107 108 109 110

    /**
     * Obtain the number of packets sent from the server to the client.
     *
     * @return The number of packets sent from the server to the client.
     */
111
    public long getNumServerPackets();
112 113
    
    /**
114 115 116 117 118 119 120 121 122
     * 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();
123

124 125 126 127 128 129
    /**
     * Returns true if the connection/session is closed.
     *
     * @return true if the connection is closed.
     */
    public boolean isClosed();
130 131

    /**
132
     * Returns true if this connection is secure.
133
     *
134
     * @return true if the connection is secure (e.g. SSL/TLS)
135
     */
136
    public boolean isSecure();
137

138 139 140 141 142 143 144
    /**
     * 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;
145 146

    /**
147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
     * 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.
168
     *
169 170
     * @see java.net.InetAddress#getCanonicalHostName
     * @see SecurityManager#checkConnect
171
     */
172
    public String getHostName() throws UnknownHostException;
173

174
    public abstract void process(Packet packet);
175 176

    /**
177 178 179
     * 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>
180
     *
181 182 183 184 185
     * 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.
186
     */
187
    public void deliverRawText(String text);
188

189 190 191 192 193 194 195 196 197
    /**
     * 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();
198
}