JSDoc: Interface: MQTTCoolSession

Encapsulation of a session opened against MQTT.Cool, from which to create MqttClient objects used to communicate with MQTT brokers.

An instance of MQTTCoolSession, which is created by invoking the openSession function, manages an MQTT.Cool connection to handle the bidirectional communications between all MqttClient instances it can create and the target MQTT.Cool server, in order to support end-to-end communications with an MQTT broker.

Method Summary

close: Disconnects from MQTT.Cool by closing the underlying MQTT.Cool connection.
createClient: Creates a new MqttClient instance, specifying how to address the MQTT broker to connect to, as well as the modalities by which the physical MQTT connection has to be set up and managed on the server side.

Method Detail

close()

Disconnects from MQTT.Cool by closing the underlying MQTT.Cool connection.

The disconnection also causes all MqttClient objects created from this instance to be closed and notified through the MqttClient#onConnectionLost callback.

createClient(brokerReference, clientIdopt, nullable) → {MqttClient}

Creates a new MqttClient instance, specifying how to address the MQTT broker to connect to, as well as the modalities by which the physical MQTT connection has to be set up and managed on the server side.

The returned MqttClient is configured to address the target MQTT broker on the basis of the provided brokerReference parameter. The following two different approaches are available (see the MQTT.Cool Getting Started Guide for more in-depth information):

Static Lookup, activated when brokerReference is a connection_alias corresponding to a static configuration already provided in the mqtt_master_connector_conf.xml file. Upon invoking the MqttClient#connect method on the MqttClient instance, the MQTT.Cool server will resolve the supplied alias by looking up the target configuration and will connect to the specified broker using all the other relative connection settings.
As an example, in the case the mqtt_master_connector_conf.xml file is populated with the following entries:
1. "local_server" => "mqtt://localhost:1883"
2. "remote_server" => "mqtt://<remote_host>:2883"
an invocation like:
```
mqttCoolSession.createClient("local_server");
```
will create an MqttClient instance enabled to establish a connection with an MQTT broker listening on tcp port 1883 of the same machine of MQTT.Cool.
Similarly:
```
mqttCoolSession.createClient("remote_server");
```
will make an MqttClient ready to connect to an MQTT broker listening on tcp port 2883 of <remote_host> address.
Dynamic Lookup, triggered when brokerReference is an explicit URI. Upon calling the MqttClient#connect method, the MQTT.Cool server will bypass any provided static configurations and will try to connect to the MQTT broker running on the host at the supplied address.
As an example, the following invocation:
```
mqttCoolSession.createClient("tcp://test.mosquitto.org:1883")
```
will trigger an MQTT connection to the publicly accessible instance of the "Mosquitto" broker.

The optional clientId parameter identifies the client to the target MQTT broker, as per the MQTT Protocol Specifications, namely:

For an MqttClient instance for which a valid clientId value is provided, the MQTT.Cool server will set up a dedicated connection.
An MqttClient instance for which the clientId is not specified will be logically joined to a shared connection.

See the documentation of the MqttClient interface for more details on how dedicated and shared connections are managed by the MQTT.Cool server.

Parameters:

Name Type Argument Description

Name	Type	Argument	Description
`brokerReference`	string		The reference of the MQTT broker with which MQTT.Cool has to establish a new connection. As detailed above, the lookup type to be used to identify and contact the MQTT broker is determined by the format, which can be: In the case of `Static Lookup`, a generic string valid with respect to the Regular Expression: `/^[A-Za-z0-9_-]+$/`. In the case of `Dynamic Lookup`, a URI in one of the following forms: `"tcp://<mqtt_broker_address>:<mqtt_broker_port>"` `"mqtt://<mqtt_broker_address>:<mqtt_broker_port>"` `"mqtts://<mqtt_broker_address>:<mqtt_broker_port>"` `"ssl://<mqtt_broker_address>:<mqtt_broker_port>"`
`clientId`	string	<optional> <nullable>	The client identifier to be used to identify the newly created client to the MQTT broker. If a non-empty string is provided, it has to be `UTF-8` encodable. In this case, a dedicated connection will be set up. Empty string and `null` are equivalent to a non-provided value. In this case, a shared connection will be set up.

brokerReference

string

The reference of the MQTT broker with which MQTT.Cool has to establish a new connection.

As detailed above, the lookup type to be used to identify and contact the MQTT broker is determined by the format, which can be:

In the case of Static Lookup, a generic string valid with respect to the Regular Expression: /^[A-Za-z0-9_-]+$/.
In the case of Dynamic Lookup, a URI in one of the following forms:
- "tcp://<mqtt_broker_address>:<mqtt_broker_port>"
- "mqtt://<mqtt_broker_address>:<mqtt_broker_port>"
- "mqtts://<mqtt_broker_address>:<mqtt_broker_port>"
- "ssl://<mqtt_broker_address>:<mqtt_broker_port>"

clientId

string

The client identifier to be used to identify the newly created client to the MQTT broker.

If a non-empty string is provided, it has to be UTF-8 encodable. In this case, a dedicated connection will be set up.

Empty string and null are equivalent to a non-provided value. In this case, a shared connection will be set up.

Throws:

If the provided arguments are invalid.
Type Error

Returns:

An object implementing the MqttClient interface, already configured to establish a connection to the target MQTT broker.

Type: MqttClient