| [[thrift-dataformat]] |
| = Thrift DataFormat |
| :page-source: components/camel-thrift/src/main/docs/thrift-dataformat.adoc |
| |
| *Available as of Camel version 2.20* |
| |
| |
| Camel provides a Data Format to serialize between |
| Java and the Apache Thrift . The project's site details why |
| you may wish to |
| https://thrift.apache.org/. |
| Apache Thrift is language-neutral and |
| platform-neutral, so messages produced by your Camel routes may be |
| consumed by other language implementations. |
| |
| https://github.com/apache/thrift[Apache Thrift Implementation] + |
| |
| == Thrift Options |
| |
| // dataformat options: START |
| The Thrift dataformat supports 3 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2s,1m,1m,6",options="header"] |
| |=== |
| | Name | Default | Java Type | Description |
| | instanceClass | | String | Name of class to use when unarmshalling |
| | contentTypeFormat | binary | String | Defines a content type format in which thrift message will be serialized/deserialized from(to) the Java been. The format can either be native or json for either native binary thrift, json or simple json fields representation. The default value is binary. |
| | contentTypeHeader | false | Boolean | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc. |
| |=== |
| // dataformat options: END |
| // spring-boot-auto-configure options: START |
| == Spring Boot Auto-Configuration |
| |
| When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration: |
| |
| [source,xml] |
| ---- |
| <dependency> |
| <groupId>org.apache.camel</groupId> |
| <artifactId>camel-thrift-starter</artifactId> |
| <version>x.x.x</version> |
| <!-- use the same version as your Camel core version --> |
| </dependency> |
| ---- |
| |
| |
| The component supports 7 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *camel.component.thrift.basic-property-binding* | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | Boolean |
| | *camel.component.thrift.enabled* | Whether to enable auto configuration of the thrift component. This is enabled by default. | | Boolean |
| | *camel.component.thrift.use-global-ssl-context-parameters* | Determine if the thrift component is using global SSL context parameters | false | Boolean |
| | *camel.dataformat.thrift.content-type-format* | Defines a content type format in which thrift message will be serialized/deserialized from(to) the Java been. The format can either be native or json for either native binary thrift, json or simple json fields representation. The default value is binary. | binary | String |
| | *camel.dataformat.thrift.content-type-header* | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc. | false | Boolean |
| | *camel.dataformat.thrift.enabled* | Whether to enable auto configuration of the thrift data format. This is enabled by default. | | Boolean |
| | *camel.dataformat.thrift.instance-class* | Name of class to use when unarmshalling | | String |
| |=== |
| // spring-boot-auto-configure options: END |
| ND |
| |
| == Content type format |
| |
| It's possible to parse JSON message to convert it to the Thrift format and unparse it back using native util converter. |
| To use this option, set contentTypeFormat value to 'json' or call thrift with second parameter. |
| If default instance is not specified, always use native binary Thrift format. |
| The simple JSON format is write-only (marshal) and produces a simple output format suitable for parsing by scripting languages. |
| The sample code shows below: |
| |
| [source,java] |
| ---- |
| from("direct:marshal") |
| .unmarshal() |
| .thrift("org.apache.camel.dataformat.thrift.generated.Work", "json") |
| .to("mock:reverse"); |
| ---- |
| |
| == Thrift overview |
| |
| This quick overview of how to use Thrift. For more detail see the |
| https://thrift.apache.org/tutorial/[complete tutorial] |
| |
| == Defining the thrift format |
| |
| The first step is to define the format for the body of your exchange. |
| This is defined in a .thrift file as so: |
| |
| *tutorial.thrift* |
| |
| [source,java] |
| ---- |
| namespace java org.apache.camel.dataformat.thrift.generated |
| |
| enum Operation { |
| ADD = 1, |
| SUBTRACT = 2, |
| MULTIPLY = 3, |
| DIVIDE = 4 |
| } |
| |
| struct Work { |
| 1: i32 num1 = 0, |
| 2: i32 num2, |
| 3: Operation op, |
| 4: optional string comment, |
| } |
| ---- |
| |
| == Generating Java classes |
| |
| The Apache Thrift provides a compiler which will generate the Java |
| classes for the format we defined in our .thrift file. |
| |
| You can also run the compiler for any additional supported languages you require manually. |
| |
| `thrift -r --gen java -out ../java/ ./tutorial-dataformat.thrift` |
| |
| This will generate separate Java class for each type defined in .thrift |
| file, i.e. struct or enum. |
| The generated classes implement org.apache.thrift.TBase which is required |
| by the serialization 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 Data Format to use a class that does not implement |
| org.apache.thrift.TBase. |
| |
| == Java DSL |
| |
| You can use create the ThriftDataFormat instance and pass it to Camel |
| DataFormat marshal and unmarshal API like this. |
| |
| [source,java] |
| ---- |
| ThriftDataFormat format = new ThriftDataFormat(new Work()); |
| |
| from("direct:in").marshal(format); |
| from("direct:back").unmarshal(format).to("mock:reverse"); |
| ---- |
| |
| Or use the DSL thrift() passing the unmarshal default instance or |
| default instance class name like this. |
| |
| [source,java] |
| ---- |
| // You don't need to specify the default instance for the thrift marshaling |
| from("direct:marshal").marshal().thrift(); |
| from("direct:unmarshalA").unmarshal() |
| .thrift("org.apache.camel.dataformat.thrift.generated.Work") |
| .to("mock:reverse"); |
| |
| from("direct:unmarshalB").unmarshal().thrift(new Work()).to("mock:reverse"); |
| ---- |
| |
| == Spring DSL |
| |
| The following example shows how to use Thrift to unmarshal using Spring |
| configuring the thrift data type |
| |
| [source,java] |
| ---- |
| <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring"> |
| <route> |
| <from uri="direct:start"/> |
| <unmarshal> |
| <thrift instanceClass="org.apache.camel.dataformat.thrift.generated.Work" /> |
| </unmarshal> |
| <to uri="mock:result"/> |
| </route> |
| </camelContext> |
| ---- |
| |
| == Dependencies |
| |
| To use Thrift in your camel routes you need to add the a dependency on |
| *camel-thrift* which implements this data format. |
| |
| [source,xml] |
| ---- |
| <dependency> |
| <groupId>org.apache.camel</groupId> |
| <artifactId>camel-thrift</artifactId> |
| <version>x.x.x</version> |
| <!-- use the same version as your Camel core version --> |
| </dependency> |
| ---- |