Configuring Connection Time-Outs and Retries in the PubSub+ JCSMP API

You can configure the connection time-outs and the number of retries for client applications to connect to event brokers. You can achieve this with channel properties for the PubSub+ JCSMP API. For information on how to set these properties, see:

For an example of how these session properties work in relation to one another when a list of potential hosts are provided for client connection attempts, see Sample Connect Retry Scenario and for more information on listing multiple hosts, see Host.

The default values for connection time-outs, retries, and retry wait times differ among the different APIs. To check the defaults, see the reference documentation for the different PubSub+ Messaging APIs.

Connection Time-Out

The connection time-out property is the maximum amount of time (in milliseconds) allowed for a Session to establish an initial connection to an event broker.

When a host list is used, the amount of time set for the Connection Time-Out property is applied to each connection attempt to a host. So, for example, if four host entries are listed, a worst-case scenario would be that an application would have to wait for the connection time-out to occur for each host entry, times the number of connect attempts, before receiving a notice of an established connection or a connection failure. This wait time is also extended by the Reconnect Retry Wait time that occurs after each unsuccessful attempt to connect to a host.

A connection attempt can terminate quicker if a failure is detected by the socket layer.

Considerations when using the PubSub+ JCSMP API

When using JCSMP, the following considerations also apply:

  • If the operating system used by the client application uses a maximum TCP connect timeout value that is less than the API connect timeout value (ConnectTimeoutInMillis), the operating system’s maximum TCP connect timeout will determine when the connection attempt will timeout.
  • If a client can't authenticate with the event broker within the amount of time configured for the read timeout (readTimeoutInMillis) property, the Session will be disconnected. If this occurs, you can increase the read timeout value.

  • When publishing large JMS messages (90MB or more), the processing time may take longer than the default read timeout period of 10s. You can change the read timeout value by using the following command:

    setReadTimeoutInMillis
public void setReadTimeoutInMillis(int readTimeoutInMillis)

    Take a look at the JCSMP reference guide for more information.

To set a connection time-out value, use JCSMPChannelProperties.setConnectTimeoutInMillis(...).

Connect Retries

The Connect Retries property sets the number of times to retry to establish an initial connection for a Session to a host event broker.

The valid range for the Connect Retries property is –1 or greater. A value of –1 means retry forever; a value of 0 means no automatic connection retries (that is, try once and give up).

If a host list is used, the API attempts to establish a connection to the first listed event broker. If that attempt fails, the API waits for the amount of time set for the Reconnect Retry Wait property before attempting another connection to either the same host. (The value of Connect Retries Per Host property sets the number times to attempt to connect to one host before moving to the next listed host.) The API attempts to connect to the host entries sequentially in the order they are listed.

If the Connect Retries property is greater than 0, the API can retry a connection attempt at the beginning of the host list if no connection could be established to any of the entries in the list. Each time the API works through the host list without establishing a connection is considered a connect retry. For example, for a Connect Retries value of 2, the API could possibly work through all of the listed hosts without connecting to them three times: one time through for the initial connect attempt, and then two times through for each connect retry. Each connect retry begins with the first host listed.

The connect retries value refers to the total number of connection attempts, including the initial connection attempt. For example, setting the connect retries value to 3 in JCSMP results in a maximum of 3 connection attempts: the initial attempt and two retries.

To set the number of connect retries, use JCSMPChannelProperties.setConnectRetries(...)

Reconnect Retries

The Reconnect Retries property sets the number of times to try to reconnect to a host after a connected Session goes down.

The valid range is greater than or equal to –1. A value of –1 means retry forever; a value of 0 means no automatic reconnection attempts.

If a host list is used, this property sets the number of times the API will traverse the host list in an attempt to reconnect to one of the hosts in the list. That is, if the API cannot connect to the first event broker on the list (that is, the preferred event broker), it attempts to connect to the next listed event broker, and so on. The API attempts to connect to each host for the number of times set for the Connect Retries Per Host property before attempting to connect to the next host.

After each unsuccessful connection attempt, the API waits for the amount of time set for the Reconnect Retry Wait property to expire before attempting to connect to the same host, the next listed host, or, after all of the listed hosts have been attempted, to the first host on the list again.

Multiple reconnects should be specified when the Session is working with a host for which event broker redundancy has been enabled (that is, the IP address listed as a host is used by a pair of redundant event brokers). Disabling reconnect retries could affect activity switches that might occur when active/active redundancy is used and could cause service disruptions. For example, in a failover scenario, if no reconnect retries are enabled, a connection attempt cannot be made to the redundant event broker.

