Added camel-avro 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/3f7da0f8 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/3f7da0f8 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/3f7da0f8 Branch: refs/heads/master Commit: 3f7da0f8b1d1b7affeebc4d65e0e5ae111a98d5c Parents: 1783e69 Author: Andrea Cosentino <[email protected]> Authored: Tue Jan 26 10:10:51 2016 +0100 Committer: Andrea Cosentino <[email protected]> Committed: Tue Jan 26 11:38:17 2016 +0100 ---------------------------------------------------------------------- components/camel-avro/src/main/docs/avro.adoc | 272 +++++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 273 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/3f7da0f8/components/camel-avro/src/main/docs/avro.adoc ---------------------------------------------------------------------- diff --git a/components/camel-avro/src/main/docs/avro.adoc b/components/camel-avro/src/main/docs/avro.adoc new file mode 100644 index 0000000..2bd0f77 --- /dev/null +++ b/components/camel-avro/src/main/docs/avro.adoc @@ -0,0 +1,272 @@ +[[avro-AvroComponent]] +Avro Component +~~~~~~~~~~~~~~ + +*Available as of Camel 2.10* + +This component provides a dataformat for avro, which allows +serialization and deserialization of messages using Apache Avro's binary +dataformat. Moreover, it provides support for Apache Avro's rpc, by +providing producers and consumers endpoint for using avro over netty or +http. + +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-avro</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[[avro-ApacheAvroOverview]] +Apache Avro Overview +^^^^^^^^^^^^^^^^^^^^ + +Avro allows you to define message types and a protocol using a json like +format and then generate java code for the specified types and messages. +An example of how a schema looks like is below. + +[source,xml] +------------------------------------------------------------------------------------------ +{"namespace": "org.apache.camel.avro.generated", + "protocol": "KeyValueProtocol", + + "types": [ + {"name": "Key", "type": "record", + "fields": [ + {"name": "key", "type": "string"} + ] + }, + {"name": "Value", "type": "record", + "fields": [ + {"name": "value", "type": "string"} + ] + } + ], + + "messages": { + "put": { + "request": [{"name": "key", "type": "Key"}, {"name": "value", "type": "Value"} ], + "response": "null" + }, + "get": { + "request": [{"name": "key", "type": "Key"}], + "response": "Value" + } + } +} +------------------------------------------------------------------------------------------ + +You can easily generate classes from a schema, using maven, ant etc. +More details can be found at the +http://avro.apache.org/docs/current/[Apache Avro documentation]. + +However, it doesn't enforce a schema first approach and you can create +schema for your existing classes. *Since 2.12* you can use existing +protocol interfaces to make RCP calls. You should use interface for the +protocol itself and POJO beans or primitive/String classes for parameter +and result types. Here is an example of the class that corresponds to +schema above: + +[source,java] +-------------------------------------------------------------- +package org.apache.camel.avro.reflection; + +public interface KeyValueProtocol { + void put(String key, Value value); + Value get(String key); +} + +class Value { + private String value; + public String getValue() { return value; } + public void setValue(String value) { this.value = value; } +} +-------------------------------------------------------------- + +_Note: Existing classes can be used only for RPC (see below), not in +data format._ + +[[avro-UsingtheAvrodataformat]] +Using the Avro data format +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Using the avro data format is as easy as specifying that the class that +you want to marshal or unmarshal in your route. + +[source,xml] +-------------------------------------------------------------------------------- + <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring"> + <route> + <from uri="direct:in"/> + <marshal> + <avro instanceClass="org.apache.camel.dataformat.avro.Message"/> + </marshal> + <to uri="log:out"/> + </route> + </camelContext> +-------------------------------------------------------------------------------- + +An alternative can be to specify the dataformat inside the context and +reference it from your route. + +[source,xml] +-------------------------------------------------------------------------------------- + <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring"> + <dataFormats> + <avro id="avro" instanceClass="org.apache.camel.dataformat.avro.Message"/> + </dataFormats> + <route> + <from uri="direct:in"/> + <marshal ref="avro"/> + <to uri="log:out"/> + </route> + </camelContext> +-------------------------------------------------------------------------------------- + +In the same manner you can umarshal using the avro data format. + +[[avro-UsingAvroRPCinCamel]] +Using Avro RPC in Camel +^^^^^^^^^^^^^^^^^^^^^^^ + +As mentioned above Avro also provides RPC support over multiple +transports such as http and netty. Camel provides consumers and +producers for these two transports. + +[source,java] +---------------------------------------- +avro:[transport]:[host]:[port][?options] +---------------------------------------- + +The supported transport values are currently http or netty. + +*Since 2.12* you can specify message name right in the URI: + +[source,java] +------------------------------------------------------ +avro:[transport]:[host]:[port][/messageName][?options] +------------------------------------------------------ + +For consumers this allows you to have multiple routes attached to the +same socket. Dispatching to correct route will be done by the avro +component automatically. Route with no messageName specified (if any) +will be used as default. + +When using camel producers for avro ipc, the "in" message body needs to +contain the parameters of the operation specified in the avro protocol. +The response will be added in the body of the "out" message. + +In a similar manner when using camel avro consumers for avro ipc, the +requests parameters will be placed inside the "in" message body of the +created exchange and once the exchange is processed the body of the +"out" message will be send as a response. + +*Note:* By default consumer parameters are wrapped into array. If you've +got only one parameter, *since 2.12* you can use `singleParameter` URI +option to receive it direcly in the "in" message body without array +wrapping. + +[[avro-AvroRPCURIOptions]] +Avro RPC URI Options +^^^^^^^^^^^^^^^^^^^^ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Name |Version |Description +|`protocolClassName`| | The class name of the avro protocol. + +|`singleParameter` |2.12 |If true, consumer parameter won't be wrapped into array. Will fail if +protocol specifies more then 1 parameter for the message + +|`protocol` | | Avro protocol object. Can be used instead of `protocolClassName` when +complex protocol needs to be created. One cane used #name notation to +refer beans from the Registry + +|`reflectionProtocol` |2.12 |If protocol object provided is reflection protocol. Should be used only +with `protocol` parameter because for `protocolClassName` protocol type +will be autodetected +|======================================================================= + +[[avro-AvroRPCHeaders]] +Avro RPC Headers +^^^^^^^^^^^^^^^^ + +[width="100%",cols="20%,80%",options="header",] +|======================================================================= +|Name |Description + +|`CamelAvroMessageName` |The name of the message to send. In consumer overrides message name from +URI (if any) +|======================================================================= + +[[avro-Examples]] +Examples +^^^^^^^^ + +An example of using camel avro producers via http: + +[source,xml] +--------------------------------------------------------------------------------------------------------------------------- + <route> + <from uri="direct:start"/> + <to uri="avro:http:localhost:{{avroport}}?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol"/> + <to uri="log:avro"/> + </route> +--------------------------------------------------------------------------------------------------------------------------- + +In the example above you need to fill `CamelAvroMessageName` header. +*Since 2.12* you can use following syntax to call constant messages: + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------- +Â Â Â Â <route> +Â Â Â Â Â Â <from uri="direct:start"/> +Â Â Â Â Â Â <to uri="avro:http:localhost:{{avroport}}/put?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol"/> +Â Â Â Â Â Â <to uri="log:avro"/> +Â Â Â Â </route> +------------------------------------------------------------------------------------------------------------------------------- + +An example of consuming messages using camel avro consumers via netty: + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------ + <route> + <from uri="avro:netty:localhost:{{avroport}}?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol"/> + <choice> + <when> + <el>${in.headers.CamelAvroMessageName == 'put'}</el> + <process ref="putProcessor"/> + </when> + <when> + <el>${in.headers.CamelAvroMessageName == 'get'}</el> + <process ref="getProcessor"/> + </when> + </choice> + </route> +------------------------------------------------------------------------------------------------------------------------------ + +*Since 2.12* you can set up two distinct routes to perform the same +task: + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------------------------------- + <route> + <from uri="avro:netty:localhost:{{avroport}}/put?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol"> + <process ref="putProcessor"/> + </route> + <route> + <from uri="avro:netty:localhost:{{avroport}}/get?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol&singleParameter=true"/> + <process ref="getProcessor"/> + </route> +------------------------------------------------------------------------------------------------------------------------------------------------------- + +In the example above, get takes only one parameter, so `singleParameter` +is used and `getProcessor` will receive Value class directly in body, +while `putProcessor` will receive an array of size 2 with String key and +Value value filled as array contents. http://git-wip-us.apache.org/repos/asf/camel/blob/3f7da0f8/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 78c0ae2..78b67a8 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -75,6 +75,7 @@ * [Apns](apns.adoc) * [Atmosphere Websocket](atmosphere-websocket.adoc) * [Atom](atom.adoc) + * [Avro](avro.adoc) * [CDI](cdi.adoc) * [JMS](jms.adoc)
