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 <anco...@gmail.com> Authored: Tue May 17 10:42:46 2016 +0200 Committer: Andrea Cosentino <anco...@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)
