org.jivesoftware.smack

Interface XMPPConnection

All Known Implementing Classes:

AbstractXMPPConnection

public interface XMPPConnection

The XMPPConnection interface provides an interface for connections to an 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 an XMPP server a simple usage of this API might look like the following:

 // Create a connection to the igniterealtime.org XMPP server.
 XMPPTCPConnection 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("jdoe@igniterealtime.org", 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();
 

Note that the XMPPConnection interface does intentionally not declare any methods that manipulate the connection state, e.g. connect(), disconnect(). You should use the most specific connection type, e.g. XMPPTCPConnection as declared type and use the XMPPConnection interface when you don't need to manipulate the connection state.

XMPPConnections can be reused between connections. This means that an Connection may be connected, disconnected and then connected again. Listeners of the XMPPConnection 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	addAsyncPacketListener(PacketListener packetListener, PacketFilter packetFilter) Registers an asynchronous packet listener with this connection.
void	addConnectionListener(ConnectionListener connectionListener) Adds a connection listener to this connection that will be notified when the connection closes or fails.
void	addOneTimeSyncCallback(PacketListener callback, PacketFilter packetFilter) Add a callback that is called exactly once and synchronously with the incoming stanza that matches the given packet filter.
void	addPacketInterceptor(PacketListener packetInterceptor, PacketFilter packetFilter) Registers a packet interceptor with this connection.
void	addPacketListener(PacketListener packetListener, PacketFilter packetFilter) Deprecated. use addAsyncPacketListener(PacketListener, PacketFilter) or addSyncPacketListener(PacketListener, PacketFilter).
void	addPacketSendingListener(PacketListener packetListener, PacketFilter packetFilter) Registers a packet listener with this connection.
void	addSyncPacketListener(PacketListener packetListener, PacketFilter packetFilter) Registers a synchronous packet listener with this connection.
PacketCollector	createPacketCollector(PacketCollector.Configuration configuration) Create a new packet collector with the given packet collector configuration.
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, Stanza packet) Creates a new packet collector for this connection.
int	getConnectionCounter() Get the connection counter of this XMPPConnection instance.
<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.
java.lang.String	getServiceName() Returns the name of the service provided by the XMPP server for this connection.
java.lang.String	getStreamId() Returns the stream ID for this connection, which is the value set by the server when opening an XMPP stream.
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	isSecureConnection() Returns true if the connection to the server has successfully negotiated encryption.
boolean	isUsingCompression() Returns true if network traffic is being compressed.
IQRequestHandler	registerIQRequestHandler(IQRequestHandler iqRequestHandler) Register an IQ request handler with this connection.
boolean	removeAsyncPacketListener(PacketListener packetListener) Removes an asynchronous packet listener for received packets from this connection.
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) Deprecated. use removeAsyncPacketListener(PacketListener) or removeSyncPacketListener(PacketListener).
void	removePacketSendingListener(PacketListener packetListener) Removes a packet listener for sending packets from this connection.
boolean	removeSyncPacketListener(PacketListener packetListener) Removes a packet listener for received 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(Stanza packet) Sends the specified packet to the server.
void	sendStanzaWithResponseCallback(Stanza stanza, PacketFilter replyFilter, PacketListener callback) Send a stanza and wait asynchronously for a response by using replyFilter.
void	sendStanzaWithResponseCallback(Stanza stanza, PacketFilter replyFilter, PacketListener callback, ExceptionCallback exceptionCallback) Send a stanza and wait asynchronously for a response by using replyFilter.
void	sendStanzaWithResponseCallback(Stanza 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.
IQRequestHandler	unregisterIQRequestHandler(IQRequestHandler iqRequestHandler) Convenience method for unregisterIQRequestHandler(String, String, org.jivesoftware.smack.packet.IQ.Type).
IQRequestHandler	unregisterIQRequestHandler(java.lang.String element, java.lang.String namespace, IQ.Type type) Unregister an IQ request handler with this connection.

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.

getStreamId

java.lang.String getStreamId()

Returns the stream ID for this connection, which is the value set by the server when opening an XMPP stream. 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.

See Also:

RFC 6120 § 4.7.3. id

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(Stanza 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

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,
                                           Stanza 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, Stanza) 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.

createPacketCollector

PacketCollector createPacketCollector(PacketCollector.Configuration configuration)

Create a new packet collector with the given packet collector configuration.

Please make sure to cancel the collector when it is no longer required. See also createPacketCollector(PacketFilter).

Parameters:

configuration - the packet collector configuration.

Returns:

a new packet collector.

Since:

4.1

removePacketCollector

void removePacketCollector(PacketCollector collector)

Remove a packet collector of this connection.

Parameters:

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

addPacketListener

@Deprecated
void addPacketListener(PacketListener packetListener,
                                PacketFilter packetFilter)

Deprecated. use addAsyncPacketListener(PacketListener, PacketFilter) or addSyncPacketListener(PacketListener, PacketFilter).

Registers a packet listener with this connection.

This method has been deprecated. It is important to differentiate between using an asynchronous packet listener (preferred where possible) and a synchronous packet lister. Refer addAsyncPacketListener(PacketListener, PacketFilter) and addSyncPacketListener(PacketListener, PacketFilter) for more information.

Parameters:

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

packetFilter - the packet filter to use.

removePacketListener

@Deprecated
boolean removePacketListener(PacketListener packetListener)

Deprecated. use removeAsyncPacketListener(PacketListener) or removeSyncPacketListener(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

addSyncPacketListener

void addSyncPacketListener(PacketListener packetListener,
                         PacketFilter packetFilter)

Registers a synchronous 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.

Important: This packet listeners will be called in the same single thread that processes all incoming stanzas. Only use this kind of packet filter if it does not perform any XMPP activity that waits for a response. Consider using addAsyncPacketListener(PacketListener, PacketFilter) when possible, i.e. when the invocation order doesn't have to be the same as the order of the arriving packets. If the order of the arriving packets, consider using a PacketCollector when possible.

Parameters:

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

packetFilter - the packet filter to use.

Since:

4.1

See Also:

addPacketInterceptor(PacketListener, PacketFilter)

removeSyncPacketListener

boolean removeSyncPacketListener(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

Since:

4.1

addAsyncPacketListener

void addAsyncPacketListener(PacketListener packetListener,
                          PacketFilter packetFilter)

Registers an asynchronous 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.

Unlike addAsyncPacketListener(PacketListener, PacketFilter) packet listeners added with this method will be invoked asynchronously in their own thread. Use this method if the order of the packet listeners must not depend on the order how the stanzas where received.

Parameters:

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

packetFilter - the packet filter to use.

Since:

4.1

See Also:

addPacketInterceptor(PacketListener, PacketFilter)

removeAsyncPacketListener

boolean removeAsyncPacketListener(PacketListener packetListener)

Removes an asynchronous packet listener for received packets from this connection.

Parameters:

packetListener - the packet listener to remove.

Returns:

true if the packet listener was removed

Since:

4.1

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 addAsyncPacketListener(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

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(Stanza 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(Stanza 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(Stanza 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

addOneTimeSyncCallback

void addOneTimeSyncCallback(PacketListener callback,
                          PacketFilter packetFilter)

Add a callback that is called exactly once and synchronously with the incoming stanza that matches the given packet filter.

Parameters:

callback - the callback invoked once the packet filter matches a stanza.

packetFilter - the filter to match stanzas or null to match all.

registerIQRequestHandler

IQRequestHandler registerIQRequestHandler(IQRequestHandler iqRequestHandler)

Register an IQ request handler with this connection.

IQ request handler process incoming IQ requests, i.e. incoming IQ stanzas of type 'get' or 'set', and return a result.

Parameters:

iqRequestHandler - the IQ request handler to register.

Returns:

the previously registered IQ request handler or null.

unregisterIQRequestHandler

IQRequestHandler unregisterIQRequestHandler(IQRequestHandler iqRequestHandler)

Convenience method for unregisterIQRequestHandler(String, String, org.jivesoftware.smack.packet.IQ.Type).

Parameters:

iqRequestHandler -

Returns:

the previously registered IQ request handler or null.

unregisterIQRequestHandler

IQRequestHandler unregisterIQRequestHandler(java.lang.String element,
                                          java.lang.String namespace,
                                          IQ.Type type)

Unregister an IQ request handler with this connection.

Parameters:

element - the IQ element the IQ request handler is responsible for.

namespace - the IQ namespace the IQ request handler is responsible for.

type - the IQ type the IQ request handler is responsible for.

Returns:

the previously registered IQ request handler or null.

getLastStanzaReceived

long getLastStanzaReceived()

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

Returns:

the timestamp in milliseconds