org.jivesoftware.smack

Interface XMPPConnection

All Known Implementing Classes:

AbstractXMPPConnection

public interface XMPPConnection

The abstract XMPPConnection class provides an interface for connections to a XMPP server and implements shared methods which are used by the different types of connections (e.g. XMPPTCPConnection or XMPPBOSHConnection). To create a connection to a XMPP server a simple usage of this API might look like the following:

 // Create a connection to the igniterealtime.org XMPP server.
 XMPPConnection con = new XMPPTCPConnection("igniterealtime.org");
 // Connect to the server
 con.connect();
 // Most servers require you to login before performing other tasks.
 con.login("jsmith", "mypass");
 // Start a new conversation with John Doe and send him a message.
 Chat chat = ChatManager.getInstanceFor(con).createChat("[email protected]", new MessageListener() {
     public void processMessage(Chat chat, Message message) {
         // Print out any messages we get back to standard out.
         System.out.println("Received message: " + message);
     }
 });
 chat.sendMessage("Howdy!");
 // Disconnect from the server
 con.disconnect();
 

Connections can be reused between connections. This means that an Connection may be connected, disconnected and then connected again. Listeners of the Connection will be retained across connections.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	XMPPConnection.FromMode

Method Summary

Methods

Modifier and Type	Method and Description
void	addConnectionListener(ConnectionListener connectionListener) Adds a connection listener to this connection that will be notified when the connection closes or fails.
void	addPacketInterceptor(PacketListener packetInterceptor, PacketFilter packetFilter) Registers a packet interceptor with this connection.
void	addPacketListener(PacketListener packetListener, PacketFilter packetFilter) Registers a packet listener with this connection.
void	addPacketSendingListener(PacketListener packetListener, PacketFilter packetFilter) Registers a packet listener with this connection.
PacketCollector	createPacketCollector(PacketFilter packetFilter) Creates a new packet collector for this connection.
PacketCollector	createPacketCollectorAndSend(IQ packet) Creates a new packet collector collecting packets that are replies to packet.
PacketCollector	createPacketCollectorAndSend(PacketFilter packetFilter, Packet packet) Creates a new packet collector for this connection.
int	getConnectionCounter() Get the connection counter of this XMPPConnection instance.
java.lang.String	getConnectionID() Returns the connection ID for this connection, which is the value set by the server when opening a XMPP stream.
<F extends PacketExtension> F	getFeature(java.lang.String element, java.lang.String namespace) Get the feature packet extensions for a given stream feature of the server, or null if the server doesn't support that feature.
XMPPConnection.FromMode	getFromMode() Get the currently active FromMode.
java.lang.String	getHost() Returns the host name of the server where the XMPP server is running.
long	getLastStanzaReceived() Returns the timestamp in milliseconds when the last stanza was received.
long	getPacketReplyTimeout() Returns the current value of the reply timeout in milliseconds for request for this XMPPConnection instance.
int	getPort() Returns the port number of the XMPP server for this connection.
Roster	getRoster() Returns the roster for the user.
RosterStore	getRosterStore() Get the permanent roster store.
java.lang.String	getServiceName() Returns the name of the service provided by the XMPP server for this connection.
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	hasFeature(java.lang.String element, java.lang.String namespace) Return true if the server supports the given stream feature.
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	isRosterLoadedAtLogin() Returns true if the roster will be loaded from the server when logging in.
boolean	isSecureConnection() Returns true if the connection to the server has successfully negotiated encryption.
boolean	isUsingCompression() Returns true if network traffic is being compressed.
void	removeConnectionListener(ConnectionListener connectionListener) Removes a connection listener from this connection.
void	removePacketCollector(PacketCollector collector) Remove a packet collector of this connection.
void	removePacketInterceptor(PacketListener packetInterceptor) Removes a packet interceptor.
boolean	removePacketListener(PacketListener packetListener) Removes a packet listener for received packets from this connection.
void	removePacketSendingListener(PacketListener packetListener) Removes a packet listener for sending packets from this connection.
void	send(PlainStreamElement element) Send a PlainStreamElement.
void	sendIqWithResponseCallback(IQ iqRequest, PacketListener callback) Send a IQ stanza and invoke callback if there is a result of IQ.Type.result with that result IQ.
void	sendIqWithResponseCallback(IQ iqRequest, PacketListener callback, ExceptionCallback exceptionCallback) Send a IQ stanza and invoke callback if there is a result of IQ.Type.result with that result IQ.
void	sendIqWithResponseCallback(IQ iqRequest, PacketListener callback, ExceptionCallback exceptionCallback, long timeout) Send a IQ stanza and invoke callback if there is a result of IQ.Type.result with that result IQ.
void	sendPacket(Packet packet) Sends the specified packet to the server.
void	sendStanzaWithResponseCallback(Packet stanza, PacketFilter replyFilter, PacketListener callback) Send a stanza and wait asynchronously for a response by using replyFilter.
void	sendStanzaWithResponseCallback(Packet stanza, PacketFilter replyFilter, PacketListener callback, ExceptionCallback exceptionCallback) Send a stanza and wait asynchronously for a response by using replyFilter.
void	sendStanzaWithResponseCallback(Packet stanza, PacketFilter replyFilter, PacketListener callback, ExceptionCallback exceptionCallback, long timeout) Send a stanza and wait asynchronously for a response by using replyFilter.
void	setFromMode(XMPPConnection.FromMode fromMode) Set the FromMode for this connection instance.
void	setPacketReplyTimeout(long timeout) Set the packet reply timeout in milliseconds.

