org.jivesoftware.smack
Class XMPPConnection

java.lang.Object
  org.jivesoftware.smack.Connection
      org.jivesoftware.smack.XMPPConnection

public class XMPPConnection
extends Connection

Creates a socket connection to a XMPP server. This is the default connection to a Jabber server and is specified in the XMPP Core (RFC 3920).

Author:

Matt Tucker

See Also:

Connection

Nested Class Summary

Nested classes/interfaces inherited from class org.jivesoftware.smack.Connection

Connection.InterceptorWrapper, Connection.ListenerWrapper

Field Summary

Fields inherited from class org.jivesoftware.smack.Connection

collectors, compressionHandler, compressionHandlers, config, connectionCounterValue, connectionListeners, DEBUG_ENABLED, debugger, interceptors, reader, recvListeners, saslAuthentication, sendListeners, writer

Constructor Summary

XMPPConnection(ConnectionConfiguration config)
Creates a new XMPP connection in the same way XMPPConnection(ConnectionConfiguration,CallbackHandler) does, but with no callback handler for password prompting of the keystore.

XMPPConnection(ConnectionConfiguration config, javax.security.auth.callback.CallbackHandler callbackHandler)
Creates a new XMPP connection using the specified connection configuration.

XMPPConnection(java.lang.String serviceName)
Creates a new XMPP connection in the same way XMPPConnection(String,CallbackHandler) does, but with no callback handler for password prompting of the keystore.

XMPPConnection(java.lang.String serviceName, javax.security.auth.callback.CallbackHandler callbackHandler)
Creates a new connection to the specified XMPP server.

Method Summary

void	addPacketWriterInterceptor(PacketInterceptor packetInterceptor, PacketFilter packetFilter) Deprecated. replaced by Connection.addPacketInterceptor(PacketInterceptor, PacketFilter).
void	addPacketWriterListener(PacketListener packetListener, PacketFilter packetFilter) Deprecated. replaced by Connection.addPacketSendingListener(PacketListener, PacketFilter).
void	connect() Establishes a connection to the XMPP server and performs an automatic login only if the previous connection state was logged (authenticated).
void	disconnect(Presence unavailablePresence) Closes the connection.
java.lang.String	getConnectionID() Returns the connection ID for this connection, which is the value set by the server when opening a XMPP stream.
Roster	getRoster() Returns the roster for the user.
java.lang.String	getUser() Returns the full XMPP address of the user that is logged in to the connection or null if not logged in yet.
boolean	isAnonymous() Returns true if currently authenticated anonymously.
boolean	isAuthenticated() Returns true if currently authenticated by successfully calling the login method.
boolean	isConnected() Returns true if currently connected to the XMPP server.
boolean	isSecureConnection() Returns true if the connection to the server has successfully negotiated encryption.
boolean	isSocketClosed()
boolean	isUsingCompression() Returns true if network traffic is being compressed.
boolean	isUsingTLS() Returns true if the connection to the server has successfully negotiated TLS.
void	login(java.lang.String username, java.lang.String password, java.lang.String resource) Logs in to the server using the strongest authentication mode supported by the server, then sets presence to available.
void	loginAnonymously() Logs in to the server anonymously.
protected void	notifyReconnection() Sends a notification indicating that the connection was reconnected successfully.
void	removePacketWriterInterceptor(PacketInterceptor packetInterceptor) Deprecated. replaced by Connection.removePacketInterceptor(PacketInterceptor).
void	removePacketWriterListener(PacketListener packetListener) Deprecated. replaced by Connection.removePacketSendingListener(PacketListener).
void	sendPacket(Packet packet) Sends the specified packet to the server.
protected void	shutdown(Presence unavailablePresence) Closes the connection by setting presence to unavailable then closing the stream to the XMPP server.

Methods inherited from class org.jivesoftware.smack.Connection

addConnectionCreationListener, addConnectionListener, addPacketInterceptor, addPacketListener, addPacketSendingListener, createPacketCollector, disconnect, firePacketInterceptors, firePacketSendingListeners, getAccountManager, getChatManager, getConfiguration, getConnectionCreationListeners, getConnectionListeners, getHost, getPacketCollectors, getPacketInterceptors, getPacketListeners, getPacketSendingListeners, getPort, getSASLAuthentication, getServiceCapsNode, getServiceName, initDebugger, isReconnectionAllowed, login, removeConnectionCreationListener, removeConnectionListener, removePacketCollector, removePacketInterceptor, removePacketListener, removePacketSendingListener, setServiceCapsNode

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XMPPConnection

public XMPPConnection(java.lang.String serviceName,
                      javax.security.auth.callback.CallbackHandler callbackHandler)

Creates a new connection to the specified XMPP server. A DNS SRV lookup will be performed to determine the IP address and port corresponding to the service name; if that lookup fails, it's assumed that server resides at serviceName with the default port of 5222. Encrypted connections (TLS) will be used if available, stream compression is disabled, and standard SASL mechanisms will be used for authentication.

