/*
* Copyright (C) 2005-2008 Jive Software. All rights reserved.
*
* 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.
*/
package org.jivesoftware.openfire.session;
import org.jivesoftware.openfire.RoutableChannelHandler;
import org.jivesoftware.openfire.StreamID;
import org.xmpp.packet.JID;
import org.xmpp.packet.Packet;
import java.net.UnknownHostException;
import java.security.cert.Certificate;
import java.util.Date;
import java.util.Locale;
/**
* 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
*/
public interface Session extends RoutableChannelHandler {
/**
* Version of the XMPP spec supported as MAJOR_VERSION.MINOR_VERSION (e.g. 1.0).
*/
int MAJOR_VERSION = 1;
int MINOR_VERSION = 0;
int STATUS_CLOSED = -1;
int STATUS_CONNECTED = 1;
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.
*/
@Override
JID getAddress();
/**
* Obtain the current status of this session.
*
* @return The status code for this session
*/
int getStatus();
/**
* 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
*/
StreamID getStreamID();
/**
* Obtain the name of the server this session belongs to.
*
* @return the server name.
*/
String getServerName();
/**
* Obtain the date the session was created.
*
* @return the session's creation date.
*/
Date getCreationDate();
/**
* Obtain the time the session last had activity.
*
* @return The last time the session received activity.
*/
Date getLastActiveDate();
/**
* Obtain the number of packets sent from the client to the server.
*
* @return The number of packets sent from the client to the server.
*/
long getNumClientPackets();
/**
* Obtain the number of packets sent from the server to the client.
*
* @return The number of packets sent from the server to the client.
*/
long getNumServerPackets();
/**
* 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>
*/
void close();
/**
* Returns true if the connection/session is closed.
*
* @return true if the connection is closed.
*/
boolean isClosed();
/**
* Returns true if this connection is secure.
*
* @return true if the connection is secure (e.g. SSL/TLS)
*/
boolean isSecure();
/**
* Returns the peer certificates associated with this session, if any.
*
* @return certificates, possibly empty or null.
*/
Certificate[] getPeerCertificates();
/**
* 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.
*/
String getHostAddress() throws UnknownHostException;
/**
* 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.
*
* @see java.net.InetAddress#getCanonicalHostName
* @see SecurityManager#checkConnect
*/
String getHostName() throws UnknownHostException;
@Override
void process( Packet packet );
/**
* 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>
*
* 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.
*/
void deliverRawText( String text );
/**
* 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.
*/
boolean validate();
/**
* Returns the TLS cipher suite name, if any.
* Always returns a valid string, though the string may be "NONE"
* @return cipher suite name.
*/
String getCipherSuiteName();
/**
* Returns the locale that is used for this session (e.g. {@link Locale#ENGLISH}).
*
* @return The language for the session.
*/
Locale getLanguage();
}