Method Detail

getServiceName

java.lang.String getServiceName()

Returns the name of the service provided by the XMPP server for this connection. This is also called XMPP domain of the connected server. After authenticating with the server the returned value may be different.

Returns:

the name of the service provided by the XMPP server.

getHost

java.lang.String getHost()

Returns the host name of the server where the XMPP server is running. This would be the IP address of the server or a name that may be resolved by a DNS server.

Returns:

the host name of the server where the XMPP server is running or null if not yet connected.

getPort

int getPort()

Returns the port number of the XMPP server for this connection. The default port for normal connections is 5222.

Returns:

the port number of the XMPP server or 0 if not yet connected.

getUser

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. An XMPP address is in the form username@server/resource.

Returns:

the full XMPP address of the user logged in.

getConnectionID

java.lang.String getConnectionID()

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.

Returns:

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

isConnected

boolean isConnected()

Returns true if currently connected to the XMPP server.

Returns:

true if connected.

isAuthenticated

boolean isAuthenticated()

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

Returns:

true if authenticated.

isAnonymous

boolean isAnonymous()

Returns true if currently authenticated anonymously.

Returns:

true if authenticated anonymously.

isSecureConnection

boolean isSecureConnection()

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

Returns:

true if a secure connection to the server.

isUsingCompression

boolean isUsingCompression()

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.

Returns:

true if network traffic is being compressed.

sendPacket

void sendPacket(Packet packet)
                throws SmackException.NotConnectedException

Sends the specified packet to the server.

Parameters:

packet - the packet to send.

Throws:

SmackException.NotConnectedException

send

void send(PlainStreamElement element)
          throws SmackException.NotConnectedException

Send a PlainStreamElement.

This method is not meant for end-user usage! It allows sending plain stream elements, which should not be done by a user manually. Doing so may result in a unstable or unusable connection. Certain Smack APIs use this method to send plain stream elements.

Parameters:

element -

Throws:

SmackException.NotConnectedException

getRoster

Roster getRoster()

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.

Returns:

the user's roster.

Throws:

java.lang.IllegalStateException - if the connection is anonymous

addConnectionListener

void addConnectionListener(ConnectionListener connectionListener)

Adds a connection listener to this connection that will be notified when the connection closes or fails.

Parameters:

connectionListener - a connection listener.

removeConnectionListener

void removeConnectionListener(ConnectionListener connectionListener)

Removes a connection listener from this connection.

Parameters:

connectionListener - a connection listener.

createPacketCollectorAndSend

PacketCollector createPacketCollectorAndSend(IQ packet)
                                             throws SmackException.NotConnectedException

Creates a new packet collector collecting packets that are replies to packet. Does also send packet. The packet filter for the collector is an IQReplyFilter, guaranteeing that packet id and JID in the 'from' address have expected values.

Parameters:

packet - the packet to filter responses from

Returns:

a new packet collector.

Throws:

SmackException.NotConnectedException

createPacketCollectorAndSend

PacketCollector createPacketCollectorAndSend(PacketFilter packetFilter,
                                           Packet packet)
                                             throws SmackException.NotConnectedException

Creates a new packet collector for this connection. A packet filter determines which packets will be accumulated by the collector. A PacketCollector is more suitable to use than a PacketListener when you need to wait for a specific result.

Parameters:

packetFilter - the packet filter to use.

