org.jivesoftware.wildfire
Interface Connection

All Known Implementing Classes:

ClientSessionConnection, HttpSession.HttpVirtualConnection, NIOConnection, SocketConnection, VirtualConnection

public interface Connection

Represents a connection on the server.

Author:

Iain Shigeoka

Nested Class Summary

static class	Connection.CompressionPolicy Enumeration of possible compression policies required to interact with the server.
static class	Connection.TLSPolicy Enumeration of possible TLS policies required to interact with the server.

Method Summary

void	close() Close this session including associated socket connection.
void	deliver(Packet packet) Delivers the packet to this connection without checking the recipient.
void	deliverRawText(String text) Delivers raw text to this connection.
Connection.CompressionPolicy	getCompressionPolicy() Returns whether compression is optional or is disabled.
InetAddress	getInetAddress() Returns the InetAddress describing the connection.
String	getLanguage() Returns the language code that should be used for this connection (e.g.
int	getMajorXMPPVersion() Returns the major version of XMPP being used by this connection (major_version.minor_version.
int	getMinorXMPPVersion() Returns the minor version of XMPP being used by this connection (major_version.minor_version.
PacketDeliverer	getPacketDeliverer() Returns the packet deliverer to use when delivering a packet over the socket fails.
Connection.TLSPolicy	getTlsPolicy() Returns whether TLS is mandatory, optional or is disabled.
void	init(Session session) Initializes the connection with it's owning session.
boolean	isClosed() Returns true if the connection/session is closed.
boolean	isCompressed() Returns true if the connection is using compression.
boolean	isFlashClient() Returns true if the connected client is a flash client.
boolean	isSecure() Returns true if this connection is secure.
void	registerCloseListener(ConnectionCloseListener listener, Object handbackMessage) Registers a listener for close event notification.
void	removeCloseListener(ConnectionCloseListener listener) Removes a registered close event listener.
void	setCompressionPolicy(Connection.CompressionPolicy compressionPolicy) Sets whether compression is enabled or is disabled.
void	setFlashClient(boolean flashClient) Sets whether the connected client is a flash client.
void	setLanaguage(String language) Sets the language code that should be used for this connection (e.g.
void	setTlsPolicy(Connection.TLSPolicy tlsPolicy) Sets whether TLS is mandatory, optional or is disabled.
void	setXMPPVersion(int majorVersion, int minorVersion) Sets the XMPP version information.
void	startCompression() Start using compression for this connection.
void	startTLS(boolean clientMode, String remoteServer) Secures the plain connection by negotiating TLS with the client.
void	systemShutdown() Notification message indicating that the server is being shutdown.
boolean	validate() Verifies that the connection is still live.

Method Detail

validate

boolean validate()

Verifies that the connection is still live. Typically this is done by sending a whitespace character between packets.

Returns:

true if the socket remains valid, false otherwise.

init

void init(Session session)

Initializes the connection with it's owning session. Allows the connection class to configure itself with session related information (e.g. stream ID).

Parameters:

session - the session that owns this connection

getInetAddress

InetAddress getInetAddress()
                           throws UnknownHostException

Returns the InetAddress describing the connection.

Returns:

the InetAddress describing the underlying connection properties.

Throws:

UnknownHostException - if IP address of host could not be determined.

close

void close()

Close this session including associated socket connection. The order of events for closing the session is:

• Set closing flag to prevent redundant shutdowns.
• Call notifyEvent all listeners that the channel is shutting down.
• Close the socket.

systemShutdown

void systemShutdown()

Notification message indicating that the server is being shutdown. Implementors should send a stream error whose condition is system-shutdown before closing the connection.

isClosed

boolean isClosed()

Returns true if the connection/session is closed.

Returns:

true if the connection is closed.

isSecure

boolean isSecure()

Returns true if this connection is secure.

Returns:

true if the connection is secure (e.g. SSL/TLS)

registerCloseListener

void registerCloseListener(ConnectionCloseListener listener,
                           Object handbackMessage)

Registers a listener for close event notification. Registrations after the Session is closed will be immediately notified before 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.

Parameters:

listener - the listener to register for events.

handbackMessage - the object to send in the event notification.

removeCloseListener

void removeCloseListener(ConnectionCloseListener listener)

Removes 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.)

Parameters:

listener - the listener to deregister for close events.

deliver

void deliver(Packet packet)
             throws UnauthorizedException

Delivers the packet to this connection without checking the recipient. The method essentially calls socket.send(packet.getWriteBuffer()).

Parameters:

packet - the packet to deliver.

Throws:

UnauthorizedException - if a permission error was detected.

deliverRawText

void deliverRawText(String text)

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 deliver(org.xmpp.packet.Packet).

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.

Parameters:

text - the XML stanzas represented kept in a String.

isFlashClient

boolean isFlashClient()

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".

Returns:

true if the connected client is a flash client.

setFlashClient

void setFlashClient(boolean flashClient)

Sets whether 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".

Parameters:

flashClient - true if the if the connection is a flash client.

getMajorXMPPVersion

int getMajorXMPPVersion()

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".

Returns:

the major XMPP version being used by this connection.

getMinorXMPPVersion

int getMinorXMPPVersion()

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".

Returns:

the minor XMPP version being used by this connection.

setXMPPVersion

void setXMPPVersion(int majorVersion,
                    int minorVersion)

Sets the XMPP version information. 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".

Parameters:

majorVersion - the major version.

minorVersion - the minor version.

getLanguage

String getLanguage()

Returns the language code that should be used for this connection (e.g. "en").

Returns:

the language code for the connection.

setLanaguage

void setLanaguage(String language)

Sets the language code that should be used for this connection (e.g. "en").

Parameters:

language - the language code.

isCompressed

boolean isCompressed()

Returns true if the connection is using compression.

Returns:

true if the connection is using compression.

getCompressionPolicy

Connection.CompressionPolicy getCompressionPolicy()

Returns whether compression is optional or is disabled.

Returns:

whether compression is optional or is disabled.

setCompressionPolicy

void setCompressionPolicy(Connection.CompressionPolicy compressionPolicy)

Sets whether compression is enabled or is disabled.

Parameters:

compressionPolicy - whether Compression is enabled or is disabled.

getTlsPolicy

Connection.TLSPolicy getTlsPolicy()

Returns whether TLS is mandatory, optional or is disabled. When TLS is mandatory clients are required to secure their connections or otherwise their connections will be closed. On the other hand, when TLS is disabled clients are not allowed to secure their connections using TLS. Their connections will be closed if they try to secure the connection. in this last case.

Returns:

whether TLS is mandatory, optional or is disabled.

setTlsPolicy

void setTlsPolicy(Connection.TLSPolicy tlsPolicy)

Sets whether TLS is mandatory, optional or is disabled. When TLS is mandatory clients are required to secure their connections or otherwise their connections will be closed. On the other hand, when TLS is disabled clients are not allowed to secure their connections using TLS. Their connections will be closed if they try to secure the connection. in this last case.

Parameters:

tlsPolicy - whether TLS is mandatory, optional or is disabled.

getPacketDeliverer

PacketDeliverer getPacketDeliverer()

Returns the packet deliverer to use when delivering a packet over the socket fails. The packet deliverer will retry to send the packet using some other connection, will store the packet offline for later retrieval or will just drop it.

Returns:

the packet deliverer to use when delivering a packet over the socket fails.

startTLS

void startTLS(boolean clientMode,
              String remoteServer)
              throws Exception

Secures the plain connection by negotiating TLS with the client. When connecting to a remote server then clientMode will be true and remoteServer is the server name of the remote server. Otherwise clientMode will be false and remoteServer null.

Parameters:

clientMode - boolean indicating if this entity is a client or a server.

remoteServer - server name of the remote server we are connecting to or null when not in client mode.

Throws:

Exception - if an error occured while securing the connection.

startCompression

void startCompression()

Start using compression for this connection. Compression will only be available after TLS has been negotiated. This means that a connection can never be using compression before TLS. However, it is possible to use compression without TLS.