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 <anco...@gmail.com> Authored: Tue May 17 11:20:11 2016 +0200 Committer: Andrea Cosentino <anco...@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