packet - the packet to send right after the collector got created

Returns:

a new packet collector.

Throws:

SmackException.NotConnectedException

createPacketCollector

PacketCollector createPacketCollector(PacketFilter packetFilter)

Creates a new packet collector for this connection. A packet filter determines which packets will be accumulated by the collector. A PacketCollector is more suitable to use than a PacketListener when you need to wait for a specific result.

Note: If you send a Packet right after using this method, then consider using createPacketCollectorAndSend(PacketFilter, Packet) instead. Otherwise make sure cancel the PacketCollector in every case, e.g. even if an exception is thrown, or otherwise you may leak the PacketCollector.

Parameters:

packetFilter - the packet filter to use.

Returns:

a new packet collector.

removePacketCollector

void removePacketCollector(PacketCollector collector)

Remove a packet collector of this connection.

Parameters:

collector - a packet collectors which was created for this connection.

addPacketListener

void addPacketListener(PacketListener packetListener,
                     PacketFilter packetFilter)

Registers a packet listener with this connection. A packet listener will be invoked only when an incoming packet is received. A packet filter determines which packets will be delivered to the listener. If the same packet listener is added again with a different filter, only the new filter will be used. NOTE: If you want get a similar callback for outgoing packets, see addPacketInterceptor(PacketListener, PacketFilter).

Parameters:

packetListener - the packet listener to notify of new received packets.

packetFilter - the packet filter to use.

removePacketListener

boolean removePacketListener(PacketListener packetListener)

Removes a packet listener for received packets from this connection.

Parameters:

packetListener - the packet listener to remove.

Returns:

true if the packet listener was removed

addPacketSendingListener