This is the simplest constructor for connecting to an XMPP server. Alternatively, you can get fine-grained control over connection settings using the XMPPConnection(ConnectionConfiguration) constructor.

Note that XMPPConnection constructors do not establish a connection to the server and you must call connect().

The CallbackHandler will only be used if the connection requires the client provide an SSL certificate to the server. The CallbackHandler must handle the PasswordCallback to prompt for a password to unlock the keystore containing the SSL certificate.

Parameters:

serviceName - the name of the XMPP server to connect to; e.g. example.com.

callbackHandler - the CallbackHandler used to prompt for the password to the keystore.

XMPPConnection

public XMPPConnection(java.lang.String serviceName)

Creates a new XMPP connection in the same way XMPPConnection(String,CallbackHandler) does, but with no callback handler for password prompting of the keystore. This will work in most cases, provided the client is not required to provide a certificate to the server.

Parameters:

serviceName - the name of the XMPP server to connect to; e.g. example.com.

XMPPConnection

public XMPPConnection(ConnectionConfiguration config)

Creates a new XMPP connection in the same way XMPPConnection(ConnectionConfiguration,CallbackHandler) does, but with no callback handler for password prompting of the keystore. This will work in most cases, provided the client is not required to provide a certificate to the server.

Parameters:

config - the connection configuration.

XMPPConnection

public XMPPConnection(ConnectionConfiguration config,
                      javax.security.auth.callback.CallbackHandler callbackHandler)

Creates a new XMPP connection using the specified connection configuration.

Manually specifying connection configuration information is suitable for advanced users of the API. In many cases, using the XMPPConnection(String) constructor is a better approach.

Note that XMPPConnection constructors do not establish a connection to the server and you must call connect().

The CallbackHandler will only be used if the connection requires the client provide an SSL certificate to the server. The CallbackHandler must handle the PasswordCallback to prompt for a password to unlock the keystore containing the SSL certificate.

Parameters:

config - the connection configuration.

callbackHandler - the CallbackHandler used to prompt for the password to the keystore.

Method Detail

getConnectionID

public java.lang.String getConnectionID()

Description copied from class: Connection

Returns the connection ID for this connection, which is the value set by the server when opening a XMPP stream. If the server does not set a connection ID, this value will be null. This value will be null if not connected to the server.

Specified by:

getConnectionID in class Connection

Returns:

the ID of this connection returned from the XMPP server or null if not connected to the server.

getUser

public java.lang.String getUser()

Description copied from class: Connection

Returns the full XMPP address of the user that is logged in to the connection or null if not logged in yet. An XMPP address is in the form username@server/resource.

Specified by:

getUser in class Connection

Returns:

the full XMPP address of the user logged in.

login

public void login(java.lang.String username,
                  java.lang.String password,
                  java.lang.String resource)
           throws XMPPException

Description copied from class: Connection

Logs in to the server using the strongest authentication mode supported by the server, then sets presence to available. If the server supports SASL authentication then the user will be authenticated using SASL if not Non-SASL authentication will be tried. If more than five seconds (default timeout) elapses in each step of the authentication process without a response from the server, or if an error occurs, a XMPPException will be thrown.

Before logging in (i.e. authenticate) to the server the connection must be connected. It is possible to log in without sending an initial available presence by using ConnectionConfiguration.setSendPresence(boolean). If this connection is not interested in loading its roster upon login then use ConnectionConfiguration.setRosterLoadedAtLogin(boolean). Finally, if you want to not pass a password and instead use a more advanced mechanism while using SASL then you may be interested in using ConnectionConfiguration.setCallbackHandler(javax.security.auth.callback.CallbackHandler). For more advanced login settings see ConnectionConfiguration.

Specified by:

login in class Connection

Parameters:

username - the username.

password - the password or null if using a CallbackHandler.

resource - the resource.

Throws:

XMPPException - if an error occurs.

loginAnonymously

public void loginAnonymously()
                      throws XMPPException

Description copied from class: Connection

Logs in to the server anonymously. Very few servers are configured to support anonymous authentication, so it's fairly likely logging in anonymously will fail. If anonymous login does succeed, your XMPP address will likely be in the form "123ABC@server/789XYZ" or "server/123ABC" (where "123ABC" and "789XYZ" is a random value generated by the server).

Specified by:

loginAnonymously in class Connection

Throws:

XMPPException - if an error occurs or anonymous logins are not supported by the server.

getRoster

public Roster getRoster()

Description copied from class: Connection

Returns the roster for the user.

This method will never return null, instead if the user has not yet logged into the server or is logged in anonymously all modifying methods of the returned roster object like Roster.createEntry(String, String, String[]), Roster.removeEntry(RosterEntry) , etc. except adding or removing RosterListeners will throw an IllegalStateException.

Specified by:

getRoster in class Connection

Returns:

the user's roster.

isConnected

public boolean isConnected()

Description copied from class: Connection

Returns true if currently connected to the XMPP server.

Specified by:

isConnected in class Connection

Returns:

true if connected.

isSecureConnection

public boolean isSecureConnection()

Description copied from class: Connection

Returns true if the connection to the server has successfully negotiated encryption.

