Class ReconnectPolicy

java.lang.Object
org.mqtt4j.hato.ReconnectPolicy
public final class ReconnectPolicy extends Object

Decides whether and when a client connects again after an established connection ends without a request to stop. The policy applies only while the application's connection request stands: MqttClient.disconnect() and MqttClient.close() withdraw it, and so does a handler failure that stops the client; see MqttSubscriber.

With exponential backoff, the delay before the first reconnection attempt is chosen uniformly at random between zero and initialDelay, and each further consecutive attempt doubles that bound up to maxDelay, without a limit on the number of attempts. A connection that stays established for a while resets the sequence; a successful CONNACK alone does not, so two clients that share a client identifier and keep taking over each other's connection slow down. Reconnecting stops when the broker's reason code, in a CONNACK refusal or an MQTT 5.0 DISCONNECT, means that the same connection would be refused again or that the client should keep away or use another server: an unsupported protocol version, an invalid client identifier, a ban, an unsupported authentication method, a session taken over by a client with the same identifier, an administrative action, a redirection, and the reason codes for malformed packets, protocol errors, invalid topics or payloads, and broker limits or features that the client exceeded (0x81, 0x82, 0x8F, 0x90, 0x93 to 0x95, 0x99 to 0x9B, 0x9E, 0xA1, and 0xA2). It also stops when the client's timer scheduler fails. Other refusals and failures are retried, including bad credentials, missing authorization, an unspecified error, and a reason code that this client does not know. ConnectionListener.onConnectFailed(Disconnection) reports each failed attempt, so an application that wants to stop on a particular cause can call MqttClient.disconnect().

Two of these classifications depend on how an application is run, and a policy can change them: withAdministrativeActionRetry() also reconnects after an administrative action, and withoutUnspecifiedErrorRetry() stops at an unspecified error. Only MQTT 5.0 brokers send these reason codes, so the two settings change nothing on MQTT 3.1.1 connections. Every other classification is fixed.

By default, the first failure of a connection request ends that request and fails its MqttClient.connect() future, because it usually reveals a configuration error at startup. withInitialRetry() retries that failure with the same backoff instead, unless its reason code stops reconnecting.

Instances are immutable values with equality.

  • Method Details

    • exponentialBackoff

      public static ReconnectPolicy exponentialBackoff(Duration initialDelay, Duration maxDelay)
      Reconnects with exponential backoff and full jitter, doubling the bound of the random delay from initialDelay up to maxDelay. Both must be positive, maxDelay must not be shorter than initialDelay, and neither may exceed 2147483647 milliseconds.
      Parameters:
      initialDelay - the first bound of the random delay
      maxDelay - the largest bound of the random delay
      Returns:
      the policy
      Throws:
      IllegalArgumentException - 
      if a delay is out of range

    • disabled

      public static ReconnectPolicy disabled()
      Never reconnects automatically. A connection that ends leaves the client disconnected until the application calls MqttClient.connect() again.
      Returns:
      the disabled policy

    • withInitialRetry

      public ReconnectPolicy withInitialRetry()
      Returns a policy that also retries a connection request's failures before its first successful connection, so its MqttClient.connect() future waits, possibly without limit, until a connection is established or the client gives the request up.
      Returns:
      a policy that also retries a connection request's failures before its first successful connection, so its MqttClient.connect() future waits, possibly without limit, until a connection is established or the client gives the request up
      Throws:
      IllegalStateException - 
      for [#disabled()], which never retries

    • withAdministrativeActionRetry

      public ReconnectPolicy withAdministrativeActionRetry()
      Returns a policy that also reconnects after an MQTT 5.0 broker ends the connection with DISCONNECT 0x98 (Administrative action), with the same backoff as after other failures. By default, the client stays disconnected after an administrative action, because an administrator ended the connection on purpose.
      Returns:
      a policy that also reconnects after an MQTT 5.0 broker ends the connection with DISCONNECT 0x98 (Administrative action), with the same backoff as after other failures
      Throws:
      IllegalStateException - 
      for [#disabled()], which never retries

    • withoutUnspecifiedErrorRetry

      public ReconnectPolicy withoutUnspecifiedErrorRetry()
      Returns a policy that stops reconnecting when an MQTT 5.0 broker refuses a connection or ends one with reason code 0x80 (Unspecified error), in CONNACK or DISCONNECT. By default, the client retries an unspecified error, because the reason code does not say whether its cause lasts.
      Returns:
      a policy that stops reconnecting when an MQTT 5.0 broker refuses a connection or ends one with reason code 0x80 (Unspecified error), in CONNACK or DISCONNECT
      Throws:
      IllegalStateException - 
      for [#disabled()], which never retries

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object