camel git commit: Added camel-paho docs to Gitbook

[ac...@apache.org]

Repository: camel
Updated Branches:
  refs/heads/master e5c7f624f -> b941f3f5a


Added camel-paho docs to Gitbook


Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/b941f3f5
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/b941f3f5
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/b941f3f5

Branch: refs/heads/master
Commit: b941f3f5a55c7226ce2c58afa927edab8924cd40
Parents: e5c7f62
Author: Andrea Cosentino <an...@gmail.com>
Authored: Tue May 17 10:42:46 2016 +0200
Committer: Andrea Cosentino <an...@gmail.com>
Committed: Tue May 17 10:42:46 2016 +0200

----------------------------------------------------------------------
 components/camel-paho/src/main/docs/paho.adoc | 198 +++++++++++++++++++++
 docs/user-manual/en/SUMMARY.md                |   1 +
 2 files changed, 199 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/b941f3f5/components/camel-paho/src/main/docs/paho.adoc
----------------------------------------------------------------------
diff --git a/components/camel-paho/src/main/docs/paho.adoc b/components/camel-paho/src/main/docs/paho.adoc
new file mode 100644
index 0000000..51daab7
--- /dev/null
+++ b/components/camel-paho/src/main/docs/paho.adoc
@@ -0,0 +1,198 @@
+[[Paho-PahoComponent]]
+Paho Component
+~~~~~~~~~~~~~~
+
+INFO: Available as of Camel 2.16�
+
+Paho component provides connector for the MQTT messaging protocol using
+the https://eclipse.org/paho/[Eclipse Paho] library. Paho is one of the
+most popular MQTT libraries, so if you would like to integrate it with
+your Java project - Camel Paho connector is a way to go.
+
+[[Paho-URIformat]]
+URI format
+^^^^^^^^^^
+
+[source,java]
+------------------------
+paho:queueName[?options]
+------------------------
+
+For example the following snippet reads messages from the MQTT broker
+installed on the same host as the Camel router:
+
+[source,java]
+------------------------
+from("paho:some/queue").
+  to("mock:test");
+------------------------
+
+While the snippet below sends message to the MQTT broker:
+
+[source,java]
+-------------------------------
+from("direct:test").
+  to("paho:some/target/queue");
+-------------------------------
+
+You can append query options to the URI in the following
+format:�`?option=value&option=value&...`�. For example this is how
+to�read messages from the remote MQTT broker:�
+
+�
+
+[source,java]
+-------------------------------------------------------------
+from("paho:some/queue?brokerUrl=tcp://iot.eclipse.org:1883").
+  to("mock:test");
+-------------------------------------------------------------
+
+�
+
+[[Paho-Addingthecomponenttotheproject]]
+Adding the component to the project
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component:
+
+[source,xml]
+------------------------------------------------------------
+<dependency>
+    <groupId>org.apache.camel</groupId>
+    <artifactId>camel-paho</artifactId>
+    <version>x.y.z</version>
+    <!-- use the same version as your Camel core version -->
+</dependency>
+------------------------------------------------------------
+
+Keep in mind that Paho artifacts are not hosted in the Maven Central, so
+you need to add Eclipse Paho repository to your POM xml file:
+
+[source,xml]
+--------------------------------------------------------------------------
+<repositories>
+  <repository>
+    <id>eclipse-paho</id>
+    <url>https://repo.eclipse.org/content/repositories/paho-releases</url>
+    <snapshots>
+      <enabled>false</enabled>
+    </snapshots>
+  </repository>
+</repositories>
+--------------------------------------------------------------------------
+
+[[Paho-Defaultpayloadtype]]
+Default payload type
+^^^^^^^^^^^^^^^^^^^^
+
+�
+
+By default Camel Paho component operates on the binary payloads
+extracted out of (or put into) the MQTT message:
+
+[source,java]
+---------------------------------------------------------------------
+// Receive payload
+byte[] payload = (byte[]) consumerTemplate.receiveBody("paho:topic");
+�
+// Send payload
+byte[] payload = "message".getBytes();
+producerTemplate.sendBody("paho:topic", payload);
+---------------------------------------------------------------------
+
+�
+
+But of course Camel build-in�link:type-converter.html[type conversion
+API] can perform the automatic data type transformations for you. In the
+example below Camel automatically converts binary payload into String
+(and�conversely):
+
+�
+
+[source,java]
+--------------------------------------------------------------------------
+// Receive payload
+String payload = consumerTemplate.receiveBody("paho:topic", String.class);
+�
+// Send payload
+String payload = "message";
+producerTemplate.sendBody("paho:topic", payload);
+--------------------------------------------------------------------------
+
+[[Paho-URIOptions]]
+Paho Options
+^^^^^^^^^^^^
+
+
+// component options: START
+The Paho component supports 3 options which are listed below.
+
+
+
+{% raw %}
+[width="100%",cols="2s,1m,8",options="header"]
+|=======================================================================
+| Name | Java Type | Description
+| brokerUrl | String | The URL of the MQTT broker.
+| clientId | String | MQTT client identifier.
+| connectOptions | MqttConnectOptions | Client connection options
+|=======================================================================
+{% endraw %}
+// component options: END
+
+
+
+// endpoint options: START
+The Paho component supports 12 endpoint options which are listed below:
+
+{% raw %}
+[width="100%",cols="2s,1,1m,1m,5",options="header"]
+|=======================================================================
+| Name | Group | Default | Java Type | Description
+| topic | common |  | String | *Required* Name of the topic
+| brokerUrl | common | tcp://localhost:1883 | String | The URL of the MQTT broker.
+| clientId | common |  | String | MQTT client identifier.
+| connectOptions | common |  | MqttConnectOptions | Client connection options
+| filePersistenceDirectory | common | Current directory | String | Base directory used by the file persistence provider.
+| persistence | common | MEMORY | PahoPersistence | Client persistence to be used - memory or file.
+| qos | common | 2 | int | Client quality of service level (0-2).
+| retained | common | false | boolean | Retain option
+| bridgeErrorHandler | consumer | false | boolean | Allows for bridging the consumer to the Camel routing Error Handler which mean any exceptions occurred while the consumer is trying to pickup incoming messages or the likes will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions that will be logged at WARN/ERROR level and ignored.
+| exceptionHandler | consumer (advanced) |  | ExceptionHandler | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions that will be logged at WARN/ERROR level and ignored.
+| exchangePattern | advanced | InOnly | ExchangePattern | Sets the default exchange pattern when creating an exchange
+| synchronous | advanced | false | boolean | Sets whether synchronous processing should be strictly used or Camel is allowed to use asynchronous processing (if supported).
+|=======================================================================
+{% endraw %}
+// endpoint options: END
+
+
+[[Paho-Headers]]
+Headers
+^^^^^^^
+
+The following headers are recognized by the Paho component:
+
+[width="100%",cols="10%,10%,10%,10%,60%",options="header",]
+|=======================================================================
+|Header |Java constant |Endpoint type |Value type |Description
+
+|`PahoOriginalMessage` |`PahoConstants.HEADER_ORIGINAL_MESSAGE` |Consumer |`org.eclipse.paho.client.mqttv3.MqttMessage` |The original Paho message instance received by the client.
+*Deprecated:*from Camel 2.17 onwards the original MqttMessage is not
+stored as a header but on the
+`org.apache.camel.component.paho.PahoMessage` message that has a getter
+`getMqttMessage`.
+
+|`CamelMqttTopic` |PahoConstants.MQTT_TOPIC |Consumer |String |*Camel 2.17:*The topic
+|=======================================================================
+�
+
+[[Paho-SeeAlso]]
+See Also
+^^^^^^^^
+
+* link:configuring-camel.html[Configuring Camel]
+* link:component.html[Component]
+* link:endpoint.html[Endpoint]
+* link:getting-started.html[Getting Started]
+

http://git-wip-us.apache.org/repos/asf/camel/blob/b941f3f5/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 5ff2e96..17c1c7b 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -212,6 +212,7 @@
     * [Olingo2](olingo2.adoc)
     * [Openshift](openshift.adoc)
     * [Optaplanner](optaplanner.adoc)
+    * [Paho](paho.adoc)
     * [Properties](properties.adoc)
     * [Quickfix](quickfix.adoc)
     * [Scp](scp.adoc)