Specified by:

isSecureConnection in class Connection

Returns:

true if a secure connection to the server.

isSocketClosed

public boolean isSocketClosed()

isAuthenticated

public boolean isAuthenticated()

Description copied from class: Connection

Returns true if currently authenticated by successfully calling the login method.

Specified by:

isAuthenticated in class Connection

Returns:

true if authenticated.

isAnonymous

public boolean isAnonymous()

Description copied from class: Connection

Returns true if currently authenticated anonymously.

Specified by:

isAnonymous in class Connection

Returns:

true if authenticated anonymously.

shutdown

protected void shutdown(Presence unavailablePresence)

Closes the connection by setting presence to unavailable then closing the stream to the XMPP server. The shutdown logic will be used during a planned disconnection or when dealing with an unexpected disconnection. Unlike Connection.disconnect() the connection's packet reader, packet writer, and Roster will not be removed; thus connection's state is kept.

Parameters:

unavailablePresence - the presence packet to send during shutdown.

disconnect

public void disconnect(Presence unavailablePresence)

Description copied from class: Connection

Closes the connection. A custom unavailable presence is sent to the server, followed by closing the stream. The Connection can still be used for connecting to the server again. A custom unavilable presence is useful for communicating offline presence information such as "On vacation". Typically, just the status text of the presence packet is set with online information, but most XMPP servers will deliver the full presence packet with whatever data is set.

This method cleans up all resources used by the connection. Therefore, the roster, listeners and other stateful objects cannot be re-used by simply calling connect() on this connection again. This is unlike the behavior during unexpected disconnects (and subsequent connections). In that case, all state is preserved to allow for more seamless error recovery.

Specified by:

disconnect in class Connection

Parameters:

unavailablePresence - the presence packet to send during shutdown.

sendPacket

public void sendPacket(Packet packet)

Description copied from class: Connection

Sends the specified packet to the server.

Specified by:

sendPacket in class Connection

Parameters:

packet - the packet to send.

addPacketWriterInterceptor

public void addPacketWriterInterceptor(PacketInterceptor packetInterceptor,
                                       PacketFilter packetFilter)

Deprecated. replaced by Connection.addPacketInterceptor(PacketInterceptor, PacketFilter).

Registers a packet interceptor with this connection. The interceptor will be invoked every time a packet is about to be sent by this connection. Interceptors may modify the packet to be sent. A packet filter determines which packets will be delivered to the interceptor.

Parameters:

packetInterceptor - the packet interceptor to notify of packets about to be sent.

packetFilter - the packet filter to use.

removePacketWriterInterceptor

public void removePacketWriterInterceptor(PacketInterceptor packetInterceptor)

Deprecated. replaced by Connection.removePacketInterceptor(PacketInterceptor).

Removes a packet interceptor.

Parameters:

packetInterceptor - the packet interceptor to remove.

addPacketWriterListener

public void addPacketWriterListener(PacketListener packetListener,
                                    PacketFilter packetFilter)

Deprecated. replaced by Connection.addPacketSendingListener(PacketListener, PacketFilter).

Registers a packet listener with this connection. The listener will be notified of every packet that this connection sends. A packet filter determines which packets will be delivered to the listener. Note that the thread that writes packets will be used to invoke the listeners. Therefore, each packet listener should complete all operations quickly or use a different thread for processing.

Parameters:

packetListener - the packet listener to notify of sent packets.

packetFilter - the packet filter to use.

removePacketWriterListener

public void removePacketWriterListener(PacketListener packetListener)

Deprecated. replaced by Connection.removePacketSendingListener(PacketListener).

Removes a packet listener for sending packets from this connection.

Parameters:

packetListener - the packet listener to remove.

isUsingTLS

public boolean isUsingTLS()

Returns true if the connection to the server has successfully negotiated TLS. Once TLS has been negotiatied the connection has been secured.

Returns:

true if the connection to the server has successfully negotiated TLS.

isUsingCompression

public boolean isUsingCompression()

Description copied from class: Connection

Returns true if network traffic is being compressed. When using stream compression network traffic can be reduced up to 90%. Therefore, stream compression is ideal when using a slow speed network connection. However, the server will need to use more CPU time in order to un/compress network data so under high load the server performance might be affected.

Specified by:

isUsingCompression in class Connection

Returns:

true if network traffic is being compressed.

connect

public void connect()
             throws XMPPException

Establishes a connection to the XMPP server and performs an automatic login only if the previous connection state was logged (authenticated). It basically creates and maintains a socket connection to the server.

Listeners will be preserved from a previous connection if the reconnection occurs after an abrupt termination.

Specified by:

connect in class Connection

Throws:

XMPPException - if an error occurs while trying to establish the connection. Two possible errors can occur which will be wrapped by an XMPPException -- UnknownHostException (XMPP error code 504), and IOException (XMPP error code 502). The error codes and wrapped exceptions can be used to present more appropiate error messages to end-users.

notifyReconnection

protected void notifyReconnection()

Sends a notification indicating that the connection was reconnected successfully.