You can configure the session reconnection feature by configuring the connectors at
the Diffusion™ server to keep the client session in a disconnected
state for a period before closing the session.
When a client detects connection loss, it will automatically attempt to re-establish connection
to the server based on the reconnection settings.
Reconnection is enabled by default.
If reconnection is successful, the client session
can continue without loss of subscriptions, topic updates, and messages that were queued for it whilst disconnected.
If reconnection is disabled, or fails to re-establish a connection, the client application must create a new session,
and re-initialise subscriptions and other application state.
To enable clients to reconnect, connectors must be configured to keep client sessions
in the DISCONNECTED state for a period during which the client can reconnect. To do
this a reconnection timeout must be specified for the connector.
Specify a reconnection timeout, maximum queue depth, and recovery
buffer size by using the <reconnect>
element in the
- Reconnection timeout (keep-alive)
- How long a disconnected client's session remains available on the server
before being closed. By default, this is 300 seconds.
- Maximum queue depth (max-depth)
- Optional maximum limit on the number of messages to queue for a
disconnected client session. By default, this is the same as the queue
depth for a connected client session, which is defined by the queue
definitions in Connectors.xml and
- Recovery buffer size (recovery-buffer-size)
- The maximum number of sent messages to keep in a buffer. These messages
can then be recovered on reconnection.
Here is an example connector configuration:
Using the above example, a client can reconnect to the server through
this connector within 60 seconds of
becoming disconnected. While the client is disconnected, up to 1000 messages are
queued for it. These messages are delivered to the client when it reconnects. A
buffer of up to 64 sent messages are retained in the recovery buffer. When a client
reconnects, the Diffusion server
uses this buffer to re-send any
messages that the client has not received.
If a client signals that it wants to disconnect, the client state on the server is
removed when the client disconnects. However, in all other circumstances where the
client loses connection, the client goes into the DISCONNECTED state, where the
subscriptions are retained and messages are queued as normal for the amount of time
specified by the reconnection timeout of the connector.
If the server is configured to expect reconnecting clients, sessions that are
currently disconnected and might reconnect are excluded from the regular system pings
that the server sends to clients.
If the client then reconnects during the period that the session is in DISCONNECTED
state, the sending of messages to the client resumes from the point when the failure
Disabling session reconnection
Session reconnection is on by default. Disabling reconnection can be useful in some
circumstances where it is better for a session to fail quickly than for it to be kept alive
and await reconnection.
- For example, when you have a control client in the same data center
as the Diffusion server, enabling reconnection for the session between the control client and the server
can make it harder to diagnose connection problems.
- During development you may want to kill and recompile or reconfigure a client, then restart it. If
reconnection is enabled, the original session will not end when the original client is killed. This can lead to
problems like preventing the new client
from registering as an updater until the reconnection timeout expires.
You can either disable reconnection in the server configuration, or a client can specify that a session
should not use reconnection.
Message queue management
When a client session is in DISCONNECTED state, messages for the client continue queuing
for the client until the reconnection timeout expires or the client reconnects. This
puts an unusual load on the client queue and the facility exists to adjust the
maximum client queue depth for the period of disconnection.
This is done by specifying a queue depth which is greater than the normal
maximum queue depth. When disconnected, the queue can expand to the higher value.
After reconnection occurs and the queue starts to drain, once the queue size goes
down to a value of 80% of its previous limit, the maximum queue depth reverts to the
The queue depth has an effect only if has a value higher than
the normal maximum queue depth.