Package org.jivesoftware.smack

Interface XMPPConnection

All Known Implementing Classes:
AbstractXMPPConnection, ModularXmppClientToServerConnection, XMPPBOSHConnection, XMPPTCPConnection
public interface XMPPConnection
The XMPPConnection interface provides an interface for connections from a client to an XMPP server and implements shared methods which are used by the different types of connections (e.g. ModularXmppClientToServerConnection or XMPPTCPConnection). To create a connection to an XMPP server a simple usage of this API might look like the following: 

 // Create the configuration for this new connection
 XMPPTCPConnectionConfiguration.Builder configBuilder = XMPPTCPConnectionConfiguration.builder();
 configBuilder.setUsernameAndPassword("username", "password");
 configBuilder.setXmppDomain("jabber.org");

 AbstractXMPPConnection connection = new XMPPTCPConnection(configBuilder.build());
 connection.connect();
 connection.login();

 Message message = connection.getStanzaFactory().buildMessageStanza()
     .to("mark@example.org)
     .setBody("Hi, how are you?")
     .build();
 connection.sendStanza(message);

 connection.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-generic superclass connection type that is able to provide the methods you require. In most cases this should be AbstractXMPPConnection. And use or hand out instances of 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.

Processing Incoming Stanzas

Smack provides a flexible framework for processing incoming stanzas using two constructs:

Incoming Stanza Listeners

Most callbacks (listeners, handlers, …) than you can add to a connection come in three different variants:

Asynchronous callbacks are run decoupled from the connections main event loop. Hence, a callback triggered by stanza B may (appear to) invoked before a callback triggered by stanza A, even though stanza A arrived before B.

Synchronous callbacks are invoked concurrently, but it is ensured that the same callback is never run concurrently and that they are executed in order. That is, if both stanza A and B trigger the same callback, and A arrives before B, then the callback will be invoked with A first, and then B. Furthermore, those callbacks are not executed within the main loop. However it is still advisable that those callbacks do not block or only block briefly.

Other callbacks are run synchronous to the main event loop of a connection and are executed within the main loop. This means that if such a callback blocks, the main event loop also blocks, which can easily cause deadlocks. Therefore, you should avoid using those callbacks unless you know what you are doing.

Stanza Filters

Stanza filters allow you to define the predicates for which listeners or collectors should be invoked. For more information about stanza filters, see org.jivesoftware.smack.filter.

Provider Architecture

XMPP is an extensible protocol. Smack allows for this extensible with its provider architecture that allows to plug-in providers that are able to parse the various XML extension elements used for XMPP's extensibility. For more information see org.jivesoftware.smack.provider.

Debugging

See org.jivesoftware.smack.debugger for Smack's API to debug XMPP connections.

Modular Connection Architecture

Smack's new modular connection architecture will one day replace the monolithic architecture. Its main entry point ModularXmppClientToServerConnection has more information.

  • Method Details

    • getXMPPServiceDomain

      DomainBareJid getXMPPServiceDomain()
      Returns the XMPP Domain of the service provided by the XMPP server and used for this connection. After authenticating with the server the returned value may be different.
      Returns:
      the XMPP domain of this XMPP session.

    • getHost

      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

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

    • getLocalAddress

      InetAddress getLocalAddress()
      Returns the local address currently in use for this connection, or null if this is invalid for the type of underlying connection.
      Returns:
      the local address currently in use for this connection

    • getStreamId

      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:

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

    • getStanzaFactory

      StanzaFactory getStanzaFactory()

    • sendStanza

      void sendStanza(Stanza stanza) throws SmackException.NotConnectedException, InterruptedException
      Sends the specified stanza to the server.
      Parameters:
      stanza - the stanza to send.
      Throws:
      SmackException.NotConnectedException - if the connection is not connected.
      InterruptedException - if the calling thread was interrupted.

    • sendStanzaNonBlocking

      void sendStanzaNonBlocking(Stanza stanza) throws SmackException.NotConnectedException, SmackException.OutgoingQueueFullException
      Throws:
      SmackException.NotConnectedException
      SmackException.OutgoingQueueFullException

    • trySendStanza

      @Deprecated boolean trySendStanza(Stanza stanza) throws SmackException.NotConnectedException
      Deprecated.
      use sendStanzaNonBlocking(Stanza) instead.
      Try to send the given stanza. Returns true if the stanza was successfully put into the outgoing stanza queue, otherwise, if false is returned, the stanza could not be scheduled for sending (for example because the outgoing element queue is full). Note that this means that the stanza possibly was not put onto the wire, even if true is returned, it just has been successfully scheduled for sending.

      Note: Implementations are not required to provide that functionality. In that case this method is mapped to sendStanza(Stanza) and will possibly block until the stanza could be scheduled for sending.

      Parameters:
      stanza - the stanza to send.
      Returns:
      true if the stanza was successfully scheduled to be sent, false otherwise.
      Throws:
      SmackException.NotConnectedException - if the connection is not connected.
      Since:
      4.4.0

    • trySendStanza

      @Deprecated boolean trySendStanza(Stanza stanza, long timeout, TimeUnit unit) throws SmackException.NotConnectedException, InterruptedException
      Deprecated.
      use sendStanzaNonBlocking(Stanza) instead.
      Try to send the given stanza. Returns true if the stanza was successfully put into the outgoing stanza queue within the given timeout period, otherwise, if false is returned, the stanza could not be scheduled for sending (for example because the outgoing element queue is full). Note that this means that the stanza possibly was not put onto the wire, even if true is returned, it just has been successfully scheduled for sending.

      Note: Implementations are not required to provide that functionality. In that case this method is mapped to sendStanza(Stanza) and will possibly block until the stanza could be scheduled for sending.

      Parameters:
      stanza - the stanza to send.
      timeout - how long to wait before giving up, in units of unit.
      unit - a TimeUnit determining how to interpret the timeout parameter.
      Returns:
      true if the stanza was successfully scheduled to be sent, false otherwise.
      Throws:
      SmackException.NotConnectedException - if the connection is not connected.
      InterruptedException - if the calling thread was interrupted.
      Since:
      4.4.0

    • sendNonza

      void sendNonza(Nonza nonza) throws SmackException.NotConnectedException, InterruptedException
      Send a Nonza.

      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:
      nonza - the Nonza to send.
      Throws:
      SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.

    • sendNonzaNonBlocking

      void sendNonzaNonBlocking(Nonza stanza) throws SmackException.NotConnectedException, SmackException.OutgoingQueueFullException
      Throws:
      SmackException.NotConnectedException
      SmackException.OutgoingQueueFullException

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

    • sendIqRequestAndWaitForResponse

      <I extends IQ> I sendIqRequestAndWaitForResponse(IQ request) throws SmackException.NoResponseException, XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException
      Send an IQ request and wait for the response.
      Type Parameters:
      I - the type of the expected result IQ.
      Parameters:
      request - the IQ request
      Returns:
      an IQ with type 'result'
      Throws:
      SmackException.NoResponseException - if there was no response from the remote entity.
      XMPPException.XMPPErrorException - if there was an XMPP error returned.
      SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.
      Since:
      4.3

    • createStanzaCollectorAndSend

      StanzaCollector createStanzaCollectorAndSend(IQ request) throws SmackException.NotConnectedException, InterruptedException
      Creates a new stanza collector collecting IQ responses that are replies to the IQ request. Does also send the request IQ. The stanza filter for the collector is an IQReplyFilter, guaranteeing that stanza id and JID in the 'from' address have expected values.
      Parameters:
      request - the IQ request to filter responses from
      Returns:
      a new stanza collector.
      Throws:
      SmackException.NotConnectedException - if the XMPP connection is not connected.
      InterruptedException - if the calling thread was interrupted.

    • createStanzaCollectorAndSend

      StanzaCollector createStanzaCollectorAndSend(StanzaFilter stanzaFilter, Stanza stanza) throws SmackException.NotConnectedException, InterruptedException
      Creates a new stanza collector for this connection. A stanza filter determines which stanzas will be accumulated by the collector. A StanzaCollector is more suitable to use than a StanzaListener when you need to wait for a specific result.
      Parameters:
      stanzaFilter - the stanza filter to use.
      stanza - the stanza to send right after the collector got created
      Returns:
      a new stanza collector.
      Throws:
      InterruptedException - if the calling thread was interrupted.
      SmackException.NotConnectedException - if the XMPP connection is not connected.

    • createStanzaCollector

      StanzaCollector createStanzaCollector(StanzaFilter stanzaFilter)
      Creates a new stanza collector for this connection. A stanza filter determines which stanzas will be accumulated by the collector. A StanzaCollector is more suitable to use than a StanzaListener when you need to wait for a specific result.

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

      Parameters:
      stanzaFilter - the stanza filter to use.
      Returns:
      a new stanza collector.

    • createStanzaCollector

      StanzaCollector createStanzaCollector(StanzaCollector.Configuration configuration)
      Create a new stanza collector with the given stanza collector configuration.

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

      Parameters:
      configuration - the stanza collector configuration.
      Returns:
      a new stanza collector.
      Since:
      4.1

    • removeStanzaCollector

      void removeStanzaCollector(StanzaCollector collector)
      Remove a stanza collector of this connection.
      Parameters:
      collector - a stanza collectors which was created for this connection.

    • addStanzaListener

      ListenerHandle addStanzaListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
      Registers a stanza listener with this connection. The listener will be invoked when a (matching) incoming stanza is received. The stanza filter determines which stanzas will be delivered to the listener. It is guaranteed that the same listener will not be invoked concurrently and the order of invocation will reflect the order in which the stanzas have been received. If the same stanza listener is added again with a different filter, only the new filter will be used.
      Parameters:
      stanzaListener - the stanza listener to notify of new received stanzas.
      stanzaFilter - the stanza filter to use.
      Returns:
      a handle which can be used in try-with-resources statements.
      Since:
      4.4.0

    • removeStanzaListener

      boolean removeStanzaListener(StanzaListener stanzaListener)
      Removes a stanza listener for received stanzas from this connection.
      Parameters:
      stanzaListener - the stanza listener to remove.
      Returns:
      true if the stanza listener was removed.
      Since:
      4.4.0

    • addSyncStanzaListener

      ListenerHandle addSyncStanzaListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
      Registers a synchronous stanza listener with this connection. A stanza listener will be invoked only when an incoming stanza is received. A stanza filter determines which stanzas will be delivered to the listener. If the same stanza listener is added again with a different filter, only the new filter will be used.

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

      Parameters:
      stanzaListener - the stanza listener to notify of new received stanzas.
      stanzaFilter - the stanza filter to use.
      Returns:
      a handle which can be used in try-with-resources statements.
      Since:
      4.1

    • removeSyncStanzaListener

      boolean removeSyncStanzaListener(StanzaListener stanzaListener)
      Removes a stanza listener for received stanzas from this connection.
      Parameters:
      stanzaListener - the stanza listener to remove.
      Returns:
      true if the stanza listener was removed
      Since:
      4.1

    • addAsyncStanzaListener

      ListenerHandle addAsyncStanzaListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
      Registers an asynchronous stanza listener with this connection. A stanza listener will be invoked only when an incoming stanza is received. A stanza filter determines which stanzas will be delivered to the listener. If the same stanza listener is added again with a different filter, only the new filter will be used.

      Unlike addAsyncStanzaListener(StanzaListener, StanzaFilter) stanza listeners added with this method will be invoked asynchronously in their own thread. Use this method if the order of the stanza listeners must not depend on the order how the stanzas where received.

      Parameters:
      stanzaListener - the stanza listener to notify of new received stanzas.
      stanzaFilter - the stanza filter to use.
      Returns:
      a handle which can be used in try-with-resources statements.
      Since:
      4.1

    • removeAsyncStanzaListener

      boolean removeAsyncStanzaListener(StanzaListener stanzaListener)
      Removes an asynchronous stanza listener for received stanzas from this connection.
      Parameters:
      stanzaListener - the stanza listener to remove.
      Returns:
      true if the stanza listener was removed
      Since:
      4.1

    • addStanzaSendingListener

      void addStanzaSendingListener(StanzaListener stanzaListener, StanzaFilter stanzaFilter)
      Registers a stanza listener with this connection. The listener will be notified of every stanza that this connection sends. A stanza filter determines which stanzas will be delivered to the listener. Note that the thread that writes stanzas will be used to invoke the listeners. Therefore, each stanza listener should complete all operations quickly or use a different thread for processing.
      Parameters:
      stanzaListener - the stanza listener to notify of sent stanzas.
      stanzaFilter - the stanza filter to use.

    • removeStanzaSendingListener

      void removeStanzaSendingListener(StanzaListener stanzaListener)
      Removes a stanza listener for sending stanzas from this connection.
      Parameters:
      stanzaListener - the stanza listener to remove.

    • addMessageInterceptor

      void addMessageInterceptor(Consumer<MessageBuilder> messageInterceptor, Predicate<Message> messageFilter)
      Registers a stanza interceptor with this connection. The interceptor will be invoked every time a stanza is about to be sent by this connection. Interceptors may modify the stanza to be sent. A stanza filter determines which stanzas will be delivered to the interceptor.

      NOTE: For a similar functionality on incoming stanzas, see addAsyncStanzaListener(StanzaListener, StanzaFilter).

      Parameters:
      messageInterceptor - the stanza interceptor to notify of stanzas about to be sent.
      messageFilter - the stanza filter to use.

    • removeMessageInterceptor

      void removeMessageInterceptor(Consumer<MessageBuilder> messageInterceptor)
      Removes a message interceptor.
      Parameters:
      messageInterceptor - the message interceptor to remove.

    • addPresenceInterceptor

      void addPresenceInterceptor(Consumer<PresenceBuilder> presenceInterceptor, Predicate<Presence> presenceFilter)
      Registers a stanza interceptor with this connection. The interceptor will be invoked every time a stanza is about to be sent by this connection. Interceptors may modify the stanza to be sent. A stanza filter determines which stanzas will be delivered to the interceptor.

      NOTE: For a similar functionality on incoming stanzas, see addAsyncStanzaListener(StanzaListener, StanzaFilter).

      Parameters:
      presenceInterceptor - the stanza interceptor to notify of stanzas about to be sent.
      presenceFilter - the stanza filter to use.

    • removePresenceInterceptor

      void removePresenceInterceptor(Consumer<PresenceBuilder> presenceInterceptor)
      Removes a presence interceptor.
      Parameters:
      presenceInterceptor - the stanza interceptor to remove.

    • getReplyTimeout

      long getReplyTimeout()
      Returns the current value of the reply timeout in milliseconds for request for this XMPPConnection instance.
      Returns:
      the reply timeout in milliseconds

    • setReplyTimeout

      void setReplyTimeout(long timeout)
      Set the stanza 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 - for a reply 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 - TODO javadoc me please

    • getFromMode

      XMPPConnection.FromMode getFromMode()
      Get the currently active FromMode.
      Returns:
      the currently active XMPPConnection.FromMode

    • getFeature

      <F extends XmlElement> F getFeature(QName qname)
      Get the feature stanza extensions for a given stream feature of the server, or null if the server doesn't support that feature.
      Type Parameters:
      F - ExtensionElement type of the feature.
      Parameters:
      qname - the qualified name of the XML element of feature.
      Returns:
      a stanza extensions of the feature or null
      Since:
      4.4

    • getFeature

      default <F extends XmlElement> F getFeature(Class<F> featureClass)
      Get the feature stanza extensions for a given stream feature of the server, or null if the server doesn't support that feature.
      Type Parameters:
      F - ExtensionElement type of the feature.
      Parameters:
      featureClass - the class of the feature.
      Returns:
      a stanza extensions of the feature or null
      Since:
      4.4

    • hasFeature

      default boolean hasFeature(String element, String namespace)
      Return true if the server supports the given stream feature.
      Parameters:
      element - TODO javadoc me please
      namespace - TODO javadoc me please
      Returns:
      true if the server supports the stream feature.

    • hasFeature

      boolean hasFeature(QName qname)
      Return true if the server supports the given stream feature.
      Parameters:
      qname - the qualified name of the XML element of feature.
      Returns:
      true if the server supports the stream feature.

    • sendIqRequestAsync

      SmackFuture<IQ,Exception> sendIqRequestAsync(IQ request)
      Send an IQ request asynchronously. The connection's default reply timeout will be used.
      Parameters:
      request - the IQ request to send.
      Returns:
      a SmackFuture for the response.

    • sendIqRequestAsync

      SmackFuture<IQ,Exception> sendIqRequestAsync(IQ request, long timeout)
      Send an IQ request asynchronously.
      Parameters:
      request - the IQ request to send.
      timeout - the reply timeout in milliseconds.
      Returns:
      a SmackFuture for the response.

    • sendAsync

      <S extends Stanza> SmackFuture<S,Exception> sendAsync(S stanza, StanzaFilter replyFilter)
      Send a stanza asynchronously, waiting for exactly one response stanza using the given reply filter. The connection's default reply timeout will be used.
      Type Parameters:
      S - the type of the stanza to send.
      Parameters:
      stanza - the stanza to send.
      replyFilter - the filter used for the response stanza.
      Returns:
      a SmackFuture for the response.

    • sendAsync

      <S extends Stanza> SmackFuture<S,Exception> sendAsync(S stanza, StanzaFilter replyFilter, long timeout)
      Send a stanza asynchronously, waiting for exactly one response stanza using the given reply filter.
      Type Parameters:
      S - the type of the stanza to send.
      Parameters:
      stanza - the stanza to send.
      replyFilter - the filter used for the response stanza.
      timeout - the reply timeout in milliseconds.
      Returns:
      a SmackFuture for the response.

    • addOneTimeSyncCallback

      void addOneTimeSyncCallback(StanzaListener callback, StanzaFilter stanzaFilter)
      Add a callback that is called exactly once and synchronously with the incoming stanza that matches the given stanza filter.
      Parameters:
      callback - the callback invoked once the stanza filter matches a stanza.
      stanzaFilter - 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 - TODO javadoc me please
      Returns:
      the previously registered IQ request handler or null.

    • unregisterIQRequestHandler

      IQRequestHandler unregisterIQRequestHandler(String element, 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