org.eclipse.paho.mqttv5.client.MqttCallback Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2009, 2018 IBM Corp.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v2.0
* and Eclipse Distribution License v1.0 which accompany this distribution.
*
* The Eclipse Public License is available at
* https://www.eclipse.org/legal/epl-2.0
* and the Eclipse Distribution License is available at
* https://www.eclipse.org/org/documents/edl-v10.php
*
* Contributors:
* Dave Locke - initial API and implementation and/or initial documentation
* James Sutton - MQTT V5 implementation
*/
package org.eclipse.paho.mqttv5.client;
import org.eclipse.paho.mqttv5.common.MqttException;
import org.eclipse.paho.mqttv5.common.MqttMessage;
import org.eclipse.paho.mqttv5.common.packet.MqttProperties;
/**
* Enables an application to be notified when asynchronous events related to the
* client occur. Classes implementing this interface can be registered on both
* types of client: {@link IMqttClient#setCallback(MqttCallback)} and
* {@link IMqttAsyncClient#setCallback(MqttCallback)}
*/
public interface MqttCallback {
/**
* This method is called when the server gracefully disconnects from the client
* by sending a disconnect packet, or when the TCP connection is lost due to a
* network issue or if the client encounters an error.
*
* @param disconnectResponse
* a {@link MqttDisconnectResponse} containing relevant properties
* related to the cause of the disconnection.
*/
void disconnected(MqttDisconnectResponse disconnectResponse);
/**
* This method is called when an exception is thrown within the MQTT client. The
* reasons for this may vary, from malformed packets, to protocol errors or even
* bugs within the MQTT client itself. This callback surfaces those errors to
* the application so that it may decide how best to deal with them.
*
* For example, The MQTT server may have sent a publish message with an invalid
* topic alias, the MQTTv5 specification suggests that the client should
* disconnect from the broker with the appropriate return code, however this is
* completely up to the application itself.
*
* @param exception
* - The exception thrown causing the error.
*/
void mqttErrorOccurred(MqttException exception);
/**
* This method is called when a message arrives from the server.
*
*
* This method is invoked synchronously by the MQTT client. An acknowledgment is
* not sent back to the server until this method returns cleanly.
*
*
* If an implementation of this method throws an Exception, then
* the client will be shut down. When the client is next re-connected, any QoS 1
* or 2 messages will be redelivered by the server.
*
*
* Any additional messages which arrive while an implementation of this method
* is running, will build up in memory, and will then back up on the network.
*
*
* If an application needs to persist data, then it should ensure the data is
* persisted prior to returning from this method, as after returning from this
* method, the message is considered to have been delivered, and will not be
* reproducible.
*
*
* It is possible to send a new message within an implementation of this
* callback (for example, a response to this message), but the implementation
* must not disconnect the client, as it will be impossible to send an
* acknowledgment for the message being processed, and a deadlock will occur.
*
*
* @param topic
* name of the topic on the message was published to
* @param message
* the actual message.
* @throws Exception
* if a terminal error has occurred, and the client should be shut
* down.
*/
void messageArrived(String topic, MqttMessage message) throws Exception;
/**
* Called when delivery for a message has been completed, and all
* acknowledgments have been received. For QoS 0 messages it is called once the
* message has been handed to the network for delivery. For QoS 1 it is called
* when PUBACK is received and for QoS 2 when PUBCOMP is received. The token
* will be the same token as that returned when the message was published.
*
* @param token
* the delivery token associated with the message.
*/
void deliveryComplete(IMqttToken token);
/**
* Called when the connection to the server is completed successfully.
*
* @param reconnect
* If true, the connection was the result of automatic reconnect.
* @param serverURI
* The server URI that the connection was made to.
*/
void connectComplete(boolean reconnect, String serverURI);
/**
* Called when an AUTH packet is received by the client.
*
* @param reasonCode
* The Reason code, can be Success (0), Continue authentication (24)
* or Re-authenticate (25).
* @param properties
* The {@link MqttProperties} to be sent, containing the
* Authentication Method, Authentication Data and any required User
* Defined Properties.
*/
void authPacketArrived(int reasonCode, MqttProperties properties);
}