Package org.jivesoftware.smackx.ping

Class PingManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.ping.PingManager

public final class PingManager
extends 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

Modifier and Type	Method	Description
static PingManager	getInstanceFor(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(Jid jid)	Query the specified entity to see if it supports the Ping protocol (XEP-0199).
boolean	ping(Jid jid)	Same as calling ping(Jid, long) with the defaultpacket reply timeout.
boolean	ping(Jid jid, long pingTimeout)	Pings the given jid.
SmackFuture<java.lang.Boolean,java.lang.Exception>	pingAsync(Jid jid)
SmackFuture<java.lang.Boolean,java.lang.Exception>	pingAsync(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(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 SmackFuture<java.lang.Boolean,java.lang.Exception> pingAsync(Jid jid)

pingAsync

public SmackFuture<java.lang.Boolean,java.lang.Exception> pingAsync(Jid jid,
                                                                          long pongTimeout)

ping

public boolean ping(Jid jid,
                    long pingTimeout)
             throws SmackException.NotConnectedException,
                    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:

SmackException.NoResponseException - if there was no response from the jid.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

ping

public boolean ping(Jid jid)
             throws SmackException.NotConnectedException,
                    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:

SmackException.NotConnectedException - if the XMPP connection is not connected.

SmackException.NoResponseException - if there was no response from the jid.

java.lang.InterruptedException - if the calling thread was interrupted.

isPingSupported

public boolean isPingSupported(Jid jid)
                        throws SmackException.NoResponseException,
                               XMPPException.XMPPErrorException,
                               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:

XMPPException.XMPPErrorException - An XMPP related error occurred during the request

SmackException.NoResponseException - if there was no response from the jid.

SmackException.NotConnectedException - if the XMPP connection is not connected.

java.lang.InterruptedException - if the calling thread was interrupted.

pingMyServer

public boolean pingMyServer()
                     throws 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:

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 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:

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 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:

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.