INT-3468 MQTT Async Client

JIRA: https://jira.spring.io/browse/INT-3468

Provide an option to not block when sending and emit
events for sends and delivery confirmations.

Also use the async client for the inbound adapter; while
it doesn't make any performance difference, it does
allow us to timeout the disconnect, which we have seen
to cause hangs on the CI servers.

INT-3468 Polishing - Use Events; Add Docs

INT-3468 Doc Polishing

INT-3468 More Polishing - PR Comments

- Only emit delivered event if async
- Add clientId and a new instance counter to events

INT-3468 Polishing

- Pull client instance up to the abstract class and remove references to the Paho implementation from the events
- Improve tests to include a second client

INT-3468 Fix Test Case

Incorrect classname meant the default location for the application
context config was not found on case-sensitive file systems.

Also, don't auto-start the adapters in the context, in case
the broker is not running.

INT-3468: Polishing

INT-3468 Fix Package Tangle; Add 'async-events'

Add an option (default false) to emit events when async is true.

src/reference/docbook/mqtt.xml

@@ -9,7 +9,7 @@
 			Spring Integration provides inbound and outbound channel adapters supporting the
 			MQ Telemetry Transport (MQTT) protocol. The current implementation uses the
 			<ulink url="http://www.eclipse.org/paho/">Eclipse Paho MQTT Client</ulink>
-			library. 
+			library.
 		</para>
 		<para>
 			Configuration of both adapters is achieved using the
@@ -44,7 +44,8 @@
 		<programlisting><![CDATA[<int-mqtt:message-driven-channel-adapter id="oneTopicAdapter"
 	client-id="foo"]]> <co id="mqtt-i-01"/><![CDATA[
 	url="tcp://localhost:1883"]]> <co id="mqtt-i-02"/><![CDATA[
-	topics="bar"]]> <co id="mqtt-i-03"/><![CDATA[
+	topics="bar,baz"]]> <co id="mqtt-i-03"/><![CDATA[
+	qos="1,2"]]> <co id="mqtt-i-03a"/><![CDATA[
 	converter="myConverter"]]> <co id="mqtt-i-04"/><![CDATA[
 	client-factory="clientFactory"]]> <co id="mqtt-i-05"/><![CDATA[
 	send-timeout="123"]]> <co id="mqtt-i-06"/><![CDATA[
@@ -68,6 +69,10 @@
 			<callout arearefs="mqtt-i-03">
 				A comma delimited list of topics from which this adapter will receive messages.
 			</callout>
+			<callout arearefs="mqtt-i-03a">
+				A comma delimited list of QoS values. Can be a single value that is applied to all
+				topics, or a value for each topic (in which case the lists must the same length).
+			</callout>
 			<callout arearefs="mqtt-i-04">
 				An <interfacename>MqttMessageConverter</interfacename> (optional). The default
 				<classname>DefaultPahoMessageConverter</classname> produces a message with a <code>String</code>
@@ -103,6 +108,11 @@
 			is wrapped in a <code>ConsumerEndpoint</code>. For convenience, it
 			can be configured using the namespace.
 		</para>
+		<para>
+			Starting with <emphasis>version 4.1</emphasis>, the adapter supports asynchronous sends, avoiding
+			blocking until the delivery is confirmed; application events can be emitted to enable applications
+			to confirm delivery if desired.
+		</para>
 		<para>
 			Attributes:
 		</para>
@@ -114,6 +124,8 @@
 	default-qos="1"]]> <co id="mqtt-o-05"/><![CDATA[
 	default-retained="true"]]> <co id="mqtt-o-06"/><![CDATA[
 	default-topic="bar"]]> <co id="mqtt-o-07"/><![CDATA[
+	async="false"]]> <co id="mqtt-o-08"/><![CDATA[
+	async-events="false"]]> <co id="mqtt-o-09"/><![CDATA[
 	channel="target" />]]></programlisting>
 		<calloutlist>
 			<callout arearefs="mqtt-o-01">
@@ -132,7 +144,7 @@
 			</callout>
 			<callout arearefs="mqtt-o-03">
 				An <interfacename>MqttMessageConverter</interfacename> (optional). The default
-				<classname>DefaultPahoMessageConverter</classname> 
+				<classname>DefaultPahoMessageConverter</classname>
 				recognizes the following headers:
 				<itemizedlist>
 					<listitem><code>mqtt_topic</code> - the topic to which the message will be sent</listitem>
@@ -154,6 +166,25 @@
 			<callout arearefs="mqtt-o-07">
 				The default topic to which the message will be sent (used if no <code>mqtt_topic</code> header is found).
 			</callout>
+			<callout arearefs="mqtt-o-08">
+				When <code>true</code>, the caller will not block waiting for delivery confirmation when a message is
+				sent.
+				Default:false (the send blocks until delivery is confirmed).
+			</callout>
+			<callout arearefs="mqtt-o-09">
+				When <code>async</code> and <code>async-events</code> are both <code>true</code>, an
+				<classname>MqttMessageSentEvent</classname> is emitted, containing the message, the
+				topic, the <code>messageId</code> generated by the client library, the <code>clientId</code>
+				and the <code>clientInstance</code> (incremented each time the client is connected).
+				When the delivery is confirmed by the client library, an
+				<classname>MqttMessageDeliveredEvent</classname> is emitted, containing the the <code>messageId</code>,
+				<code>clientId</code> and the <code>clientInstance</code>, enabling
+				delivery to be correlated with the send. These events can be received by any
+				<interfacename>ApplicationListener</interfacename>, or by an event inbound channel adapter. Note that
+				it is possible that the <classname>MqttMessageDeliveredEvent</classname> might be received before
+				the <classname>MqttMessageSentEvent</classname>.
+				Default: <code>false</code>.
+			</callout>
 		</calloutlist>
 	</section>
 

src/reference/docbook/whats-new.xml

@@ -54,13 +54,21 @@
 				See <xref linkend="http-namespace"/> for more information.
 			</para>
 		</section>
-		<section id="4.1-mqtt-cluster">
+		<section id="4.1-mqtt">
 			<title>MQTT Adapter Changes</title>
 			<para>
 				The MQTT channel adapters can now be configured to connect to multiple servers,
 				for example, to support High Availability (HA).
 				See <xref linkend="mqtt"/> for more information.
 			</para>
+			<para>
+				The MQTT message-driven channel adapter now supports specifying the QoS setting for each
+				subscription. See <xref linkend="mqtt"/> for more information.
+			</para>
+			<para>
+				The MQTT outbound channel adapter now supports asynchronous sends, avoiding blocking
+				until delivery is confirmed. See <xref linkend="mqtt"/> for more information.
+			</para>
 		</section>
 	</section>
 </chapter>