INT-3239 MQTT Final Polishing For Master Merge

* Final Polishing to move from extensions to master
* Commit history is retained from the extensions
* Docbook Chapter

JIRA: https://jira.springsource.org/browse/INT-3239

build.gradle

@@ -408,6 +408,14 @@ project('spring-integration-mongodb') {
 	}
 }
 
+project('spring-integration-mqtt') {
+	description = 'Spring Integration MQTT Support'
+	dependencies {
+		compile project(":spring-integration-core")
+		compile "org.eclipse.paho:mqtt-client:0.4.0"
+	}
+}
+
 project('spring-integration-redis') {
 	description = 'Spring Integration Redis Support'
 	dependencies {

settings.gradle

@@ -16,6 +16,7 @@ include 'spring-integration-jmx'
 include 'spring-integration-jpa'
 include 'spring-integration-mail'
 include 'spring-integration-mongodb'
+include 'spring-integration-mqtt'
 include 'spring-integration-redis'
 include 'spring-integration-rmi'
 include 'spring-integration-scripting'

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/config/xml/MqttMessageDrivenChannelAdapterParser.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,18 +15,19 @@
  */
 package org.springframework.integration.mqtt.config.xml;
 
+import org.w3c.dom.Element;
+
 import org.springframework.beans.factory.support.AbstractBeanDefinition;
 import org.springframework.beans.factory.support.BeanDefinitionBuilder;
 import org.springframework.beans.factory.xml.ParserContext;
 import org.springframework.integration.config.xml.AbstractChannelAdapterParser;
 import org.springframework.integration.mqtt.inbound.MqttPahoMessageDrivenChannelAdapter;
-import org.w3c.dom.Element;
 
 /**
  * The MqttAdapter Message Driven Channel adapter parser
  *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public class MqttMessageDrivenChannelAdapterParser extends AbstractChannelAdapterParser {

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/config/xml/MqttNamespaceHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,7 +21,7 @@ import org.springframework.integration.config.xml.AbstractIntegrationNamespaceHa
  * The namespace handler for the MqttAdapter namespace
  *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public class MqttNamespaceHandler extends AbstractIntegrationNamespaceHandler {
@@ -29,6 +29,7 @@ public class MqttNamespaceHandler extends AbstractIntegrationNamespaceHandler {
 	/* (non-Javadoc)
 	 * @see org.springframework.beans.factory.xml.NamespaceHandler#init()
 	 */
+	@Override
 	public void init() {
 		this.registerBeanDefinitionParser("message-driven-channel-adapter",  new MqttMessageDrivenChannelAdapterParser());
 		this.registerBeanDefinitionParser("outbound-channel-adapter", new MqttOutboundChannelAdapterParser());

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/config/xml/MqttOutboundChannelAdapterParser.java

@@ -1,5 +1,5 @@
 /*
-   * Copyright 2002-2013 the original author or authors.
+   * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,8 @@
  */
 package org.springframework.integration.mqtt.config.xml;
 
+import org.w3c.dom.Element;
+
 import org.springframework.beans.factory.support.AbstractBeanDefinition;
 import org.springframework.beans.factory.support.BeanDefinitionBuilder;
 import org.springframework.beans.factory.xml.ParserContext;
@@ -22,13 +24,12 @@ import org.springframework.integration.config.xml.AbstractOutboundChannelAdapter
 import org.springframework.integration.config.xml.IntegrationNamespaceUtils;
 import org.springframework.integration.mqtt.outbound.MqttPahoMessageHandler;
 import org.springframework.util.StringUtils;
-import org.w3c.dom.Element;
 
 /**
  * The parser for the MqttAdapter Outbound Channel Adapter.
  *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public class MqttOutboundChannelAdapterParser extends AbstractOutboundChannelAdapterParser {

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/config/xml/MqttParserUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,11 +15,12 @@
  */
 package org.springframework.integration.mqtt.config.xml;
 
+import org.w3c.dom.Element;
+
 import org.springframework.beans.factory.config.BeanDefinition;
 import org.springframework.beans.factory.support.BeanDefinitionBuilder;
 import org.springframework.integration.config.xml.IntegrationNamespaceUtils;
 import org.springframework.util.StringUtils;
-import org.w3c.dom.Element;
 
 /**
  * Contains various utility methods for parsing Mqtt Adapter
@@ -27,7 +28,7 @@ import org.w3c.dom.Element;
  * respective {@link BeanDefinition}s.
  *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public final class MqttParserUtils {

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/core/DefaultMqttPahoClientFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,9 +26,10 @@ import org.eclipse.paho.client.mqttv3.MqttException;
 
 /**
  * Creates a default {@link MqttClient} and a set of options as configured.
+ *
  * @author Gary Russell
  * @author Gunnar Hillert
- * @since 1.0
+ * @since 4.0
  *
  */
 public class DefaultMqttPahoClientFactory implements MqttPahoClientFactory {
@@ -81,6 +82,7 @@ public class DefaultMqttPahoClientFactory implements MqttPahoClientFactory {
 
 	/**
 	 * Will be used to set the "Last Will and Testament" (LWT) for the connection.
+	 * @param will The will.
 	 *
 	 * @see MqttConnectOptions
 	 */

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/core/MqttPahoClientFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,12 +21,25 @@ import org.eclipse.paho.client.mqttv3.MqttException;
 
 /**
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public interface MqttPahoClientFactory {
 
+	/**
+	 * Retrieve a client instance.
+	 *
+	 * @param url The URL.
+	 * @param clientId The client id.
+	 * @return The client instance.
+	 * @throws MqttException Any.
+	 */
 	MqttClient getClientInstance(String url, String clientId) throws MqttException;
 
+	/**
+	 * Retrieve the connection options.
+	 *
+	 * @return The options.
+	 */
 	MqttConnectOptions getConnectionOptions();
 }

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/inbound/AbstractMqttMessageDrivenChannelAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,8 +22,9 @@ import org.springframework.util.Assert;
 
 /**
  * Abstract class for MQTT Message-Driven Channel Adapters.
+ *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public abstract class AbstractMqttMessageDrivenChannelAdapter extends MessageProducerSupport {

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/inbound/MqttPahoMessageDrivenChannelAdapter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/outbound/AbstractMqttMessageHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,18 +19,19 @@ package org.springframework.integration.mqtt.outbound;
 import org.eclipse.paho.client.mqttv3.MqttMessage;
 
 import org.springframework.context.SmartLifecycle;
-import org.springframework.integration.MessageHandlingException;
 import org.springframework.integration.handler.AbstractMessageHandler;
 import org.springframework.integration.mqtt.support.DefaultPahoMessageConverter;
 import org.springframework.integration.mqtt.support.MqttHeaders;
 import org.springframework.integration.mqtt.support.MqttMessageConverter;
 import org.springframework.messaging.Message;
+import org.springframework.messaging.MessageHandlingException;
 import org.springframework.util.Assert;
 
 /**
  * Abstract class for MQTT outbound channel adapters.
+ *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public abstract class AbstractMqttMessageHandler extends AbstractMessageHandler implements SmartLifecycle {

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/outbound/MqttPahoMessageHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,8 +28,9 @@ import org.springframework.util.Assert;
 
 /**
  * Eclipse Paho implementation.
+ *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public class MqttPahoMessageHandler extends AbstractMqttMessageHandler

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/support/DefaultPahoMessageConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,9 +25,10 @@ import org.springframework.util.Assert;
 
 
 /**
- * Default implementation allowing most connection options to be configured.
+ * Default implementation for mapping to/from Messages.
+ *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public class DefaultPahoMessageConverter implements MqttMessageConverter {
@@ -38,6 +39,8 @@ public class DefaultPahoMessageConverter implements MqttMessageConverter {
 
 	private final Boolean defaultRetained;
 
+	private volatile boolean payloadAsBytes = false;
+
 	public DefaultPahoMessageConverter() {
 		this (0, false);
 	}
@@ -46,6 +49,15 @@ public class DefaultPahoMessageConverter implements MqttMessageConverter {
 		this(defaultQos, defaultRetain, "UTF-8");
 	}
 
+	/**
+	 * True if the converter should not convert the message payload to a String.
+	 *
+	 * @param payloadAsBytes The payloadAsBytes to set.
+	 */
+	protected final void setPayloadAsBytes(boolean payloadAsBytes) {
+		this.payloadAsBytes = payloadAsBytes;
+	}
+
 	public DefaultPahoMessageConverter(int defaultQos, boolean defaultRetained, String charset) {
 		this.defaultQos = defaultQos;
 		this.defaultRetained = defaultRetained;
@@ -59,9 +71,9 @@ public class DefaultPahoMessageConverter implements MqttMessageConverter {
 	}
 
 	@Override
-	public Message<String> toMessage(String topic, MqttMessage mqttMessage) {
+	public Message<?> toMessage(String topic, MqttMessage mqttMessage) {
 		try {
-			MessageBuilder<String> messageBuilder = MessageBuilder.withPayload(new String(mqttMessage.getPayload(), this.charset))
+			MessageBuilder<Object> messageBuilder = MessageBuilder.withPayload(mqttBytesToPayload(mqttMessage))
 					.setHeader(MqttHeaders.QOS, mqttMessage.getQos())
 					.setHeader(MqttHeaders.DUPLICATE, mqttMessage.isDuplicate())
 					.setHeader(MqttHeaders.RETAINED, mqttMessage.isRetained());
@@ -77,6 +89,42 @@ public class DefaultPahoMessageConverter implements MqttMessageConverter {
 
 	@Override
 	public MqttMessage fromMessage(Message<?> message, Class<?> targetClass) {
+		byte[] payloadBytes = messageToMqttBytes(message);
+		MqttMessage mqttMessage = new MqttMessage(payloadBytes);
+		Object header = message.getHeaders().get(MqttHeaders.RETAINED);
+		Assert.isTrue(header == null || header instanceof Boolean, MqttHeaders.RETAINED + " header must be Boolean");
+		mqttMessage.setRetained(header == null ? this.defaultRetained : (Boolean) header);
+		header = message.getHeaders().get(MqttHeaders.QOS);
+		Assert.isTrue(header == null || header instanceof Integer, MqttHeaders.QOS + " header must be Integer");
+		mqttMessage.setQos(header == null ? this.defaultQos : (Integer) header);
+		return mqttMessage;
+	}
+
+	/**
+	 * Subclasses can override this method to convert the byte[] to a payload.
+	 * The default implementation creates a String (default) or byte[].
+	 *
+	 * @param mqttMessage The inbound message.
+	 * @return The payload for the Spring integration message
+	 * @throws Exception Any.
+	 */
+	protected Object mqttBytesToPayload(MqttMessage mqttMessage) throws Exception {
+		if (this.payloadAsBytes) {
+			return mqttMessage.getPayload();
+		}
+		else {
+			return new String(mqttMessage.getPayload(), this.charset);
+		}
+	}
+
+	/**
+	 * Subclasses can override this method to convert the payload to a byte[].
+	 * The default implementation accepts a byte[] or String payload.
+	 *
+	 * @param payload The payload.
+	 * @return The byte[]
+	 */
+	protected byte[] messageToMqttBytes(Message<?> message) {
 		Object payload = message.getPayload();
 		Assert.isTrue(payload instanceof byte[] || payload instanceof String);
 		byte[] payloadBytes;
@@ -91,14 +139,7 @@ public class DefaultPahoMessageConverter implements MqttMessageConverter {
 		else {
 			payloadBytes = (byte[]) payload;
 		}
-		MqttMessage mqttMessage = new MqttMessage(payloadBytes);
-		Object header = message.getHeaders().get(MqttHeaders.RETAINED);
-		Assert.isTrue(header == null || header instanceof Boolean, MqttHeaders.RETAINED + " header must be Boolean");
-		mqttMessage.setRetained(header == null ? this.defaultRetained : (Boolean) header);
-		header = message.getHeaders().get(MqttHeaders.QOS);
-		Assert.isTrue(header == null || header instanceof Integer, MqttHeaders.QOS + " header must be Integer");
-		mqttMessage.setQos(header == null ? this.defaultQos : (Integer) header);
-		return mqttMessage;
+		return payloadBytes;
 	}
 
 }

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/support/MqttHeaders.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,7 +18,8 @@ package org.springframework.integration.mqtt.support;
 /**
  * Spring Integration headers.
  * @author Gary Russell
- * @since 3.0
+ *
+ * @since 4.0
  *
  */
 public class MqttHeaders {

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/support/MqttMessageConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,11 +23,19 @@ import org.springframework.messaging.converter.MessageConverter;
 /**
  * Extension of {@link MessageConverter} allowing the topic to be added as
  * a header.
+ *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public interface MqttMessageConverter extends MessageConverter {
 
-	Message<String> toMessage(String topic, MqttMessage mqttMessage);
+	/**
+	 * Convert to a Message.
+	 *
+	 * @param topic The topic.
+	 * @param mqttMessage The MQTT message.
+	 * @return The Message.
+	 */
+	Message<?> toMessage(String topic, MqttMessage mqttMessage);
 }

spring-integration-mqtt/src/main/java/org/springframework/integration/mqtt/support/MqttUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,12 +20,11 @@ package org.springframework.integration.mqtt.support;
  * Contains utility methods used by the MqttAdapter components.
  *
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public final class MqttUtils {
 
-	/** Prevent instantiation. */
 	private MqttUtils() {
 		throw new AssertionError();
 	}

spring-integration-mqtt/src/main/resources/META-INF/spring.schemas

@@ -1,2 +1,2 @@
-http\://www.springframework.org/schema/integration/mqtt/spring-integration-mqtt-1.0.xsd=org/springframework/integration/mqtt/config/xml/spring-integration-mqtt-1.0.xsd
-http\://www.springframework.org/schema/integration/mqtt/spring-integration-mqtt.xsd=org/springframework/integration/mqtt/config/xml/spring-integration-mqtt-1.0.xsd
+http\://www.springframework.org/schema/integration/mqtt/spring-integration-mqtt-4.0.xsd=org/springframework/integration/mqtt/config/xml/spring-integration-mqtt-4.0.xsd
+http\://www.springframework.org/schema/integration/mqtt/spring-integration-mqtt.xsd=org/springframework/integration/mqtt/config/xml/spring-integration-mqtt-4.0.xsd

spring-integration-mqtt/src/test/java/org/springframework/integration/mqtt/BackTobackAdapterTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -32,7 +32,7 @@ import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler;
 
 /**
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public class BackTobackAdapterTests {

spring-integration-mqtt/src/test/java/org/springframework/integration/mqtt/BrokerRunning.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -28,11 +28,12 @@ import org.eclipse.paho.client.mqttv3.MqttException;
 import org.junit.rules.TestWatcher;
 import org.junit.runner.Description;
 import org.junit.runners.model.Statement;
+
 import org.springframework.integration.mqtt.core.DefaultMqttPahoClientFactory;
 
 /**
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public class BrokerRunning extends TestWatcher {

spring-integration-mqtt/src/test/java/org/springframework/integration/mqtt/MqttAdapterTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -54,7 +54,7 @@ import org.springframework.scheduling.concurrent.ThreadPoolTaskScheduler;
 
 /**
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 public class MqttAdapterTests {

spring-integration-mqtt/src/test/java/org/springframework/integration/mqtt/config/xml/MqttMessageDrivenChannelAdapterParserTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -33,7 +33,7 @@ import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
 
 /**
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 @ContextConfiguration

spring-integration-mqtt/src/test/java/org/springframework/integration/mqtt/config/xml/MqttOutboundChannelAdapterParserTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2014 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -35,7 +35,7 @@ import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
 
 /**
  * @author Gary Russell
- * @since 1.0
+ * @since 4.0
  *
  */
 @ContextConfiguration

src/reference/docbook/index.xml

@@ -135,6 +135,7 @@
       <xi:include href="./jms.xml"/>
       <xi:include href="./mail.xml"/>
       <xi:include href="./mongodb.xml"/>
+      <xi:include href="./mqtt.xml"/>
       <xi:include href="./redis.xml"/>
       <xi:include href="./resource.xml"/>
       <xi:include href="./rmi.xml"/>

src/reference/docbook/mqtt.xml

@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="mqtt"
+		xmlns:xlink="http://www.w3.org/1999/xlink">
+	<title>MQTT Support</title>
+
+	<section id="mqtt-intro">
+		<title>Introduction</title>
+		<para>
+			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. 
+		</para>
+		<para>
+			Configuration of both adapters is achieved using the
+			<classname>DefaultMqttPahoClientFactory</classname>.
+			Refer to the Paho documentation for more information about configuration
+			options.
+		</para>
+	</section>
+
+	<section id="mqtt-inbound">
+		<title>Inbound (message-driven) Channel Adapter</title>
+		<para>
+			The inbound channel adapter is implemented by the
+			<classname>MqttPahoMessageDrivenChannelAdapter</classname>. For convenience, it
+			can be configured using the namespace. A minimal configuration might be:
+		</para>
+		<programlisting language="xml"><![CDATA[<bean id="clientFactory"
+		class="org.springframework.integration.mqtt.core.DefaultMqttPahoClientFactory">
+	<property name="userName" value="${mqtt.username}"/>
+	<property name="password" value="${mqtt.password}"/>
+</bean>
+
+<int-mqtt:message-driven-channel-adapter id="mqttInbound"
+	client-id="${mqtt.default.client.id}.src"
+	url="${mqtt.url}"
+	topics="sometopic"
+	client-factory="clientFactory"
+	channel="output"/>]]></programlisting>
+		<para>
+			Attributes:
+		</para>
+		<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[
+	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[
+	channel="out" />]]></programlisting>
+		<calloutlist>
+			<callout arearefs="mqtt-i-01">
+				The client id.
+			</callout>
+			<callout arearefs="mqtt-i-02">
+				The broker URL.
+			</callout>
+			<callout arearefs="mqtt-i-03">
+				A comma delimited list of topics from which this adapter will receive messages.
+			</callout>
+			<callout arearefs="mqtt-i-04">
+				An <interfacename>MqttMessageConverter</interfacename> (optional). The default
+				<classname>DefaultPahoMessageConverter</classname> produces a message with a <code>String</code>
+				payload (by default) with the following headers:
+				<itemizedlist>
+					<listitem><code>mqtt_topic</code> - the topic from which the message was received</listitem>
+					<listitem><code>mqtt_duplicate</code> - true if the message is a duplicate</listitem>
+					<listitem><code>mqtt_qos</code> - the quality of service</listitem>
+				</itemizedlist>
+				The <classname>DefaultPahoMessageConverter</classname> can be configured to return the raw
+				<code>byte[]</code> in the payload by declaring it as a &lt;bean/&gt; and setting the
+				<code>payloadAsBytes</code> property.
+			</callout>
+			<callout arearefs="mqtt-i-05">
+				The client factory.
+			</callout>
+			<callout arearefs="mqtt-i-06">
+				The send timeout - only applies if the channel might block (such as a bounded <code>QueueChannel</code>
+				that is currently full).
+			</callout>
+		</calloutlist>
+	</section>
+
+	<section id="mqtt-outbound">
+		<title>Outbound Channel Adapter</title>
+		<para>
+			The outbound channel adapter is implemented by the <classname>MqttPahoMessageHandler</classname> which
+			is wrapped in a <code>ConsumerEndpoint</code>. For convenience, it
+			can be configured using the namespace.
+		</para>
+		<para>
+			Attributes:
+		</para>
+		<programlisting><![CDATA[<int-mqtt:outbound-channel-adapter id="withConverter"
+	client-id="foo"]]> <co id="mqtt-o-01"/><![CDATA[
+	url="tcp://localhost:1883"]]> <co id="mqtt-o-02"/><![CDATA[
+	converter="myConverter"]]> <co id="mqtt-o-03"/><![CDATA[
+	client-factory="clientFactory"]]> <co id="mqtt-o-04"/><![CDATA[
+	default-qos="1"]]> <co id="mqtt-o-05"/><![CDATA[
+	default-retained="true"]]> <co id="mqtt-o-06"/><![CDATA[
+	default-topic="bar"]]> <co id="mqtt-i-07"/><![CDATA[
+	channel="target" />]]></programlisting>
+		<calloutlist>
+			<callout arearefs="mqtt-i-01">
+				The client id.
+			</callout>
+			<callout arearefs="mqtt-i-02">
+				The broker URL.
+			</callout>
+			<callout arearefs="mqtt-i-03">
+				An <interfacename>MqttMessageConverter</interfacename> (optional). The default
+				<classname>DefaultPahoMessageConverter</classname> 
+				recognizes the following headers:
+				<itemizedlist>
+					<listitem><code>mqtt_topic</code> - the topic to which the message will be sent</listitem>
+					<listitem><code>mqtt_retained</code> - true if the message is to be retained</listitem>
+					<listitem><code>mqtt_qos</code> - the quality of service</listitem>
+				</itemizedlist>
+			</callout>
+			<callout arearefs="mqtt-i-04">
+				The client factory.
+			</callout>
+			<callout arearefs="mqtt-i-05">
+				The default quality of service (used if no <code>mqtt_qos</code> header is found). Not allowed
+				if a custom <code>converter</code> is supplied.
+			</callout>
+			<callout arearefs="mqtt-i-06">
+				The default value of the retained flag (used if no <code>mqtt_retaind</code> header is found). Not allowed
+				if a custom <code>converter</code> is supplied.
+			</callout>
+			<callout arearefs="mqtt-i-07">
+				The default topic to which the message will be sent (used if no <code>mqtt_topic</code> header is found).
+			</callout>
+		</calloutlist>
+	</section>
+
+</chapter>

src/reference/docbook/whats-new.xml

@@ -9,6 +9,18 @@
 		in more details, please see the Issue Tracker tickets that
 		were resolved as part of the 4.0 development process.
 	</para>
+	<section id="4.0-new-components">
+		<title>New Components</title>
+		<section id="4.0-mqtt">
+			<title>MQTT Channel Adapters</title>
+			<para>
+				The MQTT channel adapters (previously available in the Spring Integration Extensions repository)
+				are now available as part of the normal Spring Integration distribution.
+				See <xref linkend="mqtt"/>
+			</para>
+		</section>
+	</section>
+
 	<section id="4.0-general">
 		<title>General Changes</title>
 		<para>