 |
The Xentara MQTT client v2.0
User Manual
|
|
The Xentara MQTT client v2.0
User Manual
|
Birth and will messages are used to inform subscribers of the lifetime of a Xentara session. This is important to ensure that subscribers not use stale data. A subscriber can subscribe to the will and/or birth messages, and can invalidate any Xentara data once Xentara is no longer connected to the broker.
There are several different strategies that can be used to notify subscribers of Xentara lifetime events. These strategies are described below.
If any of the client’s topic elements are configured to use retained messages, it is strongly recommended that you implement the state-based lifetime strategy described in this chapter. Otherwise, it will be impossible for consumers to determine whether the retained messages are still valid, or if they are out of date because the Xentara MQTT client is no longer connected to the broker. This may cause consumers to operate on stale data, which is undesirable.
If you are only using a single topic with retained messages, then you can alternatively use an empty will message to discard any stale messages, as described below.
In a state-based lifetime strategy, the Xentara MQTT client defines a state topic that contains the state of the client connection. The payload of this topic will contain some data, usually a Boolean flag, that denotes whether the client is alive or not. Consumers can then subscribe to that topic, and be notified whenever the client connects or disconnects.
In order to implement this strategy, you must define a birth and a will message that are both published to the state topic. Both the birth and the will message must be retained, so that new consumers will be sent the correct state when they subscribe.
It is important that the birth and will messages use the same topic, so that the will message will overwrite the birth message, and vice versa.
The birth and will payloads should have the same format and structure. The birth payload should contain some indication that the client is alive, and the will payload should include some indication that the client is dead. Usually, this will be done by including a JSON Boolean value in the payload, which will be true in the birth payload, and false in the will payload. The birth and will payloads could look like this, for example:
Birth Payload:
{"alive":true}
Will Payload:
{"alive":false}
You can also include some other information in the payload, like e.g. the connectionTime attribute of the client element. Since the will payload cannot contain any data point values or attribute values, any data point or attribute values in the birth payload must either be omitted from the will payload, or replaced with fixed values (e.g. null).
Birth and will payloads that include the connection time could look like this, for example:
Birth Payload:
{"alive":true,"connectionTime":"2024-03-22T07:14:22.324512300Z"}
Will Payload:
{"alive":false,"connectionTime":null}
Since the birth message is only published after all retained topics have been published, is is imperative that all retained topics are published in a timely manner after Xentara connects to the broker. This is most easily achieved by publishing all retained topics in response to the connected event of the client element.
When a state-based lifetime strategy is used, consumers should subscribe to the state topic, and consider all data invalid until a birth message has been received. The data will then remain valid until a will message is received.
Since the birth message is only published after all the retained topics have been correctly updated, the valid data for each topic is contained in the last message that was published on that topic before the birth message. To account for this, consumers can do one of two things:
Pseudo-Code for Option 1:
Pseudo-Code for Option 2:
A message-based lifetime strategy is only suitable if none of the client’s topic elements are configured to use retained messages. If any of the topics use retained messages, it is strongly recommended that you use a state-based lifetime strategy instead.
If you are only using a single topic with retained messages, you can alternatively use a will message to discard any stale messages, as described below.
In a message-based lifetime strategy, the birth and will messages are simply used as a notification mechanism to tell consumers when Xentara is coming on- and off line. Neither the birth nor the will message must be retained, so that new clients will receive the correct state when they subscribe.
In order to implement this strategy, you must define a will message that is published to a special will topic. Optionally, you can also define a birth message, published to a separate birth topic. Neither the will nor the birth message must be retained, as that would cause consumers to receive outdated will and birth messages when subscribing.
When a message-based lifetime strategy is used, consumers should subscribe to the will topic, and invalidate or discard all data when a will message is received.
Optionally, the consumer can also subscribe to the birth message to perform any actions necessary when the Xentara MQTT client comes back on line after an outage. Just remember that the birth message is not retained, so a newly subscribed consumer will not receive a birth message if Xentara is already connected to the broker.
Pseudo-Code:
If you only use a single, retained topic to publish all of the data related to the client, then you can use a will message to cause the broker to discard the any retained messages if the connection is closed or lost. This will prevent any stale retained messages from being sent to consumers that subscribe when Xentara is not connected to the broker.
This strategy is easiest to handle in consumers, but is restricted to a single topic, because the MQTT standard does not support multiple will messages for the same client. As a workaround for this, it is possible to use a separate client connection for each topic by defining multiple client elements that connect to the same broker. This will, however, result in multiple separate client connections with the broker, each with its own client ID, and each contributing a small network and resource overhead.
In order to cause the broker to discard a retained message when Xentara disconnects, simply define a will message with the desired topic and and empty payload. Once Xentara is disconnected, the broker will publish the empty will message, and discard any messages retained for the will topic, as required by chapter 3.3.1.3 RETAIN in the MQTT specification.
When this strategy is used, consumers need only subscribe to the normal retained topic. The consumer can then regard any non-empty message it receives as valid data, whether this message is received as a result of the subscription, or later during normal operation. When an empty message is received for the topic, the consumer must discard any data associated with the topic, until a valid message is once more received.
Pseudo-Code: