Monitoring Connection State

The AMPS client interface provides the ability to set one or more connection state listeners. A connection state listener is a callback that is invoked when the AMPS client detects a change to the connection state.

A connection state listener may be called from the client receive thread. An application should not submit commands to AMPS from a connection state listener, or the application risks creating a deadlock for commands that wait for acknowledgement from the server.

The AMPS client provides the following state values for a connection state listener:

State	Indicates
Connected	The client has established a connection to AMPS. If you are using a Client, this is delivered when connect() is successful. If you are using an HAClient, this state indicates that the connect part of the connect and logon process has completed. An HAClient using the default disconnect handler will attempt to log on immediately after delivering this state. Most applications that use Client will attempt to log on immediately after the call to connect() returns. An application should not submit commands to AMPS from the connection state listener while the client is in this state unless the application knows that the state has been delivered from a Client and that the Client does not call logon().
LoggedOn	The client has successfully logged on to AMPS. If you are using a Client, this is delivered when logon() is successful. If you are using an HAClient, this state indicates that the logon part of the connect and logon process has completed. This state is delivered after the client is logged on, but before recovery of client state is complete. Recovery will continue after delivering this state: the application should not submit commands to AMPS from the connection state listener while the client is in this state if further recovery will take place.
HeartbeatInitiated	The client has successfully started heartbeat monitoring with AMPS. This state is delivered if the application has enabled heartbeating on the client. This state is delivered before recovery of the client state is complete. Recovery may continue after this state is delivered. The application should not submit commands to AMPS from the connection state listener until the client is completely recovered.
PublishReplayed	Delivered when a client has completed replay of the publish store when recovering after connecting to AMPS. This state is delivered when the client has a PublishStore configured. If the client has a subscription manager set, (which is the default for an HAClient), the application should not submit commands from the connection state listener until the Resubscribed state is received.
Resubscribed	Delivered when a client has re-entered subscriptions when recovering after connecting to AMPS. This state is delivered when the client has a subscription manager set (which is the default for an HAClient). This is the final recovery step. An application can submit commands to AMPS from the connection state listener after receiving this state.
Disconnected	The client is not connected. For an HAClient, this means that the client will attempt to reconnect to AMPS. For a Client, this means that the client will invoke the disconnect handler, if one is specified.
Shutdown	The client is shut down. For an HAClient, this means that the client will no longer attempt to reconnect to AMPS. This state is delivered when close() is called on the client or when a server chooser tells the HAClient to stop reconnecting to AMPS.

The enumeration provided for the connection state listener also includes a value of UNKNOWN, for use as a default or to represent additional states in a custom Client implementation. The 60East implementations of the client do not deliver this state.

The following table shows examples of the set of states that will be delivered during connection, in order, depending on what features of the client are set. Notice that, for an instance of the Client class, this table assumes that the application calls both connect() and logon(). For an HAClient, this table assumes that the HAClient is using the default DisconnectHandler for the HAClient.

Configuration	States
subscription manager publish store	Connected LoggedOn PublishReplayed Resubscribed
subscription manager publish store heartbeat set	Connected LoggedOn HeartbeatInitiated PublishReplayed Resubscribed
subscription manager	Connected LoggedOn Resubscribed
subscription manager heartbeat set	Connected LoggedOn HeartbeatInitiated Resubscribed
(default Client configuration)	Connected LoggedOn