# Last Will and Testament

## Overview

Last Will and Testament (LWT) is a powerful feature in MQTT that allows clients to specify a message that will be automatically published by the broker on their behalf, if or when an unexpected disconnection occurs. 

It provides a reliable means of communication and ensures that clients can gracefully handle disconnections without leaving topics in an inconsistent state. This feature is particularly valuable when clients must notify others of their unavailability or convey important information upon an unexpected disconnection, reference [HiveMQ](https://www.hivemq.com/blog/mqtt-essentials-part-9-last-will-and-testament/). 

Joule supports a consumer LWT handler feature by providing a dedicated DSL attribute, and `lwt handler`.  

### **Example**

In this example, the `lwt handler` feature is configured for the MQTT consumer.

It specifies that a MQTT publisher disconnects unexpectedly, a message will be sent to the topic `sensors/groundfloor/+/status` to notify subscribers of the disconnection.

The custom handler will be called when a message has been received on the LWT topic. 

{% tabs %}
{% tab title="DLS" %}
This snippet configures the client to process all ground floor room sensors, using the topic wildcard, LWT messages using the SensorOfflineHandler custom class.

```yaml
mqttConsumer:
  ...

  lwt handler:
    topic: sensors/groundfloor/+/status
    handler: com.fractalworks.streams.example.SensorOfflineHandler
    properties:
      message: "Ground floor sensor status: {}"
    qos: 1
```

{% endtab %}

{% tab title="SensorOfflineHandler" %}
Simple implementation of a `MQTTLastWillTestamentHandler` interface which uses passed in properties that provide a custom log message using the `MqttMessage` as a parameter.

```java
public class SensorOfflineHandler implements MQTTLastWillTestamentHandler {

    private final Logger logger = LoggerFactory.getLogger(SensorOfflineHandler.class.getName());

    public SensorOfflineHandler() {
        // REQUIRED
    }

    @Override
    public void onMessage(String topic, MqttMessage mqttMessage) {
        if(properties != null && properties.containsKey("message")) {
            logger.info(properties.getProperty("message"), mqttMessage);            
        } else {
            logger.info("Received MQTT LWT message {}", mqttMessage);
        }
    }

    @Override
    public void setProperties(Properties properties) {
        this.properties = properties;
    }
}
```

{% endtab %}
{% endtabs %}

### **Handler** attributes schema

These attributes provide the configuration parameters to receive and process LWT disconnection notifications.

<table><thead><tr><th width="140">Attribute</th><th width="405">Description</th><th width="126">Data Type</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td>topic</td><td>Topic LWT messages are received on</td><td>String</td><td>true</td></tr><tr><td>handler</td><td>Custom handler which processes the LWT message. This is a fully qualified class string i.e. <code>com.fractalworks.streams.example.SensorOfflineHandler</code></td><td>String</td><td>true</td></tr><tr><td>properties</td><td>Set of properties required by the handler</td><td><p>Long</p><p>Default: 5 seconds</p></td><td>false</td></tr><tr><td>qos</td><td>Quality of service</td><td><p>Integer</p><p>Default: 1</p></td><td>false</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fractalworks.io/joule/components/connectors/sources/mqtt/last-will-and-testament.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.