You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by ac...@apache.org on 2016/01/26 11:39:50 UTC
[4/6] camel git commit: Added camel-avro docs to gitbook
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 <an...@gmail.com>
Authored: Tue Jan 26 10:10:51 2016 +0100
Committer: Andrea Cosentino <an...@gmail.com>
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)