void addPacketSendingListener(PacketListener packetListener,
                            PacketFilter 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.

removePacketSendingListener

void removePacketSendingListener(PacketListener packetListener)

Removes a packet listener for sending packets from this connection.

Parameters:

packetListener - the packet listener to remove.

addPacketInterceptor

void addPacketInterceptor(PacketListener packetInterceptor,
                        PacketFilter 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.

NOTE: For a similar functionality on incoming packets, see addPacketListener(PacketListener, PacketFilter).

Parameters:

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

packetFilter - the packet filter to use.

removePacketInterceptor

void removePacketInterceptor(PacketListener packetInterceptor)

Removes a packet interceptor.

Parameters:

packetInterceptor - the packet interceptor to remove.

getPacketReplyTimeout

long getPacketReplyTimeout()

Returns the current value of the reply timeout in milliseconds for request for this XMPPConnection instance.

Returns:

the packet reply timeout in milliseconds

setPacketReplyTimeout

void setPacketReplyTimeout(long timeout)

Set the packet reply timeout in milliseconds. In most cases, Smack will throw a SmackException.NoResponseException if no reply to a request was received within the timeout period.

Parameters:

timeout - the packet reply timeout in milliseconds

getConnectionCounter

int getConnectionCounter()

Get the connection counter of this XMPPConnection instance. Those can be used as ID to identify the connection, but beware that the ID may not be unique if you create more then 2*Integer.MAX_VALUE instances as the counter could wrap.

Returns:

the connection counter of this XMPPConnection

setFromMode

void setFromMode(XMPPConnection.FromMode fromMode)

Set the FromMode for this connection instance. Defines how the 'from' attribute of outgoing stanzas should be populated by Smack.

Parameters:

fromMode -

getFromMode

XMPPConnection.FromMode getFromMode()

Get the currently active FromMode.

Returns:

the currently active XMPPConnection.FromMode

getRosterStore

RosterStore getRosterStore()

Get the permanent roster store.

Returns:

the permanent roster store or null

isRosterLoadedAtLogin

boolean isRosterLoadedAtLogin()

Returns true if the roster will be loaded from the server when logging in. This is the common behavior for clients but sometimes clients may want to differ this or just never do it if not interested in rosters.

Returns:

true if the roster will be loaded from the server when logging in.

See Also:

RFC 6121 2.2 - Retrieving the Roster on Login

getFeature

<F extends PacketExtension> F getFeature(java.lang.String element,
                                       java.lang.String namespace)

Get the feature packet extensions for a given stream feature of the server, or null if the server doesn't support that feature.

Parameters:

element -

namespace -

Returns:

a packet extensions of the feature or null

hasFeature

boolean hasFeature(java.lang.String element,
                 java.lang.String namespace)

Return true if the server supports the given stream feature.

Parameters:

element -

namespace -

Returns:

true if the server supports the stream feature.

sendStanzaWithResponseCallback

void sendStanzaWithResponseCallback(Packet stanza,
                                  PacketFilter replyFilter,
                                  PacketListener callback)
                                    throws SmackException.NotConnectedException

Send a stanza and wait asynchronously for a response by using replyFilter.

If there is a response, then callback will be invoked. The callback will be invoked at most once and it will be not invoked after the connections default reply timeout has been elapsed.

Parameters:

stanza - the stanza to send (required)

replyFilter - the filter used to determine response stanza (required)

callback - the callback invoked if there is a response (required)

Throws:

SmackException.NotConnectedException

sendStanzaWithResponseCallback

void sendStanzaWithResponseCallback(Packet stanza,
                                  PacketFilter replyFilter,
                                  PacketListener callback,
                                  ExceptionCallback exceptionCallback)
                                    throws SmackException.NotConnectedException

Send a stanza and wait asynchronously for a response by using replyFilter.

If there is a response, then callback will be invoked. If there is no response after the connections default reply timeout, then exceptionCallback will be invoked with a SmackException.NoResponseException. The callback will be invoked at most once.

Parameters:

stanza - the stanza to send (required)

replyFilter - the filter used to determine response stanza (required)

callback - the callback invoked if there is a response (required)

exceptionCallback - the callback invoked if there is an exception (optional)

Throws:

SmackException.NotConnectedException

sendStanzaWithResponseCallback

void sendStanzaWithResponseCallback(Packet stanza,
                                  PacketFilter replyFilter,
                                  PacketListener callback,
                                  ExceptionCallback exceptionCallback,
                                  long timeout)
                                    throws SmackException.NotConnectedException

Send a stanza and wait asynchronously for a response by using replyFilter.

If there is a response, then callback will be invoked. If there is no response after timeout milliseconds, then exceptionCallback will be invoked with a SmackException.NoResponseException. The callback will be invoked at most once.

Parameters:

stanza - the stanza to send (required)

replyFilter - the filter used to determine response stanza (required)

callback - the callback invoked if there is a response (required)

exceptionCallback - the callback invoked if there is an exception (optional)

timeout - the timeout in milliseconds to wait for a response

Throws:

SmackException.NotConnectedException

sendIqWithResponseCallback

void sendIqWithResponseCallback(IQ iqRequest,
                              PacketListener callback)
                                throws SmackException.NotConnectedException

Send a IQ stanza and invoke callback if there is a result of IQ.Type.result with that result IQ. The callback will not be invoked after the connections default reply timeout has been elapsed.

Parameters:

iqRequest - the IQ stanza to send (required)

callback - the callback invoked if there is result response (required)

Throws:

SmackException.NotConnectedException

sendIqWithResponseCallback

void sendIqWithResponseCallback(IQ iqRequest,
                              PacketListener callback,
                              ExceptionCallback exceptionCallback)
                                throws SmackException.NotConnectedException

Send a IQ stanza and invoke callback if there is a result of IQ.Type.result with that result IQ. If there is an error response exceptionCallback will be invoked, if not null, with the received error as XMPPException.XMPPErrorException. If there is no response after the connections default reply timeout, then exceptionCallback will be invoked with a SmackException.NoResponseException.

Parameters:

iqRequest - the IQ stanza to send (required)

callback - the callback invoked if there is result response (required)

exceptionCallback - the callback invoked if there is an Exception optional

Throws:

SmackException.NotConnectedException

sendIqWithResponseCallback

void sendIqWithResponseCallback(IQ iqRequest,
                              PacketListener callback,
                              ExceptionCallback exceptionCallback,
                              long timeout)
                                throws SmackException.NotConnectedException

Send a IQ stanza and invoke callback if there is a result of IQ.Type.result with that result IQ. If there is an error response exceptionCallback will be invoked, if not null, with the received error as XMPPException.XMPPErrorException. If there is no response after timeout, then exceptionCallback will be invoked with a SmackException.NoResponseException.

Parameters:

iqRequest - the IQ stanza to send (required)

callback - the callback invoked if there is result response (required)

exceptionCallback - the callback invoked if there is an Exception optional

timeout - the timeout in milliseconds to wait for a response

Throws:

SmackException.NotConnectedException

getLastStanzaReceived

long getLastStanzaReceived()

Returns the timestamp in milliseconds when the last stanza was received.

Returns:

the timestamp in milliseconds