MQTT Cloud Connector

MQTT (Message Queue Telemetry Transport) is a lightweight publish-subscribe messaging protocol.

Versioning

The tags below are for the Cloud Connectors repository. You should use the one corresponding to the Jakarta version you require.

0.8.0

MQTT Connector using JakartaEE 8 and the javax namespace

MQTT-1.0.0

Azure Service Bus Connector using JakartaEE 10 and the jakarta namespace

Usage

If you have selected to use MQTT Connector 1.0.0, replace all occurunces of 0.8.0 with 1.0.0 for the following example.

In order to connect to a MQTT broker, the mqtt-rar-0.8.0.rar has to be deployed as shown in the Installing a connector section of the Cloud Connectors overview.

In order to make use of this connector in an application, the following Maven dependency is needed:

<dependency>
  <groupId>fish.payara.cloud.connectors.MQTT</groupId>
  <artifactId>mqtt-jca-api</artifactId>
  <version>0.8.0</version>
  <type>jar</type>
  <scope>provided</scope>
</dependency>

Note that this dependency have scope provided since the types within this dependency are globally available to every application deployed to Payara Micro after the mqtt-rar-0.8.0.rar was deployed.

Sending messages

Sending messages to a MQTT broker can be done via the JCA and an MQTT specific API. In order to start using this API to send messages, a resource has to be defined via the JCA API; a connection factory.

The connection factory has to be given a name, which can be any name that is valid for JNDI. The java:app namespace is typically recommended to be used. The type of the connection factory to be used for MQTT is fish.payara.cloud.connectors.MQTT.api.MQTTConnectionFactory, and we have to specify the resource adapter name which is here mqtt-rar-0.8.0.rar.

The following gives an example:

@ConnectionFactoryDefinition (
 name = "java:app/MQTT/factory",
 interfaceName = "fish.payara.cloud.connectors.MQTT.api.MQTTConnectionFactory",
 resourceAdapter = "mqtt-rar-0.8.0"
 properties = "cleanSession=true"
)

With the above shown definition in place the following code shows an example of sending a message:

@Singleton
@Startup
public class SendMQTTMessage {

 @Resource(lookup = "java:app/MQTT/factory")
 private MQTTConnectionFactory factory;

 @PostConstruct
 public void init() {
    try (MQTTConnection connection = factory.createConnection()) {
        connection.publish("test", "{\"test\": \"Hello World\"}".getBytes(), 0, false);
    }
    catch (Exception ex) {
    }
  }
}

Receiving messages

Messages can be received from an MQTT broker by creating an MDB (Message Driven Bean) that implements the fish.payara.cloud.connectors.MQTT.api.MQTTListener marker interface and has a single method annotated with @OnMQTTMessage and the method signature void method(String topic, MqttMessage message).

The following gives an example:

@MessageDriven(activationConfig = {
 @ActivationConfigProperty(propertyName = "topicFilter", propertyValue = "test")
})
public class ReceiveMQTTMessage implements MQTTListener {
   @OnMQTTMessage
   public void receiveMessage(String topic, MqttMessage message) {
       // Handle message
   }
}
Config Property Name Type Default Notes

serverURIs

String

tcp://localhost:1883

Server URIs for connection, comma separated

cleanSession

Boolean

false

Sets whether the client and server should remember state across reconnects

automaticReconnect

Boolean

true

Sets whether the client will automatically reconnect to the server if the connection is lost

filePersistance

Boolean

false

Whether the client should use file persistence for un-acknowledged messages

persistenceDirectory

String

.

Directory to use for file persistence

connectionTimeout

Integer

30

Sets the connection timeout value in seconds

maxInflight

Integer

10

Sets the maximum messages that can be sent without acknowledgements

keepAliveInterval

Integer

60

Sets the keep alive interval in seconds

userName

String

None

The username for the connection.

password

String

None

The password for the connection.

topicFilter

String

None

Topic Filter (For MDBs only)

qos

String

0

Quality of Service for the subscription (For MDBs only)