camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acosent...@apache.org
Subject [4/4] camel git commit: Added camel-protobuf docs to Gitbook
Date Tue, 17 May 2016 09:21:16 GMT
Added camel-protobuf 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/027352f8
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/027352f8
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/027352f8

Branch: refs/heads/master
Commit: 027352f86fb3d92895d7d33dcce5d10c45492565
Parents: e267008
Author: Andrea Cosentino <ancosen@gmail.com>
Authored: Tue May 17 11:20:11 2016 +0200
Committer: Andrea Cosentino <ancosen@gmail.com>
Committed: Tue May 17 11:20:11 2016 +0200

----------------------------------------------------------------------
 .../camel-protobuf/src/main/docs/protobuf.adoc  | 160 +++++++++++++++++++
 docs/user-manual/en/SUMMARY.md                  |   1 +
 2 files changed, 161 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/027352f8/components/camel-protobuf/src/main/docs/protobuf.adoc
----------------------------------------------------------------------
diff --git a/components/camel-protobuf/src/main/docs/protobuf.adoc b/components/camel-protobuf/src/main/docs/protobuf.adoc
new file mode 100644
index 0000000..ea8ec7a
--- /dev/null
+++ b/components/camel-protobuf/src/main/docs/protobuf.adoc
@@ -0,0 +1,160 @@
+[[Protobuf-Protobuf-ProtocolBuffers]]
+Protobuf - Protocol Buffers
+---------------------------
+
+"Protocol Buffers - Google's data interchange format"
+
+INFO: Available from Camel 2.2
+
+Camel provides a link:data-format.html[Data Format] to serialse between
+Java and the Protocol Buffer protocol. The project's site details why
+you may wish to
+http://code.google.com/apis/protocolbuffers/docs/overview.html[choose
+this format over xml]. Protocol Buffer is language-neutral and
+platform-neutral, so messages produced by your Camel routes may be
+consumed by other language implementations.
+
+http://code.google.com/apis/protocolbuffers/[API Site] +
+ http://code.google.com/p/protobuf/[Protobuf Implementation] +
+
+http://code.google.com/apis/protocolbuffers/docs/javatutorial.html[Protobuf
+Java Tutorial]
+
+[[Protobuf-Protobufoverview]]
+Protobuf overview
+~~~~~~~~~~~~~~~~~
+
+This quick overview of how to use Protobuf. For more detail see the
+http://code.google.com/apis/protocolbuffers/docs/javatutorial.html[complete
+tutorial]
+
+[[Protobuf-Definingtheprotoformat]]
+Defining the proto format
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The first step is to define the format for the body of your exchange.
+This is defined in a .proto file as so:
+
+*addressbook.proto*
+
+[source,java]
+------------------------------------------------------------
+
+package org.apache.camel.component.protobuf;
+
+option java_package = "org.apache.camel.component.protobuf";
+option java_outer_classname = "AddressBookProtos";
+
+message Person {
+  required string name = 1;
+  required int32 id = 2;
+  optional string email = 3;
+
+  enum PhoneType {
+    MOBILE = 0;
+    HOME = 1;
+    WORK = 2;
+  }
+
+  message PhoneNumber {
+    required string number = 1;
+    optional PhoneType type = 2 [default = HOME];
+  }
+
+  repeated PhoneNumber phone = 4;
+}
+
+message AddressBook {
+  repeated Person person = 1;
+}
+------------------------------------------------------------
+
+[[Protobuf-GeneratingJavaclasses]]
+Generating Java classes
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The Protobuf SDK provides a compiler which will generate the Java
+classes for the format we defined in our .proto file. You can run the
+compiler for any additional supported languages you require.
+
+`protoc --java_out=. ./addressbook.proto`
+
+This will generate a single Java class named AddressBookProtos which
+contains inner classes for Person and AddressBook. Builders are also
+implemented for you. The generated classes implement
+com.google.protobuf.Message which is required by the serialisation
+mechanism. For this reason it important that only these classes are used
+in the body of your exchanges. Camel will throw an exception on route
+creation if you attempt to tell the link:data-format.html[Data Format]
+to use a class that does not implement com.google.protobuf.Message. Use
+the generated builders to translate the data from any of your existing
+domain classes.
+
+[[Protobuf-JavaDSL]]
+Java DSL
+~~~~~~~~
+
+You can use create the ProtobufDataFormat instance and pass it to Camel
+DataFormat marshal and unmarsha API like this.
+
+[source,java]
+-----------------------------------------------------------------------------------
+   ProtobufDataFormat format = new ProtobufDataFormat(Person.getDefaultInstance());
+
+   from("direct:in").marshal(format);
+   from("direct:back").unmarshal(format).to("mock:reverse");
+-----------------------------------------------------------------------------------
+
+Or use the DSL protobuf() passing the unmarshal default instance or
+default instance class name like this.
+
+[source,java]
+--------------------------------------------------------------------------------------------------
+   // You don't need to specify the default instance for protobuf marshaling            
  
+   from("direct:marshal").marshal().protobuf();
+   from("direct:unmarshalA").unmarshal().
+       protobuf("org.apache.camel.dataformat.protobuf.generated.AddressBookProtos$Person").
+       to ("mock:reverse");
+                
+   from("direct:unmarshalB").unmarshal().protobuf(Person.getDefaultInstance()).to("mock:reverse");
+--------------------------------------------------------------------------------------------------
+
+[[Protobuf-SpringDSL]]
+Spring DSL
+~~~~~~~~~~
+
+The following example shows how to use Castor to unmarshal using Spring
+configuring the protobuf data type
+
+[source,java]
+----------------------------------------------------------------------------------------------------------
+<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
+  <route>
+    <from uri="direct:start"/>
+    <unmarshal>
+      <protobuf instanceClass="org.apache.camel.dataformat.protobuf.generated.AddressBookProtos$Person"
/>
+    </unmarshal>
+    <to uri="mock:result"/>
+  </route>
+</camelContext>
+----------------------------------------------------------------------------------------------------------
+
+[[Protobuf-Dependencies]]
+Dependencies
+^^^^^^^^^^^^
+
+To use Protobuf in your camel routes you need to add the a dependency on
+*camel-protobuf* which implements this data format.
+
+If you use maven you could just add the following to your pom.xml,
+substituting the version number for the latest & greatest release (see
+link:download.html[the download page for the latest versions]).
+
+[source,java]
+-----------------------------------------
+<dependency>
+  <groupId>org.apache.camel</groupId>
+  <artifactId>camel-protobuf</artifactId>
+  <version>2.2.0</version>
+</dependency>
+-----------------------------------------

http://git-wip-us.apache.org/repos/asf/camel/blob/027352f8/docs/user-manual/en/SUMMARY.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md
index 82d12f3..93fcdf0 100644
--- a/docs/user-manual/en/SUMMARY.md
+++ b/docs/user-manual/en/SUMMARY.md
@@ -244,6 +244,7 @@
     * [Jaxb](jaxb.adoc)
     * [Jibx](jibx.adoc)
     * [Lzf](lzf.adoc)
+    * [Protobuf](protobuf.adoc)
     * [XML JSON](xmljson.adoc)
 
 * User Guide


Mime
View raw message