Class PingManager


  • public final class PingManager
    extends org.jivesoftware.smack.Manager
    Implements the XMPP Ping as defined by XEP-0199. The XMPP Ping protocol allows one entity to ping any other entity by simply sending a ping to the appropriate JID. PingManger also periodically sends XMPP pings to the server to avoid NAT timeouts and to test the connection status.

    The default server ping interval is 30 minutes and can be modified with setDefaultPingInterval(int) and setPingInterval(int).

    See Also:
    XEP-0199:XMPP Ping
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static PingManager getInstanceFor​(org.jivesoftware.smack.XMPPConnection connection)
      Retrieves a PingManager for the specified XMPPConnection, creating one if it doesn't already exist.
      int getPingInterval()
      Get the current ping interval.
      boolean isPingSupported​(org.jxmpp.jid.Jid jid)
      Query the specified entity to see if it supports the Ping protocol (XEP-0199).
      boolean ping​(org.jxmpp.jid.Jid jid)
      Same as calling ping(Jid, long) with the defaultpacket reply timeout.
      boolean ping​(org.jxmpp.jid.Jid jid, long pingTimeout)
      Pings the given jid.
      org.jivesoftware.smack.SmackFuture<java.lang.Boolean,​java.lang.Exception> pingAsync​(org.jxmpp.jid.Jid jid)  
      org.jivesoftware.smack.SmackFuture<java.lang.Boolean,​java.lang.Exception> pingAsync​(org.jxmpp.jid.Jid jid, long pongTimeout)  
      boolean pingMyServer()
      Pings the server.
      boolean pingMyServer​(boolean notifyListeners)
      Pings the server.
      boolean pingMyServer​(boolean notifyListeners, long pingTimeout)
      Pings the server.
      void pingServerIfNecessary()
      Ping the server if deemed necessary because automatic server pings are enabled (setPingInterval(int)) and the ping interval has expired.
      void registerPingFailedListener​(PingFailedListener listener)
      Register a new PingFailedListener.
      static void setDefaultPingInterval​(int interval)
      Set the default ping interval which will be used for new connections.
      void setPingInterval​(int pingInterval)
      Set the interval in seconds between a automated server ping is send.
      void unregisterPingFailedListener​(PingFailedListener listener)
      Unregister a PingFailedListener.
      • Methods inherited from class org.jivesoftware.smack.Manager

        connection, getAuthenticatedConnectionOrThrow, schedule, schedule, scheduleBlocking
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • getInstanceFor

        public static PingManager getInstanceFor​(org.jivesoftware.smack.XMPPConnection connection)
        Retrieves a PingManager for the specified XMPPConnection, creating one if it doesn't already exist.
        Parameters:
        connection - TODO javadoc me please The connection the manager is attached to.
        Returns:
        The new or existing manager.
      • setDefaultPingInterval

        public static void setDefaultPingInterval​(int interval)
        Set the default ping interval which will be used for new connections.
        Parameters:
        interval - the interval in seconds
      • pingAsync

        public org.jivesoftware.smack.SmackFuture<java.lang.Boolean,​java.lang.Exception> pingAsync​(org.jxmpp.jid.Jid jid)
      • pingAsync

        public org.jivesoftware.smack.SmackFuture<java.lang.Boolean,​java.lang.Exception> pingAsync​(org.jxmpp.jid.Jid jid,
                                                                                                         long pongTimeout)
      • ping

        public boolean ping​(org.jxmpp.jid.Jid jid,
                            long pingTimeout)
                     throws org.jivesoftware.smack.SmackException.NotConnectedException,
                            org.jivesoftware.smack.SmackException.NoResponseException,
                            java.lang.InterruptedException
        Pings the given jid. This method will return false if an error occurs. The exception to this, is a server ping, which will always return true if the server is reachable, event if there is an error on the ping itself (i.e. ping not supported).

        Use isPingSupported(Jid) to determine if XMPP Ping is supported by the entity.

        Parameters:
        jid - The id of the entity the ping is being sent to
        pingTimeout - The time to wait for a reply in milliseconds
        Returns:
        true if a reply was received from the entity, false otherwise.
        Throws:
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the jid.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • ping

        public boolean ping​(org.jxmpp.jid.Jid jid)
                     throws org.jivesoftware.smack.SmackException.NotConnectedException,
                            org.jivesoftware.smack.SmackException.NoResponseException,
                            java.lang.InterruptedException
        Same as calling ping(Jid, long) with the defaultpacket reply timeout.
        Parameters:
        jid - The id of the entity the ping is being sent to
        Returns:
        true if a reply was received from the entity, false otherwise.
        Throws:
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the jid.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • isPingSupported

        public boolean isPingSupported​(org.jxmpp.jid.Jid jid)
                                throws org.jivesoftware.smack.SmackException.NoResponseException,
                                       org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                       org.jivesoftware.smack.SmackException.NotConnectedException,
                                       java.lang.InterruptedException
        Query the specified entity to see if it supports the Ping protocol (XEP-0199).
        Parameters:
        jid - The id of the entity the query is being sent to
        Returns:
        true if it supports ping, false otherwise.
        Throws:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - An XMPP related error occurred during the request
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the jid.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • pingMyServer

        public boolean pingMyServer()
                             throws org.jivesoftware.smack.SmackException.NotConnectedException,
                                    java.lang.InterruptedException
        Pings the server. This method will return true if the server is reachable. It is the equivalent of calling ping with the XMPP domain.

        Unlike the ping(Jid) case, this method will return true even if isPingSupported(Jid) is false.

        Returns:
        true if a reply was received from the server, false otherwise.
        Throws:
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • pingMyServer

        public boolean pingMyServer​(boolean notifyListeners)
                             throws org.jivesoftware.smack.SmackException.NotConnectedException,
                                    java.lang.InterruptedException
        Pings the server. This method will return true if the server is reachable. It is the equivalent of calling ping with the XMPP domain.

        Unlike the ping(Jid) case, this method will return true even if isPingSupported(Jid) is false.

        Parameters:
        notifyListeners - Notify the PingFailedListener in case of error if true
        Returns:
        true if the user's server could be pinged.
        Throws:
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • pingMyServer

        public boolean pingMyServer​(boolean notifyListeners,
                                    long pingTimeout)
                             throws org.jivesoftware.smack.SmackException.NotConnectedException,
                                    java.lang.InterruptedException
        Pings the server. This method will return true if the server is reachable. It is the equivalent of calling ping with the XMPP domain.

        Unlike the ping(Jid) case, this method will return true even if isPingSupported(Jid) is false.

        Parameters:
        notifyListeners - Notify the PingFailedListener in case of error if true
        pingTimeout - The time to wait for a reply in milliseconds
        Returns:
        true if the user's server could be pinged.
        Throws:
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • setPingInterval

        public void setPingInterval​(int pingInterval)
        Set the interval in seconds between a automated server ping is send. A negative value disables automatic server pings. All settings take effect immediately. If there is an active scheduled server ping it will be canceled and, if pingInterval is positive, a new one will be scheduled in pingInterval seconds.

        If the ping fails after 3 attempts waiting the connections reply timeout for an answer, then the ping failed listeners will be invoked.

        Parameters:
        pingInterval - the interval in seconds between the automated server pings
      • getPingInterval

        public int getPingInterval()
        Get the current ping interval.
        Returns:
        the interval between pings in seconds
      • registerPingFailedListener

        public void registerPingFailedListener​(PingFailedListener listener)
        Register a new PingFailedListener.
        Parameters:
        listener - the listener to invoke
      • unregisterPingFailedListener

        public void unregisterPingFailedListener​(PingFailedListener listener)
        Unregister a PingFailedListener.
        Parameters:
        listener - the listener to remove
      • pingServerIfNecessary

        public void pingServerIfNecessary()
        Ping the server if deemed necessary because automatic server pings are enabled (setPingInterval(int)) and the ping interval has expired.