Configuring Connection Time-Outs and Retries

The channel properties (for the Java API) or Session properties (for the Java RTO, C, and .NET APIs) discussed in this section are used to configure a client’s behavior for connecting and reconnecting to Solace PubSub+ message brokers.

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. (For more information on listing multiple hosts, see Host.)

Note  
  • The default values for connection time-outs, retries, and retry wait times differ among the Solace APIs. To find the default value for one of the properties listed in this section, see the APIs & Protocols documentation for the appropriate API.
  • When using HA redundant message broker pairs, a fail-over from one message broker to its mate will typically occur in under 30 seconds, however, applications should attempt to reconnect for at least five minutes. To allow for a reconnect duration of five minutes for HA redundant message brokers, set the following session property values:
    • connect retries:1
    • reconnect retries: 5
    • reconnect retry wait: 3000 ms
    • connect retries per host: 20

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 a message 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.

Note  
  • A connection attempt can terminate quicker if a failure is detected by the socket layer.
  • When using the Java API, 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 cannot authenticate with the message 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.

To Set a Connection Time-Out Value

Language

Property

Java

JCSMPChannelProperties.setConnectTimeoutInMillis()

Java RTO

SessionHandle.PROPERTIES.CONNECT_TIMEOUT_MS

C

SOLCLIENT_SESSION_PROP_CONNECT_TIMEOUT_MS

.NET

SessionProperties.ConnectTimeoutInMsecs

JavaScript and Node.js

solace.SessionProperties.connectTimeoutInMsecs

Connect Retries

The Connect Retries property sets the number of times to retry to establish an initial connection for a Session to a host message 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 message 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.

Note  
  • For the Java API, 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 the Java API results in a maximum of three connection attempts: the initial attempt and two retries.
  • For the Java RTO, C, and .NET APIs, the connect retries value refers strictly to the total number of connection retries and does not include the initial connection attempt. For example, setting the connect retries value to three in the Java RTO, C, or .NET APIs results in a maximum of four connection attempts: the initial attempt and three retries.

To Set the Number of Connect Retries

Language

Property

Java

JCSMPChannelProperties.setConnectRetries(...)

Java RTO

SessionHandle.PROPERTIES.CONNECT_RETRIES

C

SOLCLIENT_SESSION_PROP_CONNECT_RETRIES

.NET

SessionProperties.ConnectRetries

JavaScript and Node.js

solace.SessionProperties.connectRetries

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 message broker on the list (that is, the preferred message broker), it attempts to connect to the next listed message 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 message broker redundancy has been enabled (that is, the IP address listed as a host is used by a pair of redundant message 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 fail-over scenario, if no reconnect retries are enabled, a connection attempt cannot be made to the redundant message 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 message broker.

Java API

An automatic reconnect frequency limit is used to prevent a client from reconnecting more than ten times (default) within four seconds. If the message 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 Duplicate Client Connect Behavior Configuration.

To Set the Number of Reconnect Retries

Language

Property

Java

JCSMPChannelProperties.setReconnectRetries(...)

Java RTO

SessionHandle.PROPERTIES.RECONNECT_RETRIES

C

SOLCLIENT_SESSION_PROP_RECONNECT_RETRIES

.NET

SessionProperties.ReconnectRetries

JavaScript and Node.js

solace.SessionPropertiess.reconnectRetries

Reconnect Retry Wait

The Reconnect Retry Wait property sets the amount of time (in milliseconds) to wait 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.

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

To Set the Reconnect Retry Wait Times

Language

Property

Java

JCSMPChannelProperties.setReconnectRetryWaitInMillis()

Java RTO

SessionHandle.PROPERTIES.RETRY_WAIT_MS

C

SOLCLIENT_SESSION_PROP_RECONNECT_RETRY_WAIT_MS

.NET

SessionProperties.
ReconnectRetriesWaitInMsecs

JavaScript and Node.js

solace.SessionProperties.reconnectRetryWaitInMsecs

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.

Notice  

If a client application gets disconnected, the API will attempt to reconnect to the message 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. Note that 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.
Note that 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 APIs & Protocols.

To Set the Connect Retries Per Host

Language

Property

Java

JCSMPChannelProperties.setConnectRetriesPerHost(...)

Java RTO

SessionHandle.PROPERTIES.CONNECT_RETRIES_
PER_HOST

C

SOLCLIENT_SESSION_PROP_CONNECT_RETRIES_PER_
HOST

.NET

SessionProperties.ConnectRetriesPerHost

JavaScript and Node.js

solace.SessionProperties.connectRetriesPerHost

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.

Note:  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 is not 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.