Solace recommends that you set the Reconnect Retries value to the maximum number of attempts that you are willing to try before moving to an alternative error handling approach. In this case you may have encountered an issue that cannot be resolved by reconnecting the session to the host, and further consideration is required. For example, investigating an issue with the event broker.

An automatic reconnect frequency limit is used to prevent a client from reconnecting more than ten times (default) within four seconds. If the event broker permits the replacement of duplicate client connections during authentication, when multiple clients with the same client user name are used, they could enter a cycle where one client connects and then is disconnected when another client connects. If these clients have a non-zero Reconnect Retries value, each time one disconnected client successfully reconnects, it disconnects another connected client. The automatic reconnect frequency limit ensures that this client connect/reconnect cycle does not occur indefinitely.

For information on how to enable the replacement of duplicate client connections during authentication, see Configuring the Connection Behavior for Duplicate Clients .

To set the number of reconnect retries, use JCSMPChannelProperties.setReconnectRetries(...).

Reconnect Retry Wait

The Reconnect Retry Wait property sets the time to wait (in milliseconds) after an unsuccessful attempt to reconnect to the same host that the client was connected to. After this time expires, another reconnect attempt can be made. The valid range for the Reconnect Retry Wait property is 1 or greater.

To set the reconnect retry wait times, use JCSMPChannelProperties.setReconnectRetryWaitInMillis(...).

If the API works through all of the entries in the host list without establishing a connection, and a connect retry is permitted because the Connect Retry property is greater than 0, the API waits for the amount of time set for the Reconnect Retry Wait property before retrying to connect to the first host in the host list.

Connect Retries Per Host

When using a host list, the Connect Retries Per Host property sets how many times to try to connect or reconnect the Session to one host before moving to the next host in the list.

A value of 0 means make a single connection or reconnection attempt (that is, 0 retries). A value of –1 means attempt an infinite number of connect or reconnect retries (in this case, the API only tries to connect or reconnect to first host listed).

If a connect or reconnect attempt to a host is not successful, the API must wait for the amount of time set for the Reconnect Retry Wait property, before making another connect or reconnect attempt.

Application disconnection and Guaranteed messages

If a client application gets disconnected, the API will attempt to reconnect to the event broker it was connected to, and if that fails it will attempt to reconnect to the next listed host, and so on. If the application had published Guaranteed messages prior to being reconnected to a new host, the new host will not have the required Guaranteed messaging publisher state to agree with the API on which messages were last received / acknowledged. Therefore, the API will reset the publisher flow state, renumber and resend any unacknowledged messages.

If the new host was configured as a Replication mate of the original host, resending messages may create duplicates because the original messages may have been successfully delivered to the mate even though from the API’s perspective they were unacknowledged. In this case, it is up to the receiving application to resolve this duplication in an appropriate manner.
For API versions prior to 7.1.2, if a reconnect to a different host occurred after publishing Guaranteed messages, the API would close the newly created session and raise a session event—the application was responsible for reconnecting and resending any unacknowledged published messages. To use this legacy behavior, you must change the reconnect fail action channel or session property to the appropriate non-default value. For more information, see PubSub+ Messaging APIs.

To set the connect retries per host, use JCSMPChannelProperties.setConnectRetriesPerHost(...)

Sample Connect Retry Scenario

The figure below shows how the Connect Try and Retry properties can affect a client’s connection attempt behavior when a host list is used. For demonstration purposes, this example shows the worst case scenario where all potential connection attempts are unsuccessful.

The Connect Retries property behaves differently according to which messaging API is used. See Connect Retries for more information.

Connection Attempt Behavior When Using a Host List

Each time the API works through all of the entries in the host list without establishing a connection is considered a Connect Try or Retry. So, if a connection to one of the listed hosts isn't established during the initial Connect Try, a Connect Retry value of 2 means that API can work through the host list two more times (again, each listed host can be attempted up to two times for each Connect Retry). Each Connect Retry begins with the first host and works through the entries in the order in which they are listed.

Therefore, in the worst case scenario, the API could possibly work through the host list three times without making a connection to a host (one time through for the initial Connect Try, and then two times through for the Connect Retries), and because the Connect Retry Per Host value of 2 causes each host to be attempted twice, a maximum of 32 connection attempts can be made.