camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject [4/6] camel git commit: Added camel-avro docs to gitbook
Date Tue, 26 Jan 2016 10:39:50 GMT
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 <ancosen@gmail.com>
Authored: Tue Jan 26 10:10:51 2016 +0100
Committer: Andrea Cosentino <ancosen@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) 
 


Mime
View raw message