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/05/17 09:21:16 UTC
[4/4] camel git commit: Added camel-protobuf docs to Gitbook
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 <an...@gmail.com>
Authored: Tue May 17 11:20:11 2016 +0200
Committer: Andrea Cosentino <an...@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