/** * $RCSfile$ * $Revision$ * $Date$ * * Copyright (C) 2004 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. */ package org.jivesoftware.messenger; import org.jivesoftware.messenger.auth.UnauthorizedException; import java.net.InetAddress; import java.net.UnknownHostException; import java.io.IOException; import javax.xml.stream.XMLStreamException; import javax.xml.stream.XMLStreamWriter; /** * <p>Represents a connection on the server.</p> * * @author Iain Shigeoka */ public interface Connection { /** * <p>Verify that the connection is still live.</p> * <p>Typically this is done by sending a whitespace character between packets.</p> * * @return True if the socket remains valid, false otherwise */ boolean validate(); /** * Initializes the connection with it's owning session. Allows the * connection class to configure itself with session related information * (e.g. stream ID). * * @param session The session that owns this connection */ void init(Session session); /** * <p>Obtain the InetAddress describing the connection.</p> * * @return The InetAddress describing the underlying connection properties * @throws UnauthorizedException If caller doesn't have permission to * access this resource */ InetAddress getInetAddress() throws UnauthorizedException, UnknownHostException; /** * <p>Obtain the XmlSerializer used to send data to the client.</p> * <P>The serializer should only be used to obtain information about the * serialization and should not be written to directly. Other threads maybe * trying to write to the serializer so it is important that all writes are * properly synchronized.</p> * * @return The XmlSerializer underlying this connection * @throws UnauthorizedException If caller doesn't have permission to access this resource */ XMLStreamWriter getSerializer() throws UnauthorizedException; /** * Close this session including associated socket connection. * <p/> * 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> * * @throws UnauthorizedException If caller doesn't have permission to access this resource */ void close() throws UnauthorizedException; /** * Retrieve the closed state of the Session. * * @return True if the session is closed */ boolean isClosed(); /** * <p>Determines if this connection is secure.</p> * * @return True if the connection is secure (e.g. SSL/TLS) */ boolean isSecure(); /** * 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; /** * 9 * 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; /** * Delivers the packet to this XMPPAddress without checking the recipient. * The method essentially calls * <code>socket.send(packet.getWriteBuffer())</code> * * @param packet The packet to deliver. * @throws UnauthorizedException If caller doesn't have permission to access this resource * @throws XMLStreamException if there was a problem sending the packet */ void deliver(XMPPPacket packet) throws UnauthorizedException, XMLStreamException; /** * Delivers an arbitraty text to this XMPPAddress without checking the recipient. * * @param text The text to deliver. * @throws UnauthorizedException If caller doesn't have permission to access this resource * @throws IOException if there was a i/o problem sending the text */ void deliver(String text) throws UnauthorizedException, IOException; }