camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Camel > Book DataFormat Appendix
Date Thu, 11 Nov 2010 15:27:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=CAMEL&amp;forWysiwyg=true" type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CAMEL/Book+DataFormat+Appendix">Book DataFormat Appendix</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~davsclaus">Claus Ibsen</a>
    </h4>
        <br/>
                         <h4>Changes (2)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. Todo <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{div:class=chapter|id=chapter-dataformat-Appendix} <br>h1. Data Format Appendix <br> <br>{include:Data Format} <br> <br>{include:Artix Data Services} <br>{include:Serialization} <br>{include:JAXB} <br>{include:XmlBeans} <br>{include:XStream} <br>{include:CSV} <br>{include:String} <br>{include:HL7 DataFormat} <br>{include:EDI} <br>{include:Flatpack DataFormat} <br>{include:JSON} <br>{include:Zip DataFormat} <br>{include:TidyMarkup} <br>{include:Bindy} <br>{include:XMLSecurity DataFormat} <br>{include:GZip data format} <br>{include:Castor} <br>{include:Protobuf} <br>{include:SOAP} <br>{include:Crypto} <br>{include:Syslog} <br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <div id="chapter-dataformat-Appendix" class="chapter"></div>
<h1><a name="BookDataFormatAppendix-DataFormatAppendix"></a>Data Format Appendix</h1>

<h2><a name="BookDataFormatAppendix-DataFormat"></a>Data Format</h2>

<p>Camel supports a pluggable DataFormat to allow messages to be marshalled to and from binary or text formats to support a kind of <a href="/confluence/display/CAMEL/Message+Translator" title="Message Translator">Message Translator</a>.</p>

<p>The following data formats are currently supported:</p>

<ul>
	<li>Standard JVM object marshalling
	<ul>
		<li><a href="/confluence/display/CAMEL/Serialization" title="Serialization">Serialization</a></li>
		<li><a href="/confluence/display/CAMEL/String" title="String">String</a></li>
	</ul>
	</li>
</ul>


<ul>
	<li>Object marshalling
	<ul>
		<li><a href="/confluence/display/CAMEL/JSON" title="JSON">JSON</a></li>
		<li><a href="/confluence/display/CAMEL/Protobuf" title="Protobuf">Protobuf</a></li>
	</ul>
	</li>
</ul>


<ul>
	<li>Object/XML marshalling
	<ul>
		<li><a href="/confluence/display/CAMEL/Castor" title="Castor">Castor</a></li>
		<li><a href="/confluence/display/CAMEL/JAXB" title="JAXB">JAXB</a></li>
		<li><a href="/confluence/display/CAMEL/XmlBeans" title="XmlBeans">XmlBeans</a></li>
		<li><a href="/confluence/display/CAMEL/XStream" title="XStream">XStream</a></li>
	</ul>
	</li>
</ul>


<ul>
	<li>Object/XML/Webservice marshalling
	<ul>
		<li><a href="/confluence/display/CAMEL/SOAP" title="SOAP">SOAP</a></li>
	</ul>
	</li>
</ul>


<ul>
	<li>Flat data structure marshalling
	<ul>
		<li><a href="/confluence/display/CAMEL/Artix+Data+Services" title="Artix Data Services">Artix Data Services</a></li>
		<li><a href="/confluence/display/CAMEL/Bindy" title="Bindy">Bindy</a></li>
		<li><a href="/confluence/display/CAMEL/CSV" title="CSV">CSV</a></li>
		<li><a href="/confluence/display/CAMEL/EDI" title="EDI">EDI</a></li>
		<li><a href="/confluence/display/CAMEL/Flatpack+DataFormat" title="Flatpack DataFormat">Flatpack DataFormat</a></li>
	</ul>
	</li>
</ul>


<ul>
	<li>Domain specific marshalling
	<ul>
		<li><a href="/confluence/display/CAMEL/HL7+DataFormat" title="HL7 DataFormat">HL7 DataFormat</a></li>
	</ul>
	</li>
</ul>


<ul>
	<li>Compression
	<ul>
		<li><a href="/confluence/display/CAMEL/GZip+data+format" title="GZip data format">GZip data format</a></li>
		<li><a href="/confluence/display/CAMEL/Zip+DataFormat" title="Zip DataFormat">Zip DataFormat</a></li>
	</ul>
	</li>
</ul>


<ul>
	<li>Security
	<ul>
		<li><a href="/confluence/display/CAMEL/Crypto" title="Crypto">Crypto</a></li>
		<li><a href="/confluence/display/CAMEL/XMLSecurity+DataFormat" title="XMLSecurity DataFormat">XMLSecurity DataFormat</a></li>
	</ul>
	</li>
</ul>


<ul>
	<li>Misc.
	<ul>
		<li><a href="/confluence/display/CAMEL/TidyMarkup" title="TidyMarkup">TidyMarkup</a></li>
		<li><a href="/confluence/display/CAMEL/Syslog" title="Syslog">Syslog</a></li>
	</ul>
	</li>
</ul>


<p>And related is the following <a href="/confluence/display/CAMEL/Type+Converter" title="Type Converter">Type Converter</a>s:</p>
<ul class="alternate" type="square">
	<li><a href="/confluence/display/CAMEL/Dozer+Type+Conversion" title="Dozer Type Conversion">Dozer Type Conversion</a></li>
</ul>


<h3><a name="BookDataFormatAppendix-Unmarshalling"></a>Unmarshalling</h3>

<p>If you receive a message from one of the Camel <a href="/confluence/display/CAMEL/Components" title="Components">Components</a> such as <a href="/confluence/display/CAMEL/File" title="File">File</a>, <a href="/confluence/display/CAMEL/HTTP" title="HTTP">HTTP</a> or <a href="/confluence/display/CAMEL/JMS" title="JMS">JMS</a> you often want to unmarshal the payload into some bean so that you can process it using some <a href="/confluence/display/CAMEL/Bean+Integration" title="Bean Integration">Bean Integration</a> or perform <a href="/confluence/display/CAMEL/Predicate" title="Predicate">Predicate</a> evaluation and so forth. To do this use the <b>unmarshal</b> word in the <a href="/confluence/display/CAMEL/DSL" title="DSL">DSL</a> in Java or the <a href="/confluence/display/CAMEL/Xml+Configuration" title="Xml Configuration">Xml Configuration</a>.</p>

<p>For example</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
DataFormat jaxb = <span class="code-keyword">new</span> JaxbDataFormat(<span class="code-quote">"com.acme.model"</span>);

from(<span class="code-quote">"activemq:My.Queue"</span>).
  unmarshal(jaxb).
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>

<p>The above uses a named DataFormat of <em>jaxb</em> which is configured with a number of Java package names. You can if you prefer use a named reference to a data format which can then be defined in your <a href="/confluence/display/CAMEL/Registry" title="Registry">Registry</a> such as via your <a href="/confluence/display/CAMEL/Spring" title="Spring">Spring</a> XML file.</p>

<p>You can also use the DSL itself to define the data format as you use it. For example the following uses Java serialization to unmarshal a binary file then send it as an ObjectMessage to <a href="/confluence/display/CAMEL/ActiveMQ" title="ActiveMQ">ActiveMQ</a></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"file:<span class="code-comment">//foo/bar"</span>).
</span>  unmarshal().serialization().
  to(<span class="code-quote">"activemq:Some.Queue"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Marshalling"></a>Marshalling</h3>

<p>Marshalling is the opposite of unmarshalling, where a bean is marshalled into some binary or textual format for transmission over some transport via a Camel <a href="/confluence/display/CAMEL/Component" title="Component">Component</a>. Marshalling is used in the same way as unmarshalling above; in the <a href="/confluence/display/CAMEL/DSL" title="DSL">DSL</a> you can use a DataFormat instance, you can configure the DataFormat dynamically using the DSL or you can refer to a named instance of the format in the <a href="/confluence/display/CAMEL/Registry" title="Registry">Registry</a>.</p>

<p>The following example unmarshals via serialization then marshals using a named JAXB data format to perform a kind of <a href="/confluence/display/CAMEL/Message+Translator" title="Message Translator">Message Translator</a></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"file:<span class="code-comment">//foo/bar"</span>).
</span>  unmarshal().serialization(). 
  marshal(<span class="code-quote">"jaxb"</span>).
  to(<span class="code-quote">"activemq:Some.Queue"</span>);
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-UsingSpringXML"></a>Using Spring XML</h3>

<p>This example shows how to configure the data type just once and reuse it on multiple routes</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
  <span class="code-tag">&lt;dataFormats&gt;</span>
    <span class="code-tag">&lt;jaxb id=<span class="code-quote">"myJaxb"</span> prettyPrint=<span class="code-quote">"true"</span> contextPath=<span class="code-quote">"org.apache.camel.example"</span>/&gt;</span>
  <span class="code-tag">&lt;/dataFormats&gt;</span>

  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;</span>
    <span class="code-tag">&lt;marshal ref=<span class="code-quote">"myJaxb"</span>/&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"direct:marshalled"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>
  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:marshalled"</span>/&gt;</span>
    <span class="code-tag">&lt;unmarshal ref=<span class="code-quote">"myJaxb"</span>/&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>

<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<p>You can also define reusable data formats as Spring beans </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;bean id=<span class="code-quote">"myJaxb"</span> class=<span class="code-quote">"org.apache.camel.model.dataformat.JaxbDataFormat"</span>&gt;
  &lt;property name=<span class="code-quote">"prettyPrint"</span> value=<span class="code-quote">"<span class="code-keyword">true</span>"</span>/&gt;
  &lt;property name=<span class="code-quote">"contextPath"</span> value=<span class="code-quote">"org.apache.camel.example"</span>/&gt;
&lt;/bean&gt;  
</pre>
</div></div>


<h2><a name="BookDataFormatAppendix-ArtixDataServices"></a>Artix Data Services</h2>
<p><b>Deprecated, will be removed in Apache Camel 2.1</b></p>

<p>The Artix DS <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> supports the <a href="http://www.iona.com/artix/ds" class="external-link" rel="nofollow">Artix Data Services (ADS)</a> product which provides a framework for reading and writing a huge number of vertical message payloads like SWIFT, SEPA, FpML, TWIST, ISO 20022, CREST and FIX. In addition ADS provides tooling and a framework for reading and writing any legacy binary or text file using any kind of encoding like fixed width, delimited, XML, CSV and so forth. </p>

<p>ADS also provides a transformation framework making it very easy to implement the <a href="/confluence/display/CAMEL/Message+Translator" title="Message Translator">Message Translator</a> pattern using the ADS tooling to design the transformation.</p>

<h3><a name="BookDataFormatAppendix-Unmarhalling"></a>Unmarhalling</h3>

<p>The first step to using ADS is usually to unmarshal some message from one of the Camel <a href="/confluence/display/CAMEL/Components" title="Components">Components</a> like <a href="/confluence/display/CAMEL/File" title="File">File</a>, <a href="/confluence/display/CAMEL/HTTP" title="HTTP">HTTP</a> or <a href="/confluence/display/CAMEL/JMS" title="JMS">JMS</a> etc.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:InputQueue"</span>).
  unmarshal().artixDS(DocumentElement.class).
  to(<span class="code-quote">"mqseries:OutputQueue"</span>);
</pre>
</div></div>

<p>The above unmarshals using the Artix DS <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> for the element <b>DocumentElement</b> which is generated by the Artix DS tooling; DocumentElement is the root element of the message structure.</p>

<p>The above will use the default formatting for the data type. However with Artix DS you can switch from the default format to other formats easily. So you could add a specific format if you wish...</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:InputQueue"</span>).
  unmarshal().artixDS(DocumentElement.class, ArtixDSContentType.Xml).
  to(<span class="code-quote">"mqseries:OutputQueue"</span>);
</pre>
</div></div>

<p>If you use static imports this can be even more readable...</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  unmarshal().artixDS(DocumentElement.class, Xml).
</pre>
</div></div>

<h4><a name="BookDataFormatAppendix-UnmarshallingSWIFTmessages"></a>Unmarshalling SWIFT messages</h4>

<p>If you are working with <a href="http://en.wikipedia.org/wiki/Society_for_Worldwide_Interbank_Financial_Telecommunication" class="external-link" rel="nofollow">SWIFT</a> messages then as of camel-artixds version 1.3.6.0 or later there is a handy SwiftFormat helper class which avoids you having to know which Element class you want to use.</p>

<p>So you can unmarshal SWIFT messages using this code</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:InputQueue"</span>).
  unmarshal(<span class="code-keyword">new</span> SwiftFormat()).
  to(<span class="code-quote">"mqseries:OutputQueue"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Marshalling"></a>Marshalling</h3>

<p>Marshalling is the reverse of unmarshalling suprise suprise <img class="emoticon" src="/confluence/images/icons/emoticons/smile.gif" height="20" width="20" align="absmiddle" alt="" border="0"/>.</p>

<p>Here's an example which unmarshals using one format (XML) and then marshals using a different format (in this case tagged value pairs).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:XmlInput"</span>).
	unmarshal().artixDS(DocumentElement.class, ArtixDSContentType.Xml).
	marshal().artixDS(ArtixDSContentType.TagValuePair).
  	to(<span class="code-quote">"mqseries:TagOutput"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Typeconversions"></a>Type conversions </h3>

<p>An alternative to explicit unmarshalling in the DSL you can just use the common <b>convertBodyTo(Class)</b> method in the DSL to convert using the default content type to a particular ComplexDataObject from Artix DS. This mechanism uses the inbuilt Camel <a href="/confluence/display/CAMEL/Type+Converter" title="Type Converter">Type Converter</a> mechanism ot automatically marshal and unmarshal using the default content type for a model.</p>

<p>For example the following...</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:InputQueue"</span>).
  convertBodyTo(DocumentElement.class).
  to(<span class="code-quote">"mqseries:OutputQueue"</span>);
</pre>
</div></div>

<p>Is equivalent to this</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:InputQueue"</span>).
  unmarshal().artixDS(DocumentElement.class).
  to(<span class="code-quote">"mqseries:OutputQueue"</span>);
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-UsingTransformations"></a>Using Transformations</h3>

<p>To use the <a href="/confluence/display/CAMEL/Message+Translator" title="Message Translator">Message Translator</a> pattern with ADS its a simple matter of using the ADS tooling to create your transformation, then just using the generated transformation class in the <a href="/confluence/display/CAMEL/Bean+Integration" title="Bean Integration">Bean Integration</a> in Camel.</p>

<p>For example image you define a transformation in the ADS IDE to translate SWIFT to FIX format. You will then have a generated SwiftToFix Java class. You can then use the transformation in your Camel <a href="/confluence/display/CAMEL/DSL" title="DSL">DSL</a> via Java or the <a href="/confluence/display/CAMEL/Xml+Configuration" title="Xml Configuration">Xml Configuration</a> as follows</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:SwiftQueue"</span>).
  bean(SwiftToFix.class).
  to(<span class="code-quote">"mqseries:FixQueue"</span>);
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-ConfiguringviaSpringXML"></a>Configuring via Spring XML</h3>

<p>The following example shows how to use Artix DS using <a href="/confluence/display/CAMEL/Spring" title="Spring">Spring</a> XML; in this case it unmarshals the content of a JMS queue as XML using the Artix DS data model; then marshals it using a tag/value pair.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
  <span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://activemq.apache.org/camel/schema/spring"</span>&gt;</span>
    <span class="code-tag">&lt;route&gt;</span>
      <span class="code-tag">&lt;from uri=<span class="code-quote">"activemq:MyInputQueue"</span>/&gt;</span>
      <span class="code-tag">&lt;unmarshal&gt;</span>
        <span class="code-tag">&lt;artixDS contentType=<span class="code-quote">"Xml"</span> elementTypeName=<span class="code-quote">"iso.std.iso.x20022.tech.xsd.pacs.x008.x001.x01.DocumentElement"</span>/&gt;</span>
      <span class="code-tag">&lt;/unmarshal&gt;</span>
      <span class="code-tag">&lt;marshal&gt;</span>
        <span class="code-tag">&lt;artixDS contentType=<span class="code-quote">"TagValuePair"</span>/&gt;</span>
      <span class="code-tag">&lt;/marshal&gt;</span>
      <span class="code-tag">&lt;to uri=<span class="code-quote">"mqseries:MyOutputQueue"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>
  <span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-ContentTypesandautodiscovery"></a>Content Types and auto discovery</h3>

<p>You may have spotted in the above that we use the <a href="http://activemq.apache.org/camel/maven/camel-core/apidocs/org/apache/camel/model/dataformat/ArtixDSContentType.html" class="external-link" rel="nofollow">ArtixDSContentType</a> which is an <em>enum</em> in Java and the <a href="/confluence/display/CAMEL/Xml+Configuration" title="Xml Configuration">Xml Configuration</a> to describe the kind of XML format to use such as binary, XML, Text etc.</p>

<p>If no content type is specified we always use the default content type of the Artix DS model in question. This is equivalent to the <b>Default</b> content type.</p>

<p>If you wish to be flexible in what you accept or emit, we also support the <b>Auto</b> content type which will look for the <b>Content-Type</b> header on the input message and use that to try determine which of the content types to use; if none can be found then <b>Default</b> is used.</p>

<p>e.g. you could support content posted with a MIME type of <b>application/xml</b> to indicate XML or <b>application/x-java-serialized-object</b> for serialization or <b>text/plain</b> for text etc.</p>

<h3><a name="BookDataFormatAppendix-Usingcamelartixds"></a>Using camel-artixds</h3>

<p>To use this module you need to use the <a href="http://fusesource.com/products/enterprise-camel" class="external-link" rel="nofollow">FUSE Mediation Router</a> distribution. Or you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-artixds&lt;/artifactId&gt;
  &lt;version&gt;1.5.3.0-fuse&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<p>And ensure you are pointing at the maven repo</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   &lt;repository&gt;
     &lt;id&gt;open.iona.m2&lt;/id&gt;
     &lt;name&gt;FUSESource Open Source Community Release Repository&lt;/name&gt;
     &lt;url&gt;http:<span class="code-comment">//repo.fusesource.com/maven2/&lt;/url&gt;
</span>     &lt;snapshots&gt;
       &lt;enabled&gt;<span class="code-keyword">false</span>&lt;/enabled&gt;
     &lt;/snapshots&gt;
     &lt;releases&gt;
       &lt;enabled&gt;<span class="code-keyword">true</span>&lt;/enabled&gt;
     &lt;/releases&gt;
   &lt;/repository&gt;
</pre>
</div></div>

<h2><a name="BookDataFormatAppendix-Serialization"></a>Serialization</h2>

<p>Serialization is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> which uses the standard Java Serialization mechanism to unmarshal a binary payload into Java objects or to marshal Java objects into a binary blob.<br/>
 For example the following uses Java serialization to unmarshal a binary file then send it as an ObjectMessage to <a href="/confluence/display/CAMEL/ActiveMQ" title="ActiveMQ">ActiveMQ</a></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"file:<span class="code-comment">//foo/bar"</span>).
</span>  unmarshal().serialization().
  to(<span class="code-quote">"activemq:Some.Queue"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>This data format is provided in <b>camel-core</b> so no additional dependencies is needed.</p>

<h2><a name="BookDataFormatAppendix-JAXB"></a>JAXB</h2>

<p>JAXB is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> which uses the JAXB2 XML marshalling standard which is included in Java 6 to unmarshal an XML payload into Java objects or to marshal Java objects into an XML payload.</p>

<h3><a name="BookDataFormatAppendix-UsingtheJavaDSL"></a>Using the Java DSL</h3>

<p>For example the following uses a named DataFormat of <em>jaxb</em> which is configured with a number of Java package names to initialize the <a href="http://java.sun.com/javase/6/docs/api/javax/xml/bind/JAXBContext.html" class="external-link" rel="nofollow">JAXBContext</a>. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
DataFormat jaxb = <span class="code-keyword">new</span> JaxbDataFormat(<span class="code-quote">"com.acme.model"</span>);

from(<span class="code-quote">"activemq:My.Queue"</span>).
  unmarshal(jaxb).
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>

<p>You can if you prefer use a named reference to a data format which can then be defined in your <a href="/confluence/display/CAMEL/Registry" title="Registry">Registry</a> such as via your <a href="/confluence/display/CAMEL/Spring" title="Spring">Spring</a> XML file. e.g. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:My.Queue"</span>).
  unmarshal(<span class="code-quote">"myJaxbDataType"</span>).
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-UsingSpringXML"></a>Using Spring XML</h3>

<p>The following example shows how to use JAXB to unmarshal using <a href="/confluence/display/CAMEL/Spring" title="Spring">Spring</a> configuring the jaxb data type</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;</span>
    <span class="code-tag">&lt;unmarshal&gt;</span>
      <span class="code-tag">&lt;jaxb prettyPrint=<span class="code-quote">"true"</span> contextPath=<span class="code-quote">"org.apache.camel.example"</span>/&gt;</span>
    <span class="code-tag">&lt;/unmarshal&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>
<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<p>This example shows how to configure the data type just once and reuse it on multiple routes. For Camel versions below 1.5.0 you have to set the &lt;jaxb&gt; element directly in &lt;camelContext&gt;.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
  <span class="code-tag">&lt;dataFormats&gt;</span>
    <span class="code-tag">&lt;jaxb id=<span class="code-quote">"myJaxb"</span> prettyPrint=<span class="code-quote">"true"</span> contextPath=<span class="code-quote">"org.apache.camel.example"</span>/&gt;</span>
  <span class="code-tag">&lt;/dataFormats&gt;</span>

  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;</span>
    <span class="code-tag">&lt;marshal ref=<span class="code-quote">"myJaxb"</span>/&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"direct:marshalled"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>
  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:marshalled"</span>/&gt;</span>
    <span class="code-tag">&lt;unmarshal ref=<span class="code-quote">"myJaxb"</span>/&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>

<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Multiple context paths</b><br />It is possible to use this data format with more than one context path. You can specify context path using <tt>:</tt> as separator, for example <tt>com.mycompany:com.mycompany2</tt>. Note that this is handled by JAXB implementation and might change if you use different vendor than RI.</td></tr></table></div>

<h3><a name="BookDataFormatAppendix-Partialmarshalling%2Funmarshalling"></a>Partial marshalling/unmarshalling</h3>
<p><b>This feature is new to Camel 2.2.0.</b><br/>
JAXB 2 supports marshalling and unmarshalling XML tree fragments. By default JAXB looks for <tt>@XmlRootElement</tt> annotation on given class to operate on whole XML tree. This is useful but not always - sometimes generated code does not have @XmlRootElement annotation, sometimes you need unmarshall only part of tree.<br/>
In that case you can use partial unmarshalling. To enable this behaviours you need set property <tt>partClass</tt>. Camel will pass this class to JAXB's unmarshaler.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:marshal"</span>/&gt;</span>
        <span class="code-tag">&lt;marshal&gt;</span>
            &lt;jaxb prettyPrint=<span class="code-quote">"false"</span> contextPath=<span class="code-quote">"org.apache.camel.example"</span>
                partClass=<span class="code-quote">"org.apache.camel.example.PurchaseOrder"</span>
                partNamespace=<span class="code-quote">"{http://example.camel.org/apache}po"</span> /&gt;
        <span class="code-tag">&lt;/marshal&gt;</span>
        <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:marshal"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>
    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:unmarshal"</span>/&gt;</span>
        <span class="code-tag">&lt;unmarshal&gt;</span>
            &lt;jaxb prettyPrint=<span class="code-quote">"false"</span> contextPath=<span class="code-quote">"org.apache.camel.example"</span>
                partClass=<span class="code-quote">"org.apache.camel.example.Partial"</span> /&gt;
        <span class="code-tag">&lt;/unmarshal&gt;</span>
        <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:unmarshal"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>
<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<p>For marshalling you have to add <tt>partNamespace</tt> attribute with QName of destination namespace. Example of Spring DSL you can find above.</p>

<h3><a name="BookDataFormatAppendix-IgnoringtheNonXMLCharacter"></a>Ignoring the NonXML Character</h3>
<p><b>This feature is new to Camel 2.2.0.</b><br/>
JaxbDataFromat supports to ignore the <a href="http://www.w3.org/TR/2004/REC-xml-20040204/#NT-Char" class="external-link" rel="nofollow">NonXML Character</a>, you just need to set the filterNonXmlChars property to be true, JaxbDataFromat will replace the NonXML character with " " when it is marshaling or unmarshaling the message. You can also do it by setting the <a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a> property <tt>Exchange.FILTER_NON_XML_CHARS</tt>.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<th class='confluenceTh'> JDK 1.5 </th>
<th class='confluenceTh'> JDK 1.6+ </th>
</tr>
<tr>
<th class='confluenceTh'> Filtering in use </th>
<td class='confluenceTd'> StAX API and implementation </td>
<td class='confluenceTd'> No </td>
</tr>
<tr>
<th class='confluenceTh'> Filtering not in use </th>
<td class='confluenceTd'> StAX API only </td>
<td class='confluenceTd'> No </td>
</tr>
</tbody></table>
</div>


<p>This feature has been tested with Woodstox 3.2.9 and Sun JDK 1.6 StAX implementation.</p>

<h3><a name="BookDataFormatAppendix-WorkingwiththeObjectFactory"></a>Working with the ObjectFactory</h3>

<p>If you use XJC to create the java class from the schema, you will get an ObjectFactory for you JAXB context. Since the ObjectFactory uses <a href="http://java.sun.com/javase/6/docs/api/javax/xml/bind/JAXBElement.html" class="external-link" rel="nofollow">JAXBElement</a> to hold the reference of the schema and element instance value, from Camel 1.5.1 jaxbDataformat will ignore the JAXBElement by default and you will get the element instance value instead of the JAXBElement object form the unmarshaled message body. <br/>
If you want to get the JAXBElement object form the unmarshaled message body, you need to set the JaxbDataFormat object's ignoreJAXBElement property to be false.</p>


<h3><a name="BookDataFormatAppendix-Settingencoding"></a>Setting encoding</h3>
<p>In Camel 1.6.1 and newer you can set the <b>encoding</b> option to use when marshalling. Its the <tt>Marshaller.JAXB_ENCODING</tt> encoding property on the JAXB Marshaller.<br/>
You can setup which encoding to use when you declare the JAXB data format. You can also provide the encoding in the <a href="/confluence/display/CAMEL/Exchange" title="Exchange">Exchange</a> property <tt>Exchange.CHARSET_NAME</tt>. This property will overrule the encoding set on the JAXB data format.</p>

<p>In this Spring DSL we have defined to use <tt>iso-8859-1</tt> as the encoding:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;</span>
        <span class="code-tag">&lt;marshal&gt;</span>
            <span class="code-tag">&lt;jaxb prettyPrint=<span class="code-quote">"false"</span> encoding=<span class="code-quote">"iso-8859-1"</span> contextPath=<span class="code-quote">"org.apache.camel.example"</span>/&gt;</span>
        <span class="code-tag">&lt;/marshal&gt;</span>
        <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>
<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use JAXB in your camel routes you need to add the a dependency on <b>camel-jaxb</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-jaxb&lt;/artifactId&gt;
  &lt;version&gt;1.6.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h2><a name="BookDataFormatAppendix-XmlBeans"></a>XmlBeans</h2>

<p>XmlBeans is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> which uses the <a href="http://xmlbeans.apache.org/" class="external-link" rel="nofollow">XmlBeans library</a> to unmarshal an XML payload into Java objects or to marshal Java objects into an XML payload.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:My.Queue"</span>).
  unmarshal().xmlBeans().
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use XmlBeans in your camel routes you need to add the a dependency on <b>camel-xmlbeans</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-xmlbeans&lt;/artifactId&gt;
  &lt;version&gt;1.5.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h2><a name="BookDataFormatAppendix-XStream"></a>XStream</h2>

<p>XStream is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> which uses the <a href="http://xstream.codehaus.org/" class="external-link" rel="nofollow">XStream library</a> to marshal and unmarshal Java objects to and from XML.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// lets turn <span class="code-object">Object</span> messages into XML then send to MQSeries
</span>from(<span class="code-quote">"activemq:My.Queue"</span>).
  marshal().xstream().
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-XMLInputFactoryandXMLOutputFactory"></a>XMLInputFactory and XMLOutputFactory </h3>
<p><a href="http://xstream.codehaus.org/" class="external-link" rel="nofollow">The XStream library</a> uses the <tt>javax.xml.stream.XMLInputFactory</tt> and <tt>javax.xml.stream.XMLOutputFactory</tt>,  you can control which implementation of this factory should be used.</p>

<p>The Factory is discovered using this algorithm:<br/>
1. Use the <tt>javax.xml.stream.XMLInputFactory</tt> , <tt>javax.xml.stream.XMLOutputFactory</tt> system property.<br/>
2. Use the <tt>lib/xml.stream.properties</tt> file in the <tt>JRE_HOME</tt> directory.<br/>
3. Use the Services API, if available, to determine the classname by looking in the <tt>META-INF/services/javax.xml.stream.XMLInputFactory</tt>, <tt>META-INF/services/javax.xml.stream.XMLOutputFactory</tt>  files in jars available to the JRE.<br/>
4. Use the platform default XMLInputFactory,XMLOutputFactory instance.</p>

<h3><a name="BookDataFormatAppendix-HowtosettheXMLencodinginXstreamDataFormat%3F"></a>How to set the XML encoding in Xstream DataFormat?</h3>
<p>From Camel 1.6.3 or Camel 2.2.0, you can set the encoding of XML in Xstream DataFormat by setting the Exchange's property with the key <tt>Exchange.CHARSET_NAME</tt>, or setting the encoding property on Xstream from DSL or Spring config.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:My.Queue"</span>).
  marshal().xstream(<span class="code-quote">"UTF-8"</span>).
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
    
    <span class="code-tag"><span class="code-comment">&lt;!-- we define the json xstream data formats to be used (xstream is default) --&gt;</span></span>
    <span class="code-tag">&lt;dataFormats&gt;</span>
        <span class="code-tag">&lt;xstream id=<span class="code-quote">"xstream-utf8"</span> encoding=<span class="code-quote">"UTF-8"</span>/&gt;</span>
        <span class="code-tag">&lt;xstream id=<span class="code-quote">"xstream-default"</span>/&gt;</span>
    <span class="code-tag">&lt;/dataFormats&gt;</span>

    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:in"</span>/&gt;</span>
        <span class="code-tag">&lt;marshal ref=<span class="code-quote">"xstream-default"</span>/&gt;</span>
        <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>

    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:in-UTF-8"</span>/&gt;</span>
        <span class="code-tag">&lt;marshal ref=<span class="code-quote">"xstream-utf8"</span>/&gt;</span>
        <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>

<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use XStream in your camel routes you need to add the a dependency on <b>camel-xstream</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-xstream&lt;/artifactId&gt;
  &lt;version&gt;1.5.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h2><a name="BookDataFormatAppendix-CSV"></a>CSV</h2>

<p>The CSV <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> uses <a href="http://commons.apache.org/sandbox/csv/" class="external-link" rel="nofollow">Apache Commons CSV</a> to handle CSV payloads (Comma Separated Values) such as those exported/imported by Excel.</p>

<h3><a name="BookDataFormatAppendix-Options"></a>Options</h3>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> config </td>
<td class='confluenceTd'> CSVConfig </td>
<td class='confluenceTd'> Can be used to set a custom CSVConfig object. </td>
</tr>
<tr>
<td class='confluenceTd'> strategy </td>
<td class='confluenceTd'> CSVStrategy </td>
<td class='confluenceTd'> Camel uses by default <tt>CSVStrategy.DEFAULT_STRATEGY</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> autogenColumn </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> <b>Camel 1.6.1/2.0:</b> Is default true. By default, columns are autogenerated in the resulting CSV. Subsequent messages use the previously created columns with new fields being added at the end of the line. </td>
</tr>
<tr>
<td class='confluenceTd'> delimiter </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <b>Camel 2.4:</b> Is default <tt>,</tt>. Can be used to configure the delimiter, if it's not the comma. </td>
</tr>
</tbody></table>
</div>


<h3><a name="BookDataFormatAppendix-MarshallingaMaptoCSV"></a>Marshalling a Map to CSV</h3>
<p>The component allows you to marshal a Java Map (or any other message type that can be <a href="/confluence/display/CAMEL/Type+Converter" title="Type Converter">converted</a> in a Map) into a CSV payload.</p>

<p>An example: if you send a message with this map...</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt; body = <span class="code-keyword">new</span> HashMap&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;();
body.put(<span class="code-quote">"foo"</span>, <span class="code-quote">"abc"</span>);
body.put(<span class="code-quote">"bar"</span>, 123);
</pre>
</div></div>
<p>... through this route ...</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">from(<span class="code-quote">"direct:start"</span>).
    marshal().csv().
    to(<span class="code-quote">"mock:result"</span>);
</pre>
</div></div>

<p>... you will end up with a String containing this CSV message</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>abc,123</pre>
</div></div>
<p>Sending the Map below through this route will result in a CSV message that looks like <tt>foo,bar</tt></p>

<h3><a name="BookDataFormatAppendix-UnmarshallingaCSVmessageintoaJavaList"></a>Unmarshalling a CSV message into a Java List</h3>
<p>Unmarshalling will transform a CSV messsage into a Java List with CSV file lines (containing another List with all the field values).</p>

<p>An example: we have a CSV file with names of persons, their IQ and their current activity.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-sql">Jack Dalton, 115, mad at Averell
Joe Dalton, 105, calming Joe
William Dalton, 105, keeping Joe <span class="code-keyword">from</span> killing Averell
Averell Dalton, 80, playing with Rantanplan
Lucky Luke, 120, capturing the Daltons
</pre>
</div></div>

<p>We can now use the CSV component to unmarshal this file:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">from(<span class="code-quote">"file:src/test/resources/?fileName=daltons.csv&amp;noop=<span class="code-keyword">true</span>"</span>).
    unmarshal().csv().
    to(<span class="code-quote">"mock:daltons"</span>);
</pre>
</div></div>

<p>The resulting message will contain a <tt>List&lt;List&lt;String&gt;&gt;</tt> like...</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">List&lt;List&lt;<span class="code-object">String</span>&gt;&gt; data = (List&lt;List&lt;<span class="code-object">String</span>&gt;&gt;) exchange.getIn().getBody();
<span class="code-keyword">for</span> (List&lt;<span class="code-object">String</span>&gt; line : data) {
    LOG.debug(<span class="code-object">String</span>.format(<span class="code-quote">"%s has an IQ of %s and is currently %s"</span>,
                            line.get(0), line.get(1), line.get(2)));
}
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-MarshallingaList%3CMap%3EtoCSV"></a>Marshalling a List&lt;Map&gt; to CSV</h3>
<p><b>Available as of Camel 2.1</b></p>

<p>If you have multiple rows of data you want to be marshalled into CSV format you can now store the message payload as a <tt>List&lt;Map&lt;String, Object&gt;&gt;</tt> object where the list contains a Map for each row.</p>

<h3><a name="BookDataFormatAppendix-FilePollerofCSV%2Cthenunmarshaling"></a>File Poller of CSV, then unmarshaling</h3>

<p>Given a bean which can handle the incoming data...</p>
<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>MyCsvHandler.java</b></div><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// Some comments here
</span><span class="code-keyword">public</span> void doHandleCsvData(List&lt;List&lt;<span class="code-object">String</span>&gt;&gt; csvData)
{
    <span class="code-comment">// <span class="code-keyword">do</span> magic here
</span>}
</pre>
</div></div> 

<p>... your route then looks as follows</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag"><span class="code-comment">&lt;!-- poll every 10 seconds --&gt;</span></span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"file:///some/path/to/pickup/csvfiles?delete=true&amp;amp;consumer.delay=10000"</span> /&gt;</span>
        <span class="code-tag">&lt;unmarshal&gt;</span><span class="code-tag">&lt;csv /&gt;</span><span class="code-tag">&lt;/unmarshal&gt;</span>
        <span class="code-tag">&lt;to uri=<span class="code-quote">"bean:myCsvHandler?method=doHandleCsvData"</span> /&gt;</span>
<span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-Marshalingwithapipeasdelimiter"></a>Marshaling with a pipe as delimiter</h3>

<p>Using the Spring/XML DSL:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;route&gt;</span>
  <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span> /&gt;</span>
  <span class="code-tag">&lt;marshal&gt;</span>
    <span class="code-tag">&lt;csv delimiter=<span class="code-quote">"|"</span> /&gt;</span>
  <span class="code-tag">&lt;/marshal&gt;</span>
  <span class="code-tag">&lt;to uri=<span class="code-quote">"bean:myCsvHandler?method=doHandleCsv"</span> /&gt;</span>
<span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>

<p>Or the Java DSL:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
CsvDataFormat csv = <span class="code-keyword">new</span> CsvDataFormat();
CSVConfig config = <span class="code-keyword">new</span> CSVConfig();
config.setDelimiter('|');
csv.setConfig(config);

from(<span class="code-quote">"direct:start"</span>)
  .marshal(csv)
  .convertBodyTo(<span class="code-object">String</span>.class)
.to(<span class="code-quote">"bean:myCsvHandler?method=doHandleCsv"</span>);
</pre>
</div></div>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
CsvDataFormat csv = <span class="code-keyword">new</span> CsvDataFormat();
csv.setDelimiter(<span class="code-quote">"|"</span>);

from(<span class="code-quote">"direct:start"</span>)
  .marshal(csv)
  .convertBodyTo(<span class="code-object">String</span>.class)
.to(<span class="code-quote">"bean:myCsvHandler?method=doHandleCsv"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Unmarshalingwithapipeasdelimiter"></a>Unmarshaling with a pipe as delimiter</h3>

<p>Using the Spring/XML DSL:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;route&gt;</span>
  <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:start"</span> /&gt;</span>
  <span class="code-tag">&lt;unmarshal&gt;</span>
    <span class="code-tag">&lt;csv delimiter=<span class="code-quote">"|"</span> /&gt;</span>
  <span class="code-tag">&lt;/unmarshal&gt;</span>
  <span class="code-tag">&lt;to uri=<span class="code-quote">"bean:myCsvHandler?method=doHandleCsv"</span> /&gt;</span>
<span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>

<p>Or the Java DSL:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
CsvDataFormat csv = <span class="code-keyword">new</span> CsvDataFormat();
CSVStrategy strategy = CSVStrategy.DEFAULT_STRATEGY;
strategy.setDelimiter('|');
csv.setStrategy(strategy);

from(<span class="code-quote">"direct:start"</span>)
  .unmarshal(csv)
.to(<span class="code-quote">"bean:myCsvHandler?method=doHandleCsv"</span>);
</pre>
</div></div>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
CsvDataFormat csv = <span class="code-keyword">new</span> CsvDataFormat();
csv.setDelimiter(<span class="code-quote">"|"</span>);

from(<span class="code-quote">"direct:start"</span>)
  .unmarshal(csv)
.to(<span class="code-quote">"bean:myCsvHandler?method=doHandleCsv"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use CSV in your camel routes you need to add the a dependency on <b>camel-csv</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-csv&lt;/artifactId&gt;
  &lt;version&gt;2.0.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>
<p>The String <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> is a textual based format that supports encoding. </p>

<h3><a name="BookDataFormatAppendix-Options"></a>Options</h3>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> charset </td>
<td class='confluenceTd'> null </td>
<td class='confluenceTd'> To use a specific charset for encoding. If not provided Camel will use the JVM default charset. </td>
</tr>
</tbody></table>
</div>


<h3><a name="BookDataFormatAppendix-Marshal"></a>Marshal</h3>
<p>In this example we marshal the file content to String object in UTF-8 encoding.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"file:<span class="code-comment">//data.csv"</span>).marshal().string(<span class="code-quote">"UTF-8"</span>).to(<span class="code-quote">"jms://myqueue"</span>);</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Unmarshal"></a>Unmarshal</h3>
<p>In this example we unmarshal the payload from the JMS queue to a String object using UTF-8 encoding, before its processed by the newOrder processor. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"jms:<span class="code-comment">//queue/order"</span>).unmarshal().string(<span class="code-quote">"UTF-8"</span>).processRef(<span class="code-quote">"newOrder"</span>);</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>This data format is provided in <b>camel-core</b> so no additional dependencies is needed.</p>
<h3><a name="BookDataFormatAppendix-HL7DataFormat"></a>HL7 DataFormat</h3>
<p>The <a href="/confluence/display/CAMEL/HL7" title="HL7">HL7</a> component ships with a HL7 data format that can be used to format between <tt>String</tt> and HL7 model objects. </p>
<ul class="alternate" type="square">
	<li><tt>marshal</tt> = from Message to byte stream (can be used when returning as response using the HL7 MLLP codec)</li>
	<li><tt>unmarshal</tt> = from byte stream to Message (can be used when receiving streamed data from the HL7 MLLP</li>
</ul>


<p>To use the data format, simply instantiate an instance and invoke the marhsal or unmarshl operation in the route builder:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  DataFormat hl7 = <span class="code-keyword">new</span> HL7DataFormat();
  ...
  from(<span class="code-quote">"direct:hl7in"</span>).marshal(hl7).to(<span class="code-quote">"jms:queue:hl7out"</span>);
</pre>
</div></div>
<p>In the sample above, the HL7 is marshalled from a HAPI Message object to a byte stream and put on a JMS queue.<br/>
The next example is the opposite:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  DataFormat hl7 = <span class="code-keyword">new</span> HL7DataFormat();
  ...
  from(<span class="code-quote">"jms:queue:hl7out"</span>).unmarshal(hl7).to(<span class="code-quote">"patientLookupService"</span>);
</pre>
</div></div>
<p>Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.</p>

<p>Notice there is a shorthand syntax in Camel for well-known data formats that is commonly used.<br/>
Then you don't need to create an instance of the <tt>HL7DataFormat</tt> object:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  from(<span class="code-quote">"direct:hl7in"</span>).marshal().hl7().to(<span class="code-quote">"jms:queue:hl7out"</span>);
  from(<span class="code-quote">"jms:queue:hl7out"</span>).unmarshal().hl7().to(<span class="code-quote">"patientLookupService"</span>);
</pre>
</div></div>
<h2><a name="BookDataFormatAppendix-EDIDataFormat"></a>EDI DataFormat</h2>

<p>This component ships with a EDI dataformat that can be used to format from a <tt>java.io.InputStream</tt> to XML as a <tt>org.w3c.Document</tt> Object.</p>
<ul>
	<li>marshal = currently not supported by <a href="http://milyn.codehaus.org/Home" class="external-link" rel="nofollow">Smooks</a></li>
	<li>unmarshal = from stream to XML (can be used when reading EDI files)</li>
</ul>


<p>The EDIDataFormat must be configued with either a:</p>
<ul>
	<li><tt>setSmooksConfig(configfile)</tt> = a fully <a href="http://milyn.codehaus.org/Home" class="external-link" rel="nofollow">Smooks</a> configuration file</li>
	<li><tt>setMappingModel(modelfile)</tt> = just the mapping model xml file and Camel will use a default <a href="http://milyn.codehaus.org/Home" class="external-link" rel="nofollow">Smooks</a> configuration</li>
</ul>


<p>To use the data format simply instantiate an instance, set the configuration (above) and invoke the unmarshal operation in the route builder:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
DataFormat edi = <span class="code-keyword">new</span> EDIDataFormat();
edi.setMappingModel(<span class="code-quote">"my-order-mapping.xml"</span>);
...
from(<span class="code-quote">"file:<span class="code-comment">//edi/in"</span>).
</span>  unmarshal(edi).
  to(<span class="code-quote">"jms:queue:edi"</span>);
</pre>
</div></div>

<p>And you can also provide the full <a href="http://milyn.codehaus.org/Home" class="external-link" rel="nofollow">Smooks</a> configuration file where you can configure <a href="http://milyn.codehaus.org/Home" class="external-link" rel="nofollow">Smooks</a> as you want, in case the default configuration isn't useful:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
DataFormat edi = <span class="code-keyword">new</span> EDIDataFormat();
edi.setSmooksConfig(<span class="code-quote">"my-smooks-config.xml"</span>);
...
from(<span class="code-quote">"file:<span class="code-comment">//edi/in"</span>).
</span>  unmarshal(edi).
  to(<span class="code-quote">"jms:queue:edi"</span>);
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use EDI in your camel routes you need to add the a dependency on <b>camel-smooks</b> which implements this data format. </p>

<p>This component is hosted at the <a href="http://camel-extra.googlecode.com/" class="external-link" rel="nofollow">Camel Extra</a> project since the Smooks library uses a licenses which cant be included directly in an Apache project.</p>
<h2><a name="BookDataFormatAppendix-FlatpackDataFormat"></a>Flatpack DataFormat</h2>
<p>The <a href="/confluence/display/CAMEL/Flatpack" title="Flatpack">Flatpack</a> component ships with the Flatpack data format that can be used to format between fixed width or delimited text messages to a <tt>List</tt> of rows as <tt>Map</tt>. </p>
<ul class="alternate" type="square">
	<li>marshal = from <tt>List&lt;Map&lt;String, Object&gt;&gt;</tt> to <tt>OutputStream</tt> (can be converted to <tt>String</tt>)</li>
	<li>unmarshal = from <tt>java.io.InputStream</tt> (such as a <tt>File</tt> or <tt>String</tt>) to a <tt>java.util.List</tt> as an <tt>org.apache.camel.component.flatpack.DataSetList</tt> instance.<br/>
The result of the operation will contain all the data. If you need to process each row one by one you can split the exchange, using <a href="/confluence/display/CAMEL/Splitter" title="Splitter">Splitter</a>.</li>
</ul>


<p><b>Notice:</b> The Flatpack library does currently not support header and trailers for the marshal operation.</p>

<h3><a name="BookDataFormatAppendix-Options"></a>Options</h3>
<p>The data format has the following options:</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>definition</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> The flatpack pzmap configuration file. Can be omitted in simpler situations, but its preferred to use the pzmap. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>fixed</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> Delimited or fixed. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>ignoreFirstRecord</tt> </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'> Whether the first line is ignored for delimited files (for the column headers). </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>textQualifier</tt> </td>
<td class='confluenceTd'> <tt>"</tt> </td>
<td class='confluenceTd'> If the text is qualified with a char such as <tt>"</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>delimiter</tt> </td>
<td class='confluenceTd'> <tt>,</tt> </td>
<td class='confluenceTd'> The delimiter char (could be <tt>;</tt> <tt>,</tt> or similar) </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>parserFactory</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Uses the default Flatpack parser factory. </td>
</tr>
</tbody></table>
</div>


<h3><a name="BookDataFormatAppendix-Usage"></a>Usage</h3>
<p>To use the data format, simply instantiate an instance and invoke the marhsal or unmarshal operation in the route builder:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  FlatpackDataFormat fp = <span class="code-keyword">new</span> FlatpackDataFormat();
  fp.setDefinition(<span class="code-keyword">new</span> ClassPathResource(<span class="code-quote">"INVENTORY-Delimited.pzmap.xml"</span>));
  ...
  from(<span class="code-quote">"file:order/in"</span>).unmarshal(df).to(<span class="code-quote">"seda:queue:neworder"</span>);
</pre>
</div></div>
<p>The sample above will read files from the <tt>order/in</tt> folder and unmarshal the input using the Flatpack configuration file <tt>INVENTORY-Delimited.pzmap.xml</tt> that configures the structure of the files. The result is a <tt>DataSetList</tt> object we store on the SEDA queue.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
FlatpackDataFormat df = <span class="code-keyword">new</span> FlatpackDataFormat();
df.setDefinition(<span class="code-keyword">new</span> ClassPathResource(<span class="code-quote">"PEOPLE-FixedLength.pzmap.xml"</span>));
df.setFixed(<span class="code-keyword">true</span>);
df.setIgnoreFirstRecord(<span class="code-keyword">false</span>);

from(<span class="code-quote">"seda:people"</span>).marshal(df).convertBodyTo(<span class="code-object">String</span>.class).to(<span class="code-quote">"jms:queue:people"</span>);
</pre>
</div></div>
<p>In the code above we marshal the data from a Object representation as a <tt>List</tt> of rows as <tt>Maps</tt>. The rows as <tt>Map</tt> contains the column name as the key, and the the corresponding value. This structure can be created in Java code from e.g. a processor. We marshal the data according to the Flatpack format and convert the result as a <tt>String</tt> object and store it on a JMS queue.</p>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use Flatpack in your camel routes you need to add the a dependency on <b>camel-flatpack</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-flatpack&lt;/artifactId&gt;
  &lt;version&gt;1.5.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h2><a name="BookDataFormatAppendix-JSON"></a>JSON</h2>
<p>JSON is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> to marshal and unmarshal Java objects to and from <a href="http://www.json.org/" class="external-link" rel="nofollow">JSON</a>.</p>

<p>In Camel 1.6 its only the XStream library that is supported and its default.</p>

<p>In Camel 2.0 we added support for more libraries:<br/>
Camel provides integration with two popular JSon libraries:</p>
<ul class="alternate" type="square">
	<li>The <a href="http://xstream.codehaus.org/" class="external-link" rel="nofollow">XStream library</a> and <a href="http://jettison.codehaus.org/" class="external-link" rel="nofollow">Jettsion </a></li>
	<li>The <a href="http://xircles.codehaus.org/projects/jackson" class="external-link" rel="nofollow">Jackson library</a></li>
</ul>


<p>By default Camel uses the XStream library. </p>

<h3><a name="BookDataFormatAppendix-UsingJSondataformatwiththeXStreamlibrary"></a>Using JSon data format with the XStream library</h3>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// lets turn <span class="code-object">Object</span> messages into json then send to MQSeries
</span>from(<span class="code-quote">"activemq:My.Queue"</span>).
  marshal().json().
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-UsingJsondataformatwiththeJacksonlibrary"></a>Using Json data format with the Jackson library</h3>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-comment">// lets turn <span class="code-object">Object</span> messages into json then send to MQSeries
</span>from(<span class="code-quote">"activemq:My.Queue"</span>).
  marshal().json(JsonLibrary.Jackson).
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>

<h4><a name="BookDataFormatAppendix-UsingJsoninSpringDSL"></a>Using Json in Spring DSL</h4>
<p>When using <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> in Spring DSL you need to declare the data formats first. This is done in the <b>DataFormats</b> XML tag.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
        <span class="code-tag">&lt;dataFormats&gt;</span>
            &lt;!-- here we define a Json data format with the id jack and that it should use the TestPojo as the class type when
                 doing unmarshal. The unmarshalTypeName is optional, if not provided Camel will use a Map as the type --&gt;
            <span class="code-tag">&lt;json id=<span class="code-quote">"jack"</span> library=<span class="code-quote">"Jackson"</span> unmarshalTypeName=<span class="code-quote">"org.apache.camel.component.jackson.TestPojo"</span>/&gt;</span>
        <span class="code-tag">&lt;/dataFormats&gt;</span>
</pre>
</div></div>

<p>And then you can refer to this id in the route:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
       <span class="code-tag">&lt;route&gt;</span>
            <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:back"</span>/&gt;</span>
            <span class="code-tag">&lt;unmarshal ref=<span class="code-quote">"jack"</span>/&gt;</span>
            <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:reverse"</span>/&gt;</span>
        <span class="code-tag">&lt;/route&gt;</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-DependenciesforXStream"></a>Dependencies for XStream</h3>

<p>To use JSON in your camel routes you need to add the a dependency on <b>camel-xstream</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-xstream&lt;/artifactId&gt;
  &lt;version&gt;2.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-DependenciesforJackson"></a>Dependencies for Jackson</h3>

<p>To use JSON in your camel routes you need to add the a dependency on <b>camel-jackson</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-jackson&lt;/artifactId&gt;
  &lt;version&gt;2.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>

<p>The Zip <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> is a message compression and de-compression format. Messages marshalled using Zip compression can be unmarshalled using Zip decompression just prior to being consumed at the endpoint. The compression capability is quite useful when you deal with large XML and Text based payloads. It facilitates more optimal use of network bandwidth while incurring a small cost in order to compress and decompress payloads at the endpoint.</p>

<h3><a name="BookDataFormatAppendix-Options"></a>Options</h3>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> compressionLevel </td>
<td class='confluenceTd'> null </td>
<td class='confluenceTd'> To specify a specific compression Level use <tt>java.util.zip.Deflater</tt> settings. The possible settings are&nbsp; <br class="atl-forced-newline" />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - <tt>Deflater.BEST_SPEED</tt> <br class="atl-forced-newline" />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - <tt>Deflater.BEST_COMPRESSION</tt> <br class="atl-forced-newline" />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - <tt>Deflater.DEFAULT_COMPRESSION</tt> <br class="atl-forced-newline" />
<br class="atl-forced-newline" />
If compressionLevel is not explicitly specified the compressionLevel employed is <tt>Deflater.DEFAULT_COMPRESSION</tt> </td>
</tr>
</tbody></table>
</div>


<h3><a name="BookDataFormatAppendix-Marshal"></a>Marshal</h3>

<p>In this example we marshal a regular text/XML payload to a compressed payload employing zip compression <tt>Deflater.BEST_COMPRESSION</tt> and send it an ActiveMQ queue called MY_QUEUE.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"direct:start"</span>).marshal().zip(Deflater.BEST_COMPRESSION).to(<span class="code-quote">"activemq:queue:MY_QUEUE"</span>);
</pre>
</div></div>
<p>Alternatively if you would like to use the default setting you could send it as</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"direct:start"</span>).marshal().zip().to(<span class="code-quote">"activemq:queue:MY_QUEUE"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Unmarshal"></a>Unmarshal</h3>

<p>In this example we unmarshal&nbsp;a zipped&nbsp;payload from an ActiveMQ queue called MY_QUEUE&nbsp;to its original format,&nbsp;and forward it for&nbsp;processing&nbsp;to the UnZippedMessageProcessor. Note that the compression Level employed during the marshalling should be identical to the one employed during unmarshalling to avoid errors.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:queue:MY_QUEUE"</span>).unmarshal().zip().process(<span class="code-keyword">new</span> UnZippedMessageProcessor()); 
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>This data format is provided in <b>camel-core</b> so no additional dependencies is needed.</p>
<h2><a name="BookDataFormatAppendix-TidyMarkup"></a>TidyMarkup</h2>

<p>TidyMarkup is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> that uses the <a href="http://www.ccil.org/~cowan/XML/tagsoup/" class="external-link" rel="nofollow">TagSoup</a> to tidy up HTML. It can be used to parse ugly HTML and return it as pretty wellformed HTML.</p>

<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Camel eats our own <del>dog food</del> soap</b><br />We had some issues in our pdf <a href="/confluence/display/CAMEL/Manual" title="Manual">Manual</a> where we had some strange symbols. So <a href="http://janstey.blogspot.com/" class="external-link" rel="nofollow">Jonathan</a> used this data format to tidy up the wiki html pages that are used as base for rendering the pdf manuals. And then the mysterious symbols vanished.</td></tr></table></div> 

<p><a href="/confluence/display/CAMEL/TidyMarkup" title="TidyMarkup">TidyMarkup</a> only supports the <b>unmarshal</b> operation as we really don't want to turn well formed HTML into ugly HTML <img class="emoticon" src="/confluence/images/icons/emoticons/smile.gif" height="20" width="20" align="absmiddle" alt="" border="0"/></p>

<h3><a name="BookDataFormatAppendix-JavaDSLExample"></a>Java DSL Example</h3>
<p>An example where the consumer provides some HTML</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"file:<span class="code-comment">//site/inbox"</span>).unmarshal().tidyMarkup().to(<span class="code-quote">"file://site/blogs"</span>);</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-SpringXMLExample"></a>Spring XML Example</h3>
<p>The following example shows how to use <a href="/confluence/display/CAMEL/TidyMarkup" title="TidyMarkup">TidyMarkup</a> to unmarshal using Spring</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http:<span class="code-comment">//camel.apache.org/schema/spring"</span>&gt;
</span>  &lt;route&gt;
    &lt;from uri=<span class="code-quote">"file:<span class="code-comment">//site/inbox"</span>/&gt;
</span>    &lt;unmarshal&gt;
      &lt;tidyMarkup/&gt;
    &lt;/unmarshal&gt;
    &lt;to uri=<span class="code-quote">"file:<span class="code-comment">//site/blogs"</span>/&gt;
</span>  &lt;/route&gt;
&lt;/camelContext&gt;
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use TidyMarkup in your camel routes you need to add the a dependency on <b>camel-tagsoup</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-tagsoup&lt;/artifactId&gt;
  &lt;version&gt;1.6.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>
<h2><a name="BookDataFormatAppendix-Bindy"></a>Bindy</h2>

<p><b>Available as of Camel 2.0</b></p>

<p>The idea that the developers has followed to design this component was to allow the parsing/binding of non structured data (or to be more precise non-XML data)<br/>
to Java Bean using annotations. Using Bindy, you can bind data like :</p>
<ul class="alternate" type="square">
	<li>CSV record,</li>
	<li>Fixedlength record,</li>
	<li>FIX messages,</li>
	<li>or any other non-structured data</li>
</ul>


<p>to one or many Plain Old Java Object (POJO) and to convert the data according to the type of the java property. POJO  can be linked together and relation one to many is available in some cases. Moreover, for data type like Date, Double, Float, Integer, Short, Long and BigDecimal, you can provide the pattern to apply during the formatting of the property.</p>

<p>For the BigDecimal number, you can also define the precision and the decimal or grouping separators</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Format Type </th>
<th class='confluenceTh'> Pattern example </th>
<th class='confluenceTh'> Link </th>
</tr>
<tr>
<td class='confluenceTd'> Date </td>
<td class='confluenceTd'> DateFormat </td>
<td class='confluenceTd'> "dd-MM-yyyy" </td>
<td class='confluenceTd'> <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html" class="external-link" rel="nofollow">http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html</a> </td>
</tr>
<tr>
<td class='confluenceTd'> Decimal&#42; </td>
<td class='confluenceTd'> Decimalformat </td>
<td class='confluenceTd'> "##.###.###" </td>
<td class='confluenceTd'> <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/text/DecimalFormat.html" class="external-link" rel="nofollow">http://java.sun.com/j2se/1.5.0/docs/api/java/text/DecimalFormat.html</a> </td>
</tr>
</tbody></table>
</div>

<p>Decimal&#42; = Double, Integer, Float, Short, Long</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Format supported</b><br />This first release only support comma separated values fields and key value pair fields (e.g. : FIX messages).</td></tr></table></div>
<p>To work with camel-bindy, you must first define your model in a package (e.g. com.acme.model) and for each model class (e.g. Order, Client, Instrument, ...) associate the required annotations (described hereafter) with Class or property name.</p>

<h2><a name="BookDataFormatAppendix-Annotations"></a>Annotations</h2>

<p>The annotations created allow to map different concept of your model to the POJO like :</p>

<ul class="alternate" type="square">
	<li>Type of record (csv, key value pair (e.g. FIX message), fixed length ...),</li>
	<li>Link (to link object in another object),</li>
	<li>DataField and their properties (int, type, ...),</li>
	<li>KeyValuePairField (for key = value format like we have in FIX financial messages),</li>
	<li>Section (to identify header, body and footer section),</li>
	<li>OneToMany</li>
</ul>


<p>This section will describe them :</p>

<h3><a name="BookDataFormatAppendix-1.CsvRecord"></a>1. CsvRecord</h3>

<p>The CsvRecord annotation is used to identified the root class of the model. It represents a record = a line of a CSV file and can be linked to several children model classes.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Annotation name </th>
<th class='confluenceTh'> Record type </th>
<th class='confluenceTh'> Level </th>
</tr>
<tr>
<td class='confluenceTd'> <b>CsvRecord</b> </td>
<td class='confluenceTd'> csv </td>
<td class='confluenceTd'> Class </td>
</tr>
</tbody></table>
</div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter name </th>
<th class='confluenceTh'> type </th>
<th class='confluenceTh'> Info </th>
</tr>
<tr>
<td class='confluenceTd'> separator </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> mandatory - can be ',' or ';' or 'anything'. This value is interpreted as a regular expression. If you want to use a sign which has a special meaning in regular expressions, e.g. the '&#124;' sign, than you have to mask it, like '<br class="atl-forced-newline" />|' </td>
</tr>
<tr>
<td class='confluenceTd'> skipFirstLine </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - default value = false - allow to skip the first line of the CSV file </td>
</tr>
<tr>
<td class='confluenceTd'> crlf </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - default value = WINDOWS - allow to define the carriage return character to use </td>
</tr>
<tr>
<td class='confluenceTd'> generateHeaderColumns </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - default value = false - uses to generate the header columns of the CSV generates </td>
</tr>
<tr>
<td class='confluenceTd'> isOrdered </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - default value = false - allow to change the order of the fields when CSV is generated </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>This annotation is associated to the root class of the model and must be declared one time.</td>
</tr>
</tbody></table>
</div>


<p><b>case 1 : separator = ','</b></p>

<p>The separator used to segregate the fields in the CSV record is ',' :</p>

<p>10, J, Pauline, M, XD12345678, Fortis Dynamic 15/15, 2500, USD,08-01-2009</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Separator ,</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord( separator = <span class="code-quote">","</span> )
<span class="code-keyword">public</span> <span class="code-object">Class</span> Order {
...
}
</pre>
</div></div>

<p><b>case 2 : separator = ';'</b></p>

<p>Compare to the previous case, the separator here is ';' instead of ',' :</p>

<p>10; J; Pauline; M; XD12345678; Fortis Dynamic 15/15; 2500; USD; 08-01-2009</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Separator ;</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord( separator = <span class="code-quote">";"</span> )
<span class="code-keyword">public</span> <span class="code-object">Class</span> Order {
...
}
</pre>
</div></div>

<p><b>case 3 : separator = '|'</b></p>

<p>Compare to the previous case, the separator here is '|' instead of ';' :</p>

<p>10| J| Pauline| M| XD12345678| Fortis Dynamic 15/15| 2500| USD| 08-01-2009</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Separator</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord( separator = <span class="code-quote">"\\|"</span> )
<span class="code-keyword">public</span> <span class="code-object">Class</span> Order {
...
}
</pre>
</div></div>

<p><b>case 3 : separator = '\",\"'</b></p>

<p>When the field to be parsed of the CSV record contains ',' or ';' which is also used as separator, we whould find another strategy<br/>
to tell camel bindy how to handle this case. To define the field containing the data with a comma, you will use simple or double quotes<br/>
as delimiter (e.g : '10', 'Street 10, NY', 'USA' or "10", "Street 10, NY", "USA").<br/>
Remark : In this case, the first and last character of the line which are a simple or double quotes will removed by bindy </p>

<p>"10","J","Pauline"," M","XD12345678","Fortis Dynamic 15,15" 2500","USD","08-01-2009"</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Separator ""</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord( separator = <span class="code-quote">"\"</span>,\"" )
<span class="code-keyword">public</span> <span class="code-object">Class</span> Order {
...
}
</pre>
</div></div>

<p><b>case 5 : separator &amp; skipfirstline</b></p>

<p>The feature is interesting when the client wants to have in the first line of the file, the name of the data fields : </p>

<p>order id, client id, first name, last name, isin code, instrument name, quantity, currency, date</p>

<p>To inform bindy that this first line must be skipped during the parsing process, then we use the attribute :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Separator &amp; skipFirstLine</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>, skipFirstLine = <span class="code-keyword">true</span>)
<span class="code-keyword">public</span> <span class="code-object">Class</span> Order {
...
}
</pre>
</div></div>

<p><b>case 6 : generateHeaderColumns</b></p>

<p>To add at the first line of the CSV generated, the attribute generateHeaderColumns must be set to true in the annotation like this : </p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>generateHeaderColumns</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord( generateHeaderColumns = <span class="code-keyword">true</span> )
<span class="code-keyword">public</span> <span class="code-object">Class</span> Order {
...
}
</pre>
</div></div>

<p>As a result, Bindy during the unmarshaling process will generate CSV like this :</p>

<p>order id, client id, first name, last name, isin code, instrument name, quantity, currency, date<br/>
10, J, Pauline, M, XD12345678, Fortis Dynamic 15/15, 2500, USD,08-01-2009</p>

<p><b>case 7 : carriage return</b></p>

<p>If the platform where camel-bindy will run is not Windows but Macintosh or Unix, than you can change the crlf property like this. Three values are available : WINDOWS, UNIX or MAC</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>carriage return</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>, crlf=<span class="code-quote">"MAC"</span>)
<span class="code-keyword">public</span> <span class="code-object">Class</span> Order {
...
}
</pre>
</div></div>

<p><b>case 8 : isOrdered</b></p>

<p>Sometimes, the order to follow during the creation of the CSV record from the model is different from the order used during the parsing. Then, in this case, we can use the attribute isOrdered = true to indicate this in combination with attribute 'position' of the DataField annotation.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>isOrdered</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(isOrdered = <span class="code-keyword">true</span>)
<span class="code-keyword">public</span> <span class="code-object">Class</span> Order {

   @DataField(pos = 1, position = 11)
   <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

   @DataField(pos = 2, position = 10)
   <span class="code-keyword">private</span> <span class="code-object">String</span> clientNr;

...
}
</pre>
</div></div>

<p>Remark : pos is used to parse the file, stream while positions is used to generate the CSV</p>


<h3><a name="BookDataFormatAppendix-2.Link"></a>2. Link</h3>

<p>The link annotation will allow to link objects together. </p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Annotation name </th>
<th class='confluenceTh'> Record type </th>
<th class='confluenceTh'> Level </th>
</tr>
<tr>
<td class='confluenceTd'> <b>Link</b> </td>
<td class='confluenceTd'> all </td>
<td class='confluenceTd'> Class &amp; Property </td>
</tr>
</tbody></table>
</div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter name </th>
<th class='confluenceTh'> type </th>
<th class='confluenceTh'> Info </th>
</tr>
<tr>
<td class='confluenceTd'> linkType </td>
<td class='confluenceTd'> LinkType </td>
<td class='confluenceTd'> optional - by default the value is LinkType.oneToOne - so you are not obliged to mention it </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> Only one-to-one relation is allowed. </td>
</tr>
</tbody></table>
</div>


<p>e.g : If the model Class Client is linked to the Order class, then use annotation Link in the Order class like this :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Property Link</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>)
<span class="code-keyword">public</span> class Order {

    @DataField(pos = 1)
    <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

    @Link
    <span class="code-keyword">private</span> Client client;
...
</pre>
</div></div>

<p>AND for the class Client :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Class Link</b></div><div class="codeContent panelContent">
<pre class="code-java">
@Link
<span class="code-keyword">public</span> class Client {
...
}
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-3.DataField"></a>3. DataField</h3>

<p>The DataField annotation defines the property of the field. Each datafield is identified by its position in the record, a type (string, int, date, ...) and optionally of a pattern</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Annotation name </th>
<th class='confluenceTh'> Record type </th>
<th class='confluenceTh'> Level </th>
</tr>
<tr>
<td class='confluenceTd'> <b>DataField</b> </td>
<td class='confluenceTd'> all </td>
<td class='confluenceTd'> Property </td>
</tr>
</tbody></table>
</div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter name </th>
<th class='confluenceTh'> type </th>
<th class='confluenceTh'> Info </th>
</tr>
<tr>
<td class='confluenceTd'> pos </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> mandatory - digit number starting from 1 to ... </td>
</tr>
<tr>
<td class='confluenceTd'> pattern </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - default value = "" - will be used to format Decimal, Date, ... </td>
</tr>
<tr>
<td class='confluenceTd'> length </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> optional - represents the length of the field for fixed length format </td>
</tr>
<tr>
<td class='confluenceTd'> precision </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> optional - represents the precision to be used when the Decimal number will be formatted/parsed </td>
</tr>
<tr>
<td class='confluenceTd'> pattern </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - default value = "" - is used by the Java Formater (SimpleDateFormat by example) to format/validate data </td>
</tr>
<tr>
<td class='confluenceTd'> position </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> optional - must be used when the position of the field in the CSV generated must be different compare to pos </td>
</tr>
<tr>
<td class='confluenceTd'> required </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - default value = "false" </td>
</tr>
<tr>
<td class='confluenceTd'> trim </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - default value = "false" </td>
</tr>
</tbody></table>
</div>


<p><b>case 1 : pos</b></p>

<p>This parameter/attribute represents the position of the field in the csv record</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Position</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>)
<span class="code-keyword">public</span> class Order {

    @DataField(pos = 1)
    <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

    @DataField(pos = 5)
    <span class="code-keyword">private</span> <span class="code-object">String</span> isinCode;

...
}
</pre>
</div></div>

<p>As you can see in this example the position starts at '1' but continues at '5' in the class Order. The numbers from '2' to '4' are defined in the class Client (see here after).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Position continues in another model class</b></div><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Client {

    @DataField(pos = 2)
    <span class="code-keyword">private</span> <span class="code-object">String</span> clientNr;

    @DataField(pos = 3)
    <span class="code-keyword">private</span> <span class="code-object">String</span> firstName;

    @DataField(pos = 4)
    <span class="code-keyword">private</span> <span class="code-object">String</span> lastName;
...
}
</pre>
</div></div>

<p><b>case 2 : pattern</b></p>

<p>The pattern allows to enrich or validates the format of your data</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Pattern</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>)
<span class="code-keyword">public</span> class Order {

    @DataField(pos = 1)
    <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

    @DataField(pos = 5)
    <span class="code-keyword">private</span> <span class="code-object">String</span> isinCode;

    @DataField(name = <span class="code-quote">"Name"</span>, pos = 6)
    <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentName;

    @DataField(pos = 7, precision = 2)
    <span class="code-keyword">private</span> BigDecimal amount;

    @DataField(pos = 8)
    <span class="code-keyword">private</span> <span class="code-object">String</span> currency;

    @DataField(pos = 9, pattern = <span class="code-quote">"dd-MM-yyyy"</span>) -- pattern used during parsing or when the date is created
    <span class="code-keyword">private</span> Date orderDate;
...
}
</pre>
</div></div>

<p><b>case 3 : precision</b></p>

<p>The precision is helpful when you want to define the decimal part of your number</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Precision</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>)
<span class="code-keyword">public</span> class Order {

    @DataField(pos = 1)
    <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

    @Link
    <span class="code-keyword">private</span> Client client;

    @DataField(pos = 5)
    <span class="code-keyword">private</span> <span class="code-object">String</span> isinCode;

    @DataField(name = <span class="code-quote">"Name"</span>, pos = 6)
    <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentName;

    @DataField(pos = 7, precision = 2) -- precision
    <span class="code-keyword">private</span> BigDecimal amount;

    @DataField(pos = 8)
    <span class="code-keyword">private</span> <span class="code-object">String</span> currency;

    @DataField(pos = 9, pattern = <span class="code-quote">"dd-MM-yyyy"</span>)
    <span class="code-keyword">private</span> Date orderDate;
...
}
</pre>
</div></div>

<p><b>case 4 : Position is different in output</b></p>

<p>The position attribute will inform bindy how to place the field in the CSV record generated. By default, the position used corresponds to the position defined with the attribute 'pos'. If the position is different (that means that we have an asymetric processus comparing marshaling from unmarshaling) than we can use 'position' to indicate this.</p>

<p>Here is an example </p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Position is different in output</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>)
<span class="code-keyword">public</span> class Order {
@CsvRecord(separator = <span class="code-quote">","</span>, isOrdered = <span class="code-keyword">true</span>)
<span class="code-keyword">public</span> class Order {

    <span class="code-comment">// Positions of the fields start from 1 and not from 0
</span>
    @DataField(pos = 1, position = 11)
    <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

    @DataField(pos = 2, position = 10)
    <span class="code-keyword">private</span> <span class="code-object">String</span> clientNr;

    @DataField(pos = 3, position = 9)
    <span class="code-keyword">private</span> <span class="code-object">String</span> firstName;

    @DataField(pos = 4, position = 8)
    <span class="code-keyword">private</span> <span class="code-object">String</span> lastName;

    @DataField(pos = 5, position = 7)
    <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentCode;

    @DataField(pos = 6, position = 6)
    <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentNumber;
...
}
</pre>
</div></div>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This attribute of the annotation @DataField must be used in combination with attribute isOrdered = true of the annotation @CsvRecord</td></tr></table></div>


<p><b>case 5 : required</b></p>

<p>If a field is mandatory, simply use the attribute 'required' setted to true</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Required</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>)
<span class="code-keyword">public</span> class Order {

    @DataField(pos = 1)
    <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

    @DataField(pos = 2, required = <span class="code-keyword">true</span>)
    <span class="code-keyword">private</span> <span class="code-object">String</span> clientNr;

    @DataField(pos = 3, required = <span class="code-keyword">true</span>)
    <span class="code-keyword">private</span> <span class="code-object">String</span> firstName;

    @DataField(pos = 4, required = <span class="code-keyword">true</span>)
    <span class="code-keyword">private</span> <span class="code-object">String</span> lastName;
...
}
</pre>
</div></div>

<p>If this field is not present in the record, than an error will be raised by the parser with the following information :</p>

<p>Some fields are missing (optional or mandatory), line : </p>


<p><b>case 6 : trim</b></p>

<p>If a field has leading and/or trailing spaces which should be removed before they are processed, simply use the attribute 'trim' setted to true</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Trim</b></div><div class="codeContent panelContent">
<pre class="code-java">
@CsvRecord(separator = <span class="code-quote">","</span>)
<span class="code-keyword">public</span> class Order {

    @DataField(pos = 1, trim = <span class="code-keyword">true</span>)
    <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

    @DataField(pos = 2, trim = <span class="code-keyword">true</span>)
    <span class="code-keyword">private</span> <span class="code-object">Integer</span> clientNr;

    @DataField(pos = 3, required = <span class="code-keyword">true</span>)
    <span class="code-keyword">private</span> <span class="code-object">String</span> firstName;

    @DataField(pos = 4)
    <span class="code-keyword">private</span> <span class="code-object">String</span> lastName;
...
}
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-4.FixedLengthRecord"></a>4. FixedLengthRecord</h3>

<p>The FixedLengthRecord annotation is used to identified the root class of the model. It represents a record = a line of a file/message containing data fixed length formatted<br/>
 and can be linked to several children model classes. This format is a bit particular beause data of a field can be aligned to the right or to the left. <br/>
 When the size of the data does not fill completely the length of the field, then we add 'padd' characters.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Annotation name </th>
<th class='confluenceTh'> Record type </th>
<th class='confluenceTh'> Level </th>
</tr>
<tr>
<td class='confluenceTd'> <b>FixedLengthRecord</b> </td>
<td class='confluenceTd'> fixed </td>
<td class='confluenceTd'> Class </td>
</tr>
</tbody></table>
</div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter name </th>
<th class='confluenceTh'> type </th>
<th class='confluenceTh'> Info </th>
</tr>
<tr>
<td class='confluenceTd'> crlf </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - default value = WINDOWS - allow to define the carriage return character to use </td>
</tr>
<tr>
<td class='confluenceTd'> paddingChar </td>
<td class='confluenceTd'> char </td>
<td class='confluenceTd'> mandatory - default value = '  ' </td>
</tr>
<tr>
<td class='confluenceTd'> length </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> mandatory = size of the fixed length record </td>
</tr>
<tr>
<td class='confluenceTd'> hasHeader </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - NOT YET IMPLEMENTED </td>
</tr>
<tr>
<td class='confluenceTd'> hasFooter</td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - NOT YET IMPLEMENTED </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>This annotation is associated to the root class of the model and must be declared one time.</td>
</tr>
</tbody></table>
</div>


<p><b>case 1 : Simple fixed length record</b></p>

<p>This simple example shows how to design the model to parse/format a fixed message</p>

<p>10A9PaulineMISINXD12345678BUYShare2500.45USD01-08-2009</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Fixed-simple</b></div><div class="codeContent panelContent">
<pre class="code-java">
   @FixedLengthRecord(length=54, paddingChar=' ')
    <span class="code-keyword">public</span> <span class="code-keyword">static</span> class Order {

        @DataField(pos = 1, length=2)
        <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

        @DataField(pos = 3, length=2)
        <span class="code-keyword">private</span> <span class="code-object">String</span> clientNr;

        @DataField(pos = 5, length=7)
        <span class="code-keyword">private</span> <span class="code-object">String</span> firstName;

        @DataField(pos = 12, length=1, align=<span class="code-quote">"L"</span>)
        <span class="code-keyword">private</span> <span class="code-object">String</span> lastName;

        @DataField(pos = 13, length=4)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentCode;

        @DataField(pos = 17, length=10)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentNumber;

        @DataField(pos = 27, length=3)
        <span class="code-keyword">private</span> <span class="code-object">String</span> orderType;

        @DataField(pos = 30, length=5)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentType;

        @DataField(pos = 35, precision = 2, length=7)
        <span class="code-keyword">private</span> BigDecimal amount;

        @DataField(pos = 42, length=3)
        <span class="code-keyword">private</span> <span class="code-object">String</span> currency;

        @DataField(pos = 45, length=10, pattern = <span class="code-quote">"dd-MM-yyyy"</span>)
        <span class="code-keyword">private</span> Date orderDate;
        ...
</pre>
</div></div>

<p><b>case 2 : Fixed length record with alignment and padding</b></p>

<p>This more elaborated example show how to define the alignment for a field and how to assign a padding character which is ' ' here''</p>

<p>10A9  PaulineM    ISINXD12345678BUYShare2500.45USD01-08-2009</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Fixed-padding-align</b></div><div class="codeContent panelContent">
<pre class="code-java">
   @FixedLengthRecord(length=60, paddingChar=' ')
    <span class="code-keyword">public</span> <span class="code-keyword">static</span> class Order {

        @DataField(pos = 1, length=2)
        <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

        @DataField(pos = 3, length=2)
        <span class="code-keyword">private</span> <span class="code-object">String</span> clientNr;

        @DataField(pos = 5, length=9)
        <span class="code-keyword">private</span> <span class="code-object">String</span> firstName;

        @DataField(pos = 14, length=5, align=<span class="code-quote">"L"</span>)   <span class="code-comment">// align text to the LEFT zone of the block
</span>        <span class="code-keyword">private</span> <span class="code-object">String</span> lastName;

        @DataField(pos = 19, length=4)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentCode;

        @DataField(pos = 23, length=10)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentNumber;

        @DataField(pos = 33, length=3)
        <span class="code-keyword">private</span> <span class="code-object">String</span> orderType;

        @DataField(pos = 36, length=5)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentType;

        @DataField(pos = 41, precision = 2, length=7)
        <span class="code-keyword">private</span> BigDecimal amount;

        @DataField(pos = 48, length=3)
        <span class="code-keyword">private</span> <span class="code-object">String</span> currency;

        @DataField(pos = 51, length=10, pattern = <span class="code-quote">"dd-MM-yyyy"</span>)
        <span class="code-keyword">private</span> Date orderDate;
        ...
</pre>
</div></div>

<p><b>case 3 : Field padding</b></p>

<p>Sometimes, the default padding defined for record cannnot be applied to the field as we have a number format where we would like to padd with '0' instead of ' '. In this case, you can use in the model the attribute paddingField to set this value.</p>

<p>10A9  PaulineM    ISINXD12345678BUYShare000002500.45USD01-08-2009</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Fixed-padding-field</b></div><div class="codeContent panelContent">
<pre class="code-java">
    @FixedLengthRecord(length = 65, paddingChar = ' ')
    <span class="code-keyword">public</span> <span class="code-keyword">static</span> class Order {

        @DataField(pos = 1, length = 2)
        <span class="code-keyword">private</span> <span class="code-object">int</span> orderNr;

        @DataField(pos = 3, length = 2)
        <span class="code-keyword">private</span> <span class="code-object">String</span> clientNr;

        @DataField(pos = 5, length = 9)
        <span class="code-keyword">private</span> <span class="code-object">String</span> firstName;

        @DataField(pos = 14, length = 5, align = <span class="code-quote">"L"</span>)
        <span class="code-keyword">private</span> <span class="code-object">String</span> lastName;

        @DataField(pos = 19, length = 4)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentCode;

        @DataField(pos = 23, length = 10)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentNumber;

        @DataField(pos = 33, length = 3)
        <span class="code-keyword">private</span> <span class="code-object">String</span> orderType;

        @DataField(pos = 36, length = 5)
        <span class="code-keyword">private</span> <span class="code-object">String</span> instrumentType;

        @DataField(pos = 41, precision = 2, length = 12, paddingChar = '0')
        <span class="code-keyword">private</span> BigDecimal amount;

        @DataField(pos = 53, length = 3)
        <span class="code-keyword">private</span> <span class="code-object">String</span> currency;

        @DataField(pos = 56, length = 10, pattern = <span class="code-quote">"dd-MM-yyyy"</span>)
        <span class="code-keyword">private</span> Date orderDate;
        ...
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-5.Message"></a>5. Message</h3>

<p>The Message annotation is used to identified the class of your model who will contain key value pairs fields. This kind of format is used mainly in Financial Exchange Protocol Messages (FIX). Nevertheless, this annotation can be used for any other format where data are identified by keys. The key pair values are separated each other by a separator which can be a special character like a tab delimitor (unicode representation : \u0009) or a start of heading (unicode representation : \u0001)</p>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>"FIX information"</b><br />More information about FIX can be found on this web site : <a href="http://www.fixprotocol.org/" class="external-link" rel="nofollow">http://www.fixprotocol.org/</a>. To work with FIX messages, the model must contain a Header and Trailer classes linked to the root message class which could be a Order class. This is not mandatory but will be very helpful when you will use camel-bindy in combination with camel-fix which is a Fix gateway based on quickFix project <a href="http://www.quickfixj.org/" class="external-link" rel="nofollow">http://www.quickfixj.org/</a>.</td></tr></table></div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Annotation name </th>
<th class='confluenceTh'> Record type </th>
<th class='confluenceTh'> Level </th>
</tr>
<tr>
<td class='confluenceTd'> <b>Message</b> </td>
<td class='confluenceTd'> key value pair </td>
<td class='confluenceTd'> Class </td>
</tr>
</tbody></table>
</div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter name </th>
<th class='confluenceTh'> type </th>
<th class='confluenceTh'> Info </th>
</tr>
<tr>
<td class='confluenceTd'> pairSeparator </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> mandatory - can be '=' or ';' or 'anything' </td>
</tr>
<tr>
<td class='confluenceTd'> keyValuePairSeparair</td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> mandatory - can be '\u0001', '\u0009', '#' or 'anything' </td>
</tr>
<tr>
<td class='confluenceTd'> crlf </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - default value = WINDOWS - allow to define the carriage return character to use </td>
</tr>
<tr>
<td class='confluenceTd'> type </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - define the type of message (e.g. FIX, EMX, ...) </td>
</tr>
<tr>
<td class='confluenceTd'> version </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - version of the message (e.g. 4.1) </td>
</tr>
<tr>
<td class='confluenceTd'> isOrdered </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - default value = false - allow to change the order of the fields when FIX message is generated </td>
</tr>
<tr>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'>This annotation is associated to the message class of the model and must be declared one time.</td>
</tr>
</tbody></table>
</div>


<p><b>case 1 : separator = 'u0001'</b></p>

<p>The separator used to segregate the key value pair fields in a FIX message is the ASCII '01' character or in unicode format '\u0001'. This character must be escaped a second time to avoid a java runtime error. Here is an example :</p>

<p>8=FIX.4.1 9=20 34=1 35=0 49=INVMGR 56=BRKR 1=BE.CHM.001 11=CHM0001-01 22=4 ...</p>

<p>and how to use the annotation</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>FIX - message</b></div><div class="codeContent panelContent">
<pre class="code-java">
@Message(keyValuePairSeparator = <span class="code-quote">"="</span>, pairSeparator = <span class="code-quote">"\u0001"</span>, type=<span class="code-quote">"FIX"</span>, version=<span class="code-quote">"4.1"</span>)
<span class="code-keyword">public</span> class Order {
...
}
</pre>
</div></div>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Look at test cases</b><br />The ASCII character like tab, ... cannot be displayed in WIKI page. So, have a look to the test case of camel-bindy to see exactly how the FIX message looks like (src\test\data\fix\fix.txt) and the Order, Trailer, Header classes (src\test\java\org\apache\camel\dataformat\bindy\model\fix\simple\Order.java)</td></tr></table></div>

<h3><a name="BookDataFormatAppendix-6.KeyValuePairField"></a>6. KeyValuePairField</h3>

<p>The KeyValuePairField annotation defines the property of a key value pair field. Each KeyValuePairField is identified by a tag (= key) and its value associated, a type (string, int, date, ...), optionaly a pattern and if the field is required</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Annotation name </th>
<th class='confluenceTh'> Record type </th>
<th class='confluenceTh'> Level </th>
</tr>
<tr>
<td class='confluenceTd'> <b>KeyValuePairField</b> </td>
<td class='confluenceTd'> Key Value Pair - FIX</td>
<td class='confluenceTd'> Property </td>
</tr>
</tbody></table>
</div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter name </th>
<th class='confluenceTh'> type </th>
<th class='confluenceTh'> Info </th>
</tr>
<tr>
<td class='confluenceTd'> tag </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> mandatory - digit number identifying the field in the message - must be unique </td>
</tr>
<tr>
<td class='confluenceTd'> pattern </td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - default value = "" - will be used to format Decimal, Date, ... </td>
</tr>
<tr>
<td class='confluenceTd'> precision </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> optional - digit number - represents the precision to be used when the Decimal number will be formatted/parsed </td>
</tr>
<tr>
<td class='confluenceTd'> position </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> optional - must be used when the position of the key/tag in the FIX message must be different </td>
</tr>
<tr>
<td class='confluenceTd'> required </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> optional - default value = "false" </td>
</tr>
</tbody></table>
</div>


<p><b>case 1 : tag</b></p>

<p>This parameter represents the key of the field in the message</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>FIX message - Tag</b></div><div class="codeContent panelContent">
<pre class="code-java">
@Message(keyValuePairSeparator = <span class="code-quote">"="</span>, pairSeparator = <span class="code-quote">"\u0001"</span>, type=<span class="code-quote">"FIX"</span>, version=<span class="code-quote">"4.1"</span>)
<span class="code-keyword">public</span> class Order {
    
    @Link Header header;
    
    @Link Trailer trailer;

    @KeyValuePairField(tag = 1) <span class="code-comment">// Client reference
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> Account;

    @KeyValuePairField(tag = 11) <span class="code-comment">// Order reference
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> ClOrdId;
    
    @KeyValuePairField(tag = 22) <span class="code-comment">// Fund ID type (Sedol, ISIN, ...)
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> IDSource;
    
    @KeyValuePairField(tag = 48) <span class="code-comment">// Fund code
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> SecurityId;
    
    @KeyValuePairField(tag = 54) <span class="code-comment">// Movement type ( 1 = Buy, 2 = sell)
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> Side;
    
    @KeyValuePairField(tag = 58) <span class="code-comment">// Free text
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> Text;

...
}
</pre>
</div></div>

<p><b>case 2 : Different position in output</b></p>

<p>If the tags/keys that we will put in the FIX message must be sorted according to a predefine order, then use the attribute 'position' of the annotation @KeyValuePairField</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>FIX message - Tag - sort</b></div><div class="codeContent panelContent">
<pre class="code-java">
@Message(keyValuePairSeparator = <span class="code-quote">"="</span>, pairSeparator = <span class="code-quote">"\\u0001"</span>, type = <span class="code-quote">"FIX"</span>, version = <span class="code-quote">"4.1"</span>, isOrdered = <span class="code-keyword">true</span>)
<span class="code-keyword">public</span> class Order {
    
    @Link Header header;
    
    @Link Trailer trailer;

    @KeyValuePairField(tag = 1, position = 1) <span class="code-comment">// Client reference
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> account;

    @KeyValuePairField(tag = 11, position = 3) <span class="code-comment">// Order reference
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> clOrdId;

...
}
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-7.Section"></a>7. Section</h3>

<p>In FIX message of fixed length records, it is common to have different sections in the representation of the information : header, body and section. The purpose of the annotation @Section is to inform bindy about which class of the model represents the header (= section 1), body (= section 2) and footer (= section 3)</p>

<p>Only one attribute/parameter exists for this annotation.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Annotation name </th>
<th class='confluenceTh'> Record type </th>
<th class='confluenceTh'> Level </th>
</tr>
<tr>
<td class='confluenceTd'> <b>Section</b> </td>
<td class='confluenceTd'> FIX</td>
<td class='confluenceTd'> Class </td>
</tr>
</tbody></table>
</div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter name </th>
<th class='confluenceTh'> type </th>
<th class='confluenceTh'> Info </th>
</tr>
<tr>
<td class='confluenceTd'> number </td>
<td class='confluenceTd'> int </td>
<td class='confluenceTd'> digit number identifying the section position </td>
</tr>
</tbody></table>
</div>


<p><b>case 1 : Section</b></p>

<p>A. Definition of the header section</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>FIX message - Section - Header</b></div><div class="codeContent panelContent">
<pre class="code-java">
@Section(number = 1)
<span class="code-keyword">public</span> class Header {

    @KeyValuePairField(tag = 8, position = 1) <span class="code-comment">// Message Header
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> beginString;

    @KeyValuePairField(tag = 9, position = 2) <span class="code-comment">// Checksum
</span>    <span class="code-keyword">private</span> <span class="code-object">int</span> bodyLength;
...
}
</pre>
</div></div>

<p>B. Definition of the body section</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>FIX message - Section - Body</b></div><div class="codeContent panelContent">
<pre class="code-java">
@Section(number = 2)
@Message(keyValuePairSeparator = <span class="code-quote">"="</span>, pairSeparator = <span class="code-quote">"\\u0001"</span>, type = <span class="code-quote">"FIX"</span>, version = <span class="code-quote">"4.1"</span>, isOrdered = <span class="code-keyword">true</span>)
<span class="code-keyword">public</span> class Order {
    
    @Link Header header;
    
    @Link Trailer trailer;

    @KeyValuePairField(tag = 1, position = 1) <span class="code-comment">// Client reference
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> account;

    @KeyValuePairField(tag = 11, position = 3) <span class="code-comment">// Order reference
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> clOrdId;
</pre>
</div></div>


<p>C. Definition of the footer section</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>FIX message - Section - Footer</b></div><div class="codeContent panelContent">
<pre class="code-java">
@Section(number = 3)
<span class="code-keyword">public</span> class Trailer {

    @KeyValuePairField(tag = 10, position = 1)
    <span class="code-comment">// CheckSum
</span>    <span class="code-keyword">private</span> <span class="code-object">int</span> checkSum;

    <span class="code-keyword">public</span> <span class="code-object">int</span> getCheckSum() {
        <span class="code-keyword">return</span> checkSum;
    }
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-8.OneToMany"></a>8. OneToMany</h3>

<p>The purpose of the annotation @OneToMany is to allow to work with a List&lt;?&gt; field defined a POJO class or from a record containing repetitive groups. </p>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Restrictions OneToMany</b><br />Be careful, the one to many of bindy does not allow to handle repetitions defined on several levels of the hierarchy</td></tr></table></div>

<p>The relation OneToMany ONLY WORKS in the following cases :</p>

<ul class="alternate" type="square">
	<li>Reading a FIX message containing repetitive groups (= group of tags/keys)</li>
	<li>Generating a CSV with repetitive data</li>
</ul>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Annotation name </th>
<th class='confluenceTh'> Record type </th>
<th class='confluenceTh'> Level </th>
</tr>
<tr>
<td class='confluenceTd'> <b>OneToMany</b> </td>
<td class='confluenceTd'> all </td>
<td class='confluenceTd'> property </td>
</tr>
</tbody></table>
</div>


<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Parameter name </th>
<th class='confluenceTh'> type </th>
<th class='confluenceTh'> Info </th>
</tr>
<tr>
<td class='confluenceTd'> mappedTo</td>
<td class='confluenceTd'> string </td>
<td class='confluenceTd'> optional - string - class name associated to the type of the List&lt;Type of the Class&gt; </td>
</tr>
</tbody></table>
</div>


<p><b>case 1 : Generating CSV with repetitive data</b></p>

<p>Here is the CSV output that we want :</p>

<p>Claus,Ibsen,Camel in Action 1,2010,35<br/>
Claus,Ibsen,Camel in Action 2,2012,35<br/>
Claus,Ibsen,Camel in Action 3,2013,35<br/>
Claus,Ibsen,Camel in Action 4,2014,35</p>

<p>Remark : the repetitive data concern the title of the book and its publication date while first, last name and age are common</p>

<p>and the classes used to modeling this. The Author class contains a List of Book.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Generate CSV with repetitive data</b></div><div class="codeContent panelContent">
<pre class="code-java">

@CsvRecord(separator=<span class="code-quote">","</span>)
<span class="code-keyword">public</span> class Author {
	
	@DataField(pos = 1)
	<span class="code-keyword">private</span> <span class="code-object">String</span> firstName;
	
	@DataField(pos = 2)
	<span class="code-keyword">private</span> <span class="code-object">String</span> lastName;
	
	@OneToMany
	<span class="code-keyword">private</span> List&lt;Book&gt; books;

	@DataField(pos = 5)
	<span class="code-keyword">private</span> <span class="code-object">String</span> Age;
...


<span class="code-keyword">public</span> class Book {

	@DataField(pos = 3)
	<span class="code-keyword">private</span> <span class="code-object">String</span> title;
	
	@DataField(pos = 4)
	<span class="code-keyword">private</span> <span class="code-object">String</span> year;
</pre>
</div></div>

<p>Very simple isn't it !!!</p>

<p><b>case 2 : Reading FIX message containing group of tags/keys</b></p>

<p>Here is the message that we would like to process in our model :</p>

<p>"8=FIX 4.19=2034=135=049=INVMGR56=BRKR"<br/>
"1=BE.CHM.00111=CHM0001-0158=this is a camel - bindy test" <br/>
"22=448=BE000124567854=1"<br/>
"22=548=BE000987654354=2" <br/>
"22=648=BE000999999954=3"<br/>
"10=220"</p>

<p>tags 22, 48 and 54 are repeated</p>

<p>and the code</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Reading FIX message containing group of tags/keys</b></div><div class="codeContent panelContent">
<pre class="code-java">

<span class="code-keyword">public</span> class Order {
    
    @Link Header header;
    
    @Link Trailer trailer;

    @KeyValuePairField(tag = 1) <span class="code-comment">// Client reference
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> account;

    @KeyValuePairField(tag = 11) <span class="code-comment">// Order reference
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> clOrdId;
    
    @KeyValuePairField(tag = 58) <span class="code-comment">// Free text
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> text;
    
    @OneToMany(mappedTo = <span class="code-quote">"org.apache.camel.dataformat.bindy.model.fix.complex.onetomany.Security"</span>)
    List&lt;Security&gt; securities;
...

<span class="code-keyword">public</span> class Security {
    
    @KeyValuePairField(tag = 22) <span class="code-comment">// Fund ID type (Sedol, ISIN, ...)
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> idSource;
    
    @KeyValuePairField(tag = 48) <span class="code-comment">// Fund code
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> securityCode;
    
    @KeyValuePairField(tag = 54) <span class="code-comment">// Movement type ( 1 = Buy, 2 = sell)
</span>    <span class="code-keyword">private</span> <span class="code-object">String</span> side;

</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-UsingtheJavaDSL"></a>Using the Java DSL</h3>

<p>The next step consists in instantiating the DataFormat <em>bindy</em> class associated with this record type and providing Java package name(s) as parameter.</p>

<p>For example the following uses the class CsvBindyFormat (who correspond to the class associated with the CSV record type) which is configured with "com.acme.model"<br/>
package name to initialize the model objects configured in this package.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
DataFormat bindy = <span class="code-keyword">new</span> CsvBindyDataFormat(<span class="code-quote">"com.acme.model"</span>);

from(<span class="code-quote">"file:<span class="code-comment">//inbox"</span>).
</span>  unmarshal(bindy).
  to(<span class="code-quote">"bean:handleOrder"</span>);
</pre>
</div></div>
<p>The Camel route will pick-up files in the inbox directory, unmarshall CSV records in a collection of model objects and send the collection<br/>
to the bean referenced by 'handleOrder'.</p>

<p>The collection is a list of Map. Each Map of the list contains the objects of the model. Each object can be retrieve using its class name.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">int</span> count = 0;

    List&lt;Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;&gt; models = <span class="code-keyword">new</span> ArrayList&lt;Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;&gt;();
    Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt; model = <span class="code-keyword">new</span> HashMap&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;();

    models = (List&lt;Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;&gt;) exchange.getIn().getBody();

    Iterator&lt;Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;&gt; it = models.iterator();

    <span class="code-keyword">while</span>(it.hasNext()){

          model = it.next();

	  <span class="code-keyword">for</span>(<span class="code-object">String</span> key : model.keySet()) {
	     <span class="code-object">Object</span> obj = model.get(key);
	     LOG.info(<span class="code-quote">"Count : "</span> + count + <span class="code-quote">", "</span> + obj.toString());
	  }

	 count++;
    }

    LOG.info(<span class="code-quote">"Nber of CSV records received by the csv bean : "</span> + count);
</pre>
</div></div>
<p>To generate CSV records from a collection of model objects, you create the following route :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"bean:handleOrder"</span>)
   marshal(bindy)
   to(<span class="code-quote">"file:<span class="code-comment">//outbox"</span>)</span>
</pre>
</div></div>
<p>You can if you prefer use a named reference to a data format which can then be defined in your <a href="/confluence/display/CAMEL/Registry" title="Registry">Registry</a> such as via your <a href="/confluence/display/CAMEL/Spring" title="Spring">Spring</a> XML file. e.g.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"file:<span class="code-comment">//inbox"</span>).
</span>  unmarshal(<span class="code-quote">"myBindyDataFormat"</span>).
  to(<span class="code-quote">"bean:handleOrder"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Unittest"></a>Unit test</h3>

<p>Here is two examples showing how to marshall or unmarshall a CSV file with Camel</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Marshall</b></div><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">package</span> org.apache.camel.dataformat.bindy.csv;

<span class="code-keyword">import</span> java.math.BigDecimal;
<span class="code-keyword">import</span> java.util.ArrayList;
<span class="code-keyword">import</span> java.util.Calendar;
<span class="code-keyword">import</span> java.util.GregorianCalendar;
<span class="code-keyword">import</span> java.util.HashMap;
<span class="code-keyword">import</span> java.util.List;
<span class="code-keyword">import</span> java.util.Map;

<span class="code-keyword">import</span> org.apache.camel.EndpointInject;
<span class="code-keyword">import</span> org.apache.camel.Produce;
<span class="code-keyword">import</span> org.apache.camel.ProducerTemplate;
<span class="code-keyword">import</span> org.apache.camel.builder.RouteBuilder;
<span class="code-keyword">import</span> org.apache.camel.component.mock.MockEndpoint;
<span class="code-keyword">import</span> org.apache.camel.dataformat.bindy.model.complex.twoclassesandonelink.Client;
<span class="code-keyword">import</span> org.apache.camel.dataformat.bindy.model.complex.twoclassesandonelink.Order;
<span class="code-keyword">import</span> org.apache.camel.spring.javaconfig.SingleRouteCamelConfiguration;
<span class="code-keyword">import</span> org.junit.Test;
<span class="code-keyword">import</span> org.springframework.config.java.annotation.Bean;
<span class="code-keyword">import</span> org.springframework.config.java.annotation.Configuration;
<span class="code-keyword">import</span> org.springframework.config.java.test.JavaConfigContextLoader;
<span class="code-keyword">import</span> org.springframework.test.context.ContextConfiguration;
<span class="code-keyword">import</span> org.springframework.test.context.junit4.AbstractJUnit4SpringContextTests;

@ContextConfiguration(locations = <span class="code-quote">"org.apache.camel.dataformat.bindy.csv.BindyComplexCsvMarshallTest$ContextConfig"</span>, loader = JavaConfigContextLoader.class)
<span class="code-keyword">public</span> class BindyComplexCsvMarshallTest <span class="code-keyword">extends</span> AbstractJUnit4SpringContextTests {

    <span class="code-keyword">private</span> List&lt;Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;&gt; models = <span class="code-keyword">new</span> ArrayList&lt;Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;&gt;();
    <span class="code-keyword">private</span> <span class="code-object">String</span> result = <span class="code-quote">"10,A1,Julia,Roberts,BE123456789,Belgium Ventage 10/12,150,USD,14-01-2009"</span>;

    @Produce(uri = <span class="code-quote">"direct:start"</span>)
    <span class="code-keyword">private</span> ProducerTemplate template;

    @EndpointInject(uri = <span class="code-quote">"mock:result"</span>)
    <span class="code-keyword">private</span> MockEndpoint resultEndpoint;

    @Test
    <span class="code-keyword">public</span> void testMarshallMessage() <span class="code-keyword">throws</span> Exception {
        resultEndpoint.expectedBodiesReceived(result);

        template.sendBody(generateModel());

        resultEndpoint.assertIsSatisfied();
    }

    <span class="code-keyword">private</span> List&lt;Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;&gt; generateModel() {
        Map&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt; model = <span class="code-keyword">new</span> HashMap&lt;<span class="code-object">String</span>, <span class="code-object">Object</span>&gt;();

        Order order = <span class="code-keyword">new</span> Order();
        order.setOrderNr(10);
        order.setAmount(<span class="code-keyword">new</span> BigDecimal(<span class="code-quote">"150"</span>));
        order.setIsinCode(<span class="code-quote">"BE123456789"</span>);
        order.setInstrumentName(<span class="code-quote">"Belgium Ventage 10/12"</span>);
        order.setCurrency(<span class="code-quote">"USD"</span>);

        Calendar calendar = <span class="code-keyword">new</span> GregorianCalendar();
        calendar.set(2009, 0, 14);
        order.setOrderDate(calendar.getTime());

        Client client = <span class="code-keyword">new</span> Client();
        client.setClientNr(<span class="code-quote">"A1"</span>);
        client.setFirstName(<span class="code-quote">"Julia"</span>);
        client.setLastName(<span class="code-quote">"Roberts"</span>);

        order.setClient(client);

        model.put(order.getClass().getName(), order);
        model.put(client.getClass().getName(), client);

        models.add(0, model);

        <span class="code-keyword">return</span> models;
    }

    @Configuration
    <span class="code-keyword">public</span> <span class="code-keyword">static</span> class ContextConfig <span class="code-keyword">extends</span> SingleRouteCamelConfiguration {
        BindyCsvDataFormat camelDataFormat = <span class="code-keyword">new</span> BindyCsvDataFormat(<span class="code-quote">"org.apache.camel.dataformat.bindy.model.complex.twoclassesandonelink"</span>);

        @Override
        @Bean
        <span class="code-keyword">public</span> RouteBuilder route() {
            <span class="code-keyword">return</span> <span class="code-keyword">new</span> RouteBuilder() {
                @Override
                <span class="code-keyword">public</span> void configure() {
                    from(<span class="code-quote">"direct:start"</span>).marshal(camelDataFormat).to(<span class="code-quote">"mock:result"</span>);
                }
            };
        }
    }

}
</pre>
</div></div>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>Unmarshall</b></div><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">package</span> org.apache.camel.dataformat.bindy.csv;

<span class="code-keyword">import</span> org.apache.camel.EndpointInject;
<span class="code-keyword">import</span> org.apache.camel.builder.RouteBuilder;
<span class="code-keyword">import</span> org.apache.camel.component.mock.MockEndpoint;
<span class="code-keyword">import</span> org.apache.camel.spring.javaconfig.SingleRouteCamelConfiguration;
<span class="code-keyword">import</span> org.junit.Test;
<span class="code-keyword">import</span> org.springframework.config.java.annotation.Bean;
<span class="code-keyword">import</span> org.springframework.config.java.annotation.Configuration;
<span class="code-keyword">import</span> org.springframework.config.java.test.JavaConfigContextLoader;
<span class="code-keyword">import</span> org.springframework.test.context.ContextConfiguration;
<span class="code-keyword">import</span> org.springframework.test.context.junit4.AbstractJUnit4SpringContextTests;

@ContextConfiguration(locations = <span class="code-quote">"org.apache.camel.dataformat.bindy.csv.BindyComplexCsvUnmarshallTest$ContextConfig"</span>, loader = JavaConfigContextLoader.class)
<span class="code-keyword">public</span> class BindyComplexCsvUnmarshallTest <span class="code-keyword">extends</span> AbstractJUnit4SpringContextTests {

    @EndpointInject(uri = <span class="code-quote">"mock:result"</span>)
    <span class="code-keyword">private</span> MockEndpoint resultEndpoint;

    @Test
    <span class="code-keyword">public</span> void testUnMarshallMessage() <span class="code-keyword">throws</span> Exception {
        resultEndpoint.expectedMessageCount(1);
        resultEndpoint.assertIsSatisfied();
    }

    @Configuration
    <span class="code-keyword">public</span> <span class="code-keyword">static</span> class ContextConfig <span class="code-keyword">extends</span> SingleRouteCamelConfiguration {
        BindyCsvDataFormat csvBindyDataFormat = <span class="code-keyword">new</span> BindyCsvDataFormat(<span class="code-quote">"org.apache.camel.dataformat.bindy.model.complex.twoclassesandonelink"</span>);

        @Override
        @Bean
        <span class="code-keyword">public</span> RouteBuilder route() {
            <span class="code-keyword">return</span> <span class="code-keyword">new</span> RouteBuilder() {
                @Override
                <span class="code-keyword">public</span> void configure() {
                    from(<span class="code-quote">"file:<span class="code-comment">//src/test/data?noop=<span class="code-keyword">true</span>"</span>).unmarshal(csvBindyDataFormat).to(<span class="code-quote">"mock:result"</span>);
</span>                }
            };
        }
    }

}
</pre>
</div></div>

<p>In this example, BindyCsvDataFormat class has been instantiated in a traditional way but it is also possible to provide information directly to the function (un)marshal like this where BindyType corresponds to the Bindy DataFormat class to instantiate and the parameter contains the list of package names.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
    <span class="code-keyword">public</span> <span class="code-keyword">static</span> class ContextConfig <span class="code-keyword">extends</span> SingleRouteCamelConfiguration {
        @Override
        @Bean
        <span class="code-keyword">public</span> RouteBuilder route() {
            <span class="code-keyword">return</span> <span class="code-keyword">new</span> RouteBuilder() {
                @Override
                <span class="code-keyword">public</span> void configure() {
                    from(<span class="code-quote">"direct:start"</span>)
                    .marshal().bindy(BindyType.Csv, <span class="code-quote">"org.apache.camel.dataformat.bindy.model.simple.oneclass"</span>)
                    .to(<span class="code-quote">"mock:result"</span>);
                }
            };
        }
    }
</pre>
</div></div> 

<h3><a name="BookDataFormatAppendix-UsingSpringXML"></a>Using Spring XML</h3>

<p>This is really easy to use Spring as your favorite DSL language to declare the routes to be used for camel-bindy. The following example shows two routes where the first will pick-up records from files, unmarshal the content and bind it to their model. The result is then send to a pojo (doing nothing special) and place them into a queue.</p>

<p>The second route will extract the pojos from the queue and marshal the content to generate a file containing the csv record</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>spring dsl</b></div><div class="codeContent panelContent">
<pre class="code-java">
&lt;?xml version=<span class="code-quote">"1.0"</span> encoding=<span class="code-quote">"UTF-8"</span>?&gt;

&lt;beans xmlns=<span class="code-quote">"http:<span class="code-comment">//www.springframework.org/schema/beans"</span>
</span>	xmlns:xsi=<span class="code-quote">"http:<span class="code-comment">//www.w3.org/2001/XMLSchema-instance"</span>
</span>	xsi:schemaLocation="
       http:<span class="code-comment">//www.springframework.org/schema/beans
</span>       http:<span class="code-comment">//www.springframework.org/schema/beans/spring-beans.xsd
</span>       http:<span class="code-comment">//camel.apache.org/schema/spring
</span>       http:<span class="code-comment">//camel.apache.org/schema/spring/camel-spring.xsd"&gt;
</span>
	&lt;bean id=<span class="code-quote">"bindyDataformat"</span> class=<span class="code-quote">"org.apache.camel.dataformat.bindy.csv.BindyCsvDataFormat"</span>&gt;
		&lt;constructor-arg value=<span class="code-quote">"org.apache.camel.bindy.model"</span> /&gt;
	&lt;/bean&gt;

	&lt;bean id=<span class="code-quote">"csv"</span> class=<span class="code-quote">"org.apache.camel.bindy.csv.HandleOrderBean"</span> /&gt;

       
        &lt;!-- Queuing engine - ActiveMq - work locally in mode virtual memory --&gt;
	&lt;bean id=<span class="code-quote">"activemq"</span> class=<span class="code-quote">"org.apache.activemq.camel.component.ActiveMQComponent"</span>&gt;
		&lt;property name=<span class="code-quote">"brokerURL"</span> value=<span class="code-quote">"vm:<span class="code-comment">//localhost:61616"</span>/&gt;
</span>	&lt;/bean&gt;


	&lt;camelContext xmlns=<span class="code-quote">"http:<span class="code-comment">//camel.apache.org/schema/spring"</span>&gt;
</span>		&lt;jmxAgent id=<span class="code-quote">"agent"</span> disabled=<span class="code-quote">"<span class="code-keyword">false</span>"</span> /&gt;

		&lt;route&gt;
			&lt;from uri=<span class="code-quote">"file:<span class="code-comment">//src/data/csv/?noop=<span class="code-keyword">true</span>"</span> /&gt;
</span>			&lt;unmarshal ref=<span class="code-quote">"bindyDataformat"</span> /&gt;
			&lt;to uri=<span class="code-quote">"bean:csv"</span> /&gt;
			&lt;to uri=<span class="code-quote">"activemq:queue:in"</span> /&gt;
		&lt;/route&gt;
		
		&lt;route&gt;
			&lt;from uri=<span class="code-quote">"activemq:queue:in"</span> /&gt;
			&lt;marshal ref=<span class="code-quote">"bindyDataformat"</span> /&gt;
			&lt;to uri=<span class="code-quote">"file:<span class="code-comment">//src/data/csv/out/"</span> /&gt;
</span>		&lt;/route&gt;
	&lt;/camelContext&gt;
&lt;/beans&gt;
</pre>
</div></div>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Be careful</b><br />Please verify that your model classes implements serializable otherwise the queue manager will raise an error</td></tr></table></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use Bindy in your camel routes you need to add the a dependency on <b>camel-bindy</b> which implements this data format.</p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-bindy&lt;/artifactId&gt;
  &lt;version&gt;2.1.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>
<h2><a name="BookDataFormatAppendix-XMLSecurityDataFormat"></a>XMLSecurity Data Format</h2>
<p><b>Available as of Camel 2.0</b></p>

<p>The XMLSecurity DataFormat facilitates encryption and decryption of XML payloads at the Document, Element and Element Content levels (including simultaneous multi-node encryption/decryption using XPATH).</p>

<p>The encrytion capability is based on formats supported using the Apache XML Security (Santaurio) project. Encryption/Decryption is "currently" supported using Triple-DES and AES (128, 192 and 256) encryption formats. Additional formats can be easily added later as needed. &nbsp;(Note: The support currently offered is for symmetric encryption. This means the same keyset is needed at both ends of the communication to encrypt/decrypt payloads).</p>

<p>The capability allows Camel users to encrypt/decrypt payloads while being dispatched or received along a route.&nbsp;</p>

<h3><a name="BookDataFormatAppendix-Options"></a>Options</h3>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> secureTag </td>
<td class='confluenceTd'> null </td>
<td class='confluenceTd'> The XPATH reference to the XML Element selected for encryption/decryption. If no tag is specified, the entire payload is encrypted/decrypted. </td>
</tr>
<tr>
<td class='confluenceTd'> secureTagContents </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> A boolean value to specify whether the XML Element is to be encrypted or the contents of the XML Element
<ul>
	<li><tt>false</tt> = Element Level</li>
	<li><tt>true</tt> = Element Content Level</li>
</ul>
</td>
</tr>
<tr>
<td class='confluenceTd'> passPhrase </td>
<td class='confluenceTd'> null </td>
<td class='confluenceTd'> A String used as passPhrase to encrypt/decrypt content. The passPhrase has to be provided. If no passPhrase is specified, a default passPhrase is used. The passPhrase needs to be put together in conjunction with the appropriate encryption algorithm. For example using <tt>TRIPLEDES</tt> the passPhase can be a <tt>"Only another 24 Byte key"</tt> </td>
</tr>
<tr>
<td class='confluenceTd'> xmlCipherAlgorithm </td>
<td class='confluenceTd'> TRIPLEDES </td>
<td class='confluenceTd'> The cipher algorithm to be used for encryption/decryption. The available choices are:
<ul>
	<li><tt>XMLCipher.TRIPLEDES</tt></li>
	<li><tt>XMLCipher.AES_128</tt></li>
	<li><tt>XMLCipher.AES_192</tt></li>
	<li><tt>XMLCipher.AES_256</tt></li>
</ul>
</td>
</tr>
</tbody></table>
</div>


<h3><a name="BookDataFormatAppendix-Marshal"></a>Marshal</h3>
<p>In order to encrypt the payload, the marshal processor needs to be applied on the route followed by the <b>secureXML()</b> tag.</p>

<h3><a name="BookDataFormatAppendix-Unmarshal"></a>Unmarshal</h3>
<p>In order to decrypt the payload, the unmarshal processor needs to be applied on the route followed by the <b>secureXML()</b> tag.</p>

<h3><a name="BookDataFormatAppendix-Examples"></a>Examples</h3>
<p>Given below are several examples of how marshalling could be performaed at the Document, Element and Content levels.</p>

<h4><a name="BookDataFormatAppendix-FullPayloadencryption%2Fdecryption"></a>Full Payload encryption/decryption</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"direct:start"</span>).
    marshal().secureXML().
    unmarshal().secureXML().
to(<span class="code-quote">"direct:end"</span>);
</pre>
</div></div>

<h4><a name="BookDataFormatAppendix-PartialPayloadContentOnlyencryption%2Fdecryption"></a>Partial Payload Content Only encryption/decryption*</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> tagXPATH = <span class="code-quote">"<span class="code-comment">//cheesesites/italy/cheese"</span>;
</span><span class="code-object">boolean</span> secureTagContent = <span class="code-keyword">true</span>;
...
from(<span class="code-quote">"direct:start"</span>).
    marshal().secureXML(tagXPATH , secureTagContent ).
    unmarshal().secureXML(tagXPATH , secureTagContent).
to(<span class="code-quote">"direct:end"</span>);
</pre>
</div></div>

<h4><a name="BookDataFormatAppendix-PartialMultiNodePayloadContentOnlyencryption%2Fdecryption"></a>Partial Multi Node Payload Content Only encryption/decryption*</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> tagXPATH = <span class="code-quote">"<span class="code-comment">//cheesesites/*/cheese"</span>;
</span><span class="code-object">boolean</span> secureTagContent = <span class="code-keyword">true</span>;
....
from(<span class="code-quote">"direct:start"</span>).
    marshal().secureXML(tagXPATH , secureTagContent ).
    unmarshal().secureXML(tagXPATH , secureTagContent).
to(<span class="code-quote">"direct:end"</span>);
</pre>
</div></div>

<h4><a name="BookDataFormatAppendix-PartialPayloadContentOnlyencryption%2FdecryptionwithchoiceofpassPhrase%28password%29"></a>Partial Payload Content Only encryption/decryption with choice of passPhrase(password)*</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> tagXPATH = <span class="code-quote">"<span class="code-comment">//cheesesites/italy/cheese"</span>;
</span><span class="code-object">boolean</span> secureTagContent = <span class="code-keyword">true</span>;
....
<span class="code-object">String</span> passPhrase = <span class="code-quote">"Just another 24 <span class="code-object">Byte</span> key"</span>;
from(<span class="code-quote">"direct:start"</span>).
    marshal().secureXML(tagXPATH , secureTagContent , passPhrase).
    unmarshal().secureXML(tagXPATH , secureTagContent, passPhrase).
to(<span class="code-quote">"direct:end"</span>);
</pre>
</div></div>

<h4><a name="BookDataFormatAppendix-PartialPayloadContentOnlyencryption%2FdecryptionwithpassPhrase%28password%29andAlgorithm%26nbsp%3B"></a>Partial Payload Content Only encryption/decryption with passPhrase(password) and Algorithm*&nbsp;</h4>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">import</span> org.apache.xml.security.encryption.XMLCipher;
....
<span class="code-object">String</span> tagXPATH = <span class="code-quote">"<span class="code-comment">//cheesesites/italy/cheese"</span>;
</span><span class="code-object">boolean</span> secureTagContent = <span class="code-keyword">true</span>;
<span class="code-object">String</span> passPhrase = <span class="code-quote">"Just another 24 <span class="code-object">Byte</span> key"</span>;
<span class="code-object">String</span> algorithm= XMLCipher.TRIPLEDES;
from(<span class="code-quote">"direct:start"</span>).
    marshal().secureXML(tagXPATH , secureTagContent , passPhrase, algorithm).
    unmarshal().secureXML(tagXPATH , secureTagContent, passPhrase, algorithm).
to(<span class="code-quote">"direct:end"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>This data format is provided in the <b>camel-xmlsecurity</b> component.</p>
<p>The GZip <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> is a message compression and de-compression format. It uses the same deflate algorithm that is used in <a href="/confluence/display/CAMEL/Zip+DataFormat" title="Zip DataFormat">Zip DataFormat</a>, although some additional headers are provided. This format is produced by popular <tt>gzip</tt>/<tt>gunzip</tt> tool. Messages marshalled using GZip compression can be unmarshalled using GZip decompression just prior to being consumed at the endpoint. The compression capability is quite useful when you deal with large XML and Text based payloads or when you read messages previously comressed using <tt>gzip</tt> tool.</p>

<h3><a name="BookDataFormatAppendix-Options"></a>Options</h3>

<p>There are no options provided for this data format.</p>

<h3><a name="BookDataFormatAppendix-Marshal"></a>Marshal</h3>

<p>In this example we marshal a regular text/XML payload to a compressed payload employing gzip compression format and send it an ActiveMQ queue called MY_QUEUE.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"direct:start"</span>).marshal().gzip().to(<span class="code-quote">"activemq:queue:MY_QUEUE"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Unmarshal"></a>Unmarshal</h3>

<p>In this example we unmarshal&nbsp;a gzipped&nbsp;payload from an ActiveMQ queue called MY_QUEUE&nbsp;to its original format,&nbsp;and forward it for&nbsp;processing&nbsp;to the <tt>UnGZippedMessageProcessor</tt>. </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:queue:MY_QUEUE"</span>).unmarshal().gzip().process(<span class="code-keyword">new</span> UnGZippedMessageProcessor()); 
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>This data format is provided in <b>camel-core</b> so no additional dependencies is needed.</p>
<h2><a name="BookDataFormatAppendix-Castor"></a>Castor</h2>
<p><b>Available as of Camel 2.1</b></p>

<p>Castor is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> which uses the <a href="http://www.castor.org/" class="external-link" rel="nofollow">Castor XML library</a> to unmarshal an XML payload into Java objects or to marshal Java objects into an XML payload.</p>

<p>As usually you can use either Java DSL or Spring XML to work with Castor Data Format. </p>

<h3><a name="BookDataFormatAppendix-UsingtheJavaDSL"></a>Using the Java DSL</h3>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"direct:order"</span>).
  marshal().castor().
  to(<span class="code-quote">"activemq:queue:order"</span>);
</pre>
</div></div>

<p>For example the following uses a named DataFormat of Castor which uses default Castor data binding features.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
CastorDataFormat castor = <span class="code-keyword">new</span> CastorDataFormat ();

from(<span class="code-quote">"activemq:My.Queue"</span>).
  unmarshal(castor).
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>



<p>If you prefer to use a named reference to a data format which can then be defined in your Registry such as via your Spring XML file. e.g.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
from(<span class="code-quote">"activemq:My.Queue"</span>).
  unmarshal(<span class="code-quote">"mycastorType"</span>).
  to(<span class="code-quote">"mqseries:Another.Queue"</span>);
</pre>
</div></div>



<p>If you want to override default mapping schema by providing a mapping file you can set it as follows.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
CastorDataFormat castor = <span class="code-keyword">new</span> CastorDataFormat ();
castor.setMappingFile(<span class="code-quote">"mapping.xml"</span>);
</pre>
</div></div>


<p>Also if you want to have more control on Castor Marshaller and Unmarshaller you can access them as below.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
castor.getMarshaller();
castor.getUnmarshaller();
</pre>
</div></div>



<h3><a name="BookDataFormatAppendix-UsingSpringXML"></a>Using Spring XML</h3>
<p>The following example shows how to use Castor to unmarshal using Spring configuring the castor data type</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http:<span class="code-comment">//camel.apache.org/schema/spring"</span>&gt;
</span>  &lt;route&gt;
    &lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;
    &lt;unmarshal&gt;
      &lt;castor validation=<span class="code-quote">"<span class="code-keyword">true</span>"</span> /&gt;
    &lt;/unmarshal&gt;
    &lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;
  &lt;/route&gt;
&lt;/camelContext&gt;
</pre>
</div></div>

<p>This example shows how to configure the data type just once and reuse it on multiple routes. You have to set the &lt;castor&gt; element directly in &lt;camelContext&gt;.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;camelContext&gt;
&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http:<span class="code-comment">//camel.apache.org/schema/spring"</span>&gt;
</span>  &lt;dataFormats&gt;
    &lt;castor id=<span class="code-quote">"myCastor"</span>/&gt;
  &lt;/dataFormats&gt;

  &lt;route&gt;
    &lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;
    &lt;marshal ref=<span class="code-quote">"myCastor"</span>/&gt;
    &lt;to uri=<span class="code-quote">"direct:marshalled"</span>/&gt;
  &lt;/route&gt;
  &lt;route&gt;
    &lt;from uri=<span class="code-quote">"direct:marshalled"</span>/&gt;
    &lt;unmarshal ref=<span class="code-quote">"myCastor"</span>/&gt;
    &lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;
  &lt;/route&gt;

&lt;/camelContext&gt;
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-Options"></a>Options</h3>
<p>Castor supports the following options</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Option </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> encoding </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> UTF-8 </td>
<td class='confluenceTd'> Encoding to use when marshalling an Object to XML </td>
</tr>
<tr>
<td class='confluenceTd'> validation </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> Whether validation is turned on or off. </td>
</tr>
<tr>
<td class='confluenceTd'> mappingFile </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> null </td>
<td class='confluenceTd'> Path to a Castor mapping file to load from the classpath. </td>
</tr>
<tr>
<td class='confluenceTd'> packages </td>
<td class='confluenceTd'> String[] </td>
<td class='confluenceTd'> null </td>
<td class='confluenceTd'> Add additional packages to Castor XmlContext </td>
</tr>
<tr>
<td class='confluenceTd'> classNames </td>
<td class='confluenceTd'> String[] </td>
<td class='confluenceTd'> null </td>
<td class='confluenceTd'> Add additional class names to Castor XmlContext </td>
</tr>
</tbody></table>
</div>


<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use Castor in your camel routes you need to add the a dependency on <b>camel-castor</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-castor&lt;/artifactId&gt;
  &lt;version&gt;2.1.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>
<h1><a name="BookDataFormatAppendix-ProtobufProtocolBuffers"></a>Protobuf - Protocol Buffers</h1>

<p>"Protocol Buffers - Google's data interchange format"</p>

<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Available from Camel 2.2</td></tr></table></div>

<p>Camel provides a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> to serialse between Java and the Protocol Buffer protocol.  The project's site details why you may wish to <a href="http://code.google.com/apis/protocolbuffers/docs/overview.html" class="external-link" rel="nofollow">choose this format over xml</a>.  Protocol Buffer is language-neutral and platform-neutral, so messages produced by your Camel routes may be consumed by other language implementations.</p>

<p><a href="http://code.google.com/apis/protocolbuffers/" class="external-link" rel="nofollow">API Site</a><br/>
<a href="http://code.google.com/p/protobuf/" class="external-link" rel="nofollow">Protobuf Implementation</a><br/>
<a href="http://code.google.com/apis/protocolbuffers/docs/javatutorial.html" class="external-link" rel="nofollow">Protobuf Java Tutorial</a></p>

<h2><a name="BookDataFormatAppendix-Protobufoverview"></a>Protobuf overview</h2>

<p>This quick overview of how to use Protobuf. For more detail see the <a href="http://code.google.com/apis/protocolbuffers/docs/javatutorial.html" class="external-link" rel="nofollow">complete tutorial</a></p>

<h3><a name="BookDataFormatAppendix-Definingtheprotoformat"></a>Defining the proto format</h3>

<p>The first step is to define the format for the body of your exchange.  This is defined in a .proto file as so:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader" style="border-bottom-width: 1px;"><b>addressbook.proto</b></div><div class="codeContent panelContent">
<pre class="code-java">

<span class="code-keyword">package</span> org.apache.camel.component.protobuf;

option java_package = <span class="code-quote">"org.apache.camel.component.protobuf"</span>;
option java_outer_classname = <span class="code-quote">"AddressBookProtos"</span>;

message Person {
  required string name = 1;
  required int32 id = 2;
  optional string email = 3;

  <span class="code-keyword">enum</span> PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
  }

  message PhoneNumber {
    required string number = 1;
    optional PhoneType type = 2 [<span class="code-keyword">default</span> = HOME];
  }

  repeated PhoneNumber phone = 4;
}

message AddressBook {
  repeated Person person = 1;
}

</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-GeneratingJavaclasses"></a>Generating Java classes</h3>

<p>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.</p>

<p><tt>protoc --java_out=. ./addressbook.proto</tt></p>

<p>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 <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> 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.</p>

<h2><a name="BookDataFormatAppendix-JavaDSL"></a>Java DSL</h2>

<p>You can use create the ProtobufDataFormat instance and pass it to Camel DataFormat marshal and unmarsha API like this.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   ProtobufDataFormat format = <span class="code-keyword">new</span> ProtobufDataFormat(Person.getDefaultInstance());

   from(<span class="code-quote">"direct:in"</span>).marshal(format);
   from(<span class="code-quote">"direct:back"</span>).unmarshal(format).to(<span class="code-quote">"mock:reverse"</span>);
</pre>
</div></div>

<p>Or use the DSL protobuf() passing the unmarshal default instance or default instance class name like this.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
   <span class="code-comment">// You don't need to specify the <span class="code-keyword">default</span> instance <span class="code-keyword">for</span> protobuf marshaling               
</span>   from(<span class="code-quote">"direct:marshal"</span>).marshal().protobuf();
   from(<span class="code-quote">"direct:unmarshalA"</span>).unmarshal().
       protobuf(<span class="code-quote">"org.apache.camel.dataformat.protobuf.generated.AddressBookProtos$Person"</span>).
       to (<span class="code-quote">"mock:reverse"</span>);
                
   from(<span class="code-quote">"direct:unmarshalB"</span>).unmarshal().protobuf(Person.getDefaultInstance()).to(<span class="code-quote">"mock:reverse"</span>);
</pre>
</div></div>


<h2><a name="BookDataFormatAppendix-SpringDSL"></a>Spring DSL</h2>

<p>The following example shows how to use Castor to unmarshal using Spring configuring the protobuf data type</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http:<span class="code-comment">//camel.apache.org/schema/spring"</span>&gt;
</span>  &lt;route&gt;
    &lt;from uri=<span class="code-quote">"direct:start"</span>/&gt;
    &lt;unmarshal&gt;
      &lt;protobuf instanceClass=<span class="code-quote">"org.apache.camel.dataformat.protobuf.generated.AddressBookProtos$Person"</span> /&gt;
    &lt;/unmarshal&gt;
    &lt;to uri=<span class="code-quote">"mock:result"</span>/&gt;
  &lt;/route&gt;
&lt;/camelContext&gt;
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use Protobuf in your camel routes you need to add the a dependency on <b>camel-protobuf</b> which implements this data format. </p>

<p>If you use maven you could just add the following to your pom.xml, substituting the version number for the latest &amp; greatest release (see <a href="/confluence/display/CAMEL/Download" title="Download">the download page for the latest versions</a>).</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.camel&lt;/groupId&gt;
  &lt;artifactId&gt;camel-protobuf&lt;/artifactId&gt;
  &lt;version&gt;2.2.0&lt;/version&gt;
&lt;/dependency&gt;
</pre>
</div></div>
<h2><a name="BookDataFormatAppendix-SOAPDataFormat"></a>SOAP DataFormat</h2>
<p><b>Available as of Camel 2.3</b></p>

<p>SOAP is a <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> which uses JAXB2 and JAX-WS annotations to marshal and unmarshal SOAP payloads. It provides the basic features of Apache CXF without need for the CXF Stack.</p>

<h3><a name="BookDataFormatAppendix-ElementNameStrategy"></a>ElementNameStrategy</h3>

<p>An element name strategy is used for two purposes. The first is to find a xml element name for a given object and soap action when marshalling the object into a SOAP message. The second is to find an Exception class for a given soap fault name.</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Strategy </th>
<th class='confluenceTh'> Usage </th>
</tr>
<tr>
<td class='confluenceTd'> QNameStrategy </td>
<td class='confluenceTd'> Uses a fixed qName that is configured on instantiation. Exception lookup is not supported </td>
</tr>
<tr>
<td class='confluenceTd'> TypeNameStrategy </td>
<td class='confluenceTd'> Uses the name and namespace from the @XMLType annotation of the given type. If no namespace is set then package-info is used. Exception lookup is not supported </td>
</tr>
<tr>
<td class='confluenceTd'> ServiceInterfaceStrategy </td>
<td class='confluenceTd'> Uses information from a webservice interface to determine the type name and to find the exception class for a SOAP fault</td>
</tr>
</tbody></table>
</div>


<p>If you have generated the web service stub code with cxf-codegen or a similar tool then you probably will want to use the ServiceInterfaceStrategy. In the case you have no annotated service interface you should use QNameStrategy or TypeNameStrategy.</p>

<h3><a name="BookDataFormatAppendix-UsingtheJavaDSL"></a>Using the Java DSL</h3>

<p>The following example uses a named DataFormat of <em>soap</em> which is configured with the package com.example.customerservice to initialize the <a href="http://java.sun.com/javase/6/docs/api/javax/xml/bind/JAXBContext.html" class="external-link" rel="nofollow">JAXBContext</a>. The second parameter is the ElementNameStrategy. The route is able to marshal normal objects as well as exceptions.  (Note the below just sends a SOAP Envelope to a queue. A web service provider would actually need to be listening to the queue for a SOAP call to actually occur, in which case it would be a one way SOAP request. If you need request reply then you should look at the next example.)</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
SoapJaxbDataFormat soap = <span class="code-keyword">new</span> SoapJaxbDataFormat(<span class="code-quote">"com.example.customerservice"</span>, <span class="code-keyword">new</span> ServiceInterfaceStrategy(CustomerService.class));
from(<span class="code-quote">"direct:start"</span>)
  .marshal(soap)
  .to(<span class="code-quote">"jms:myQueue"</span>);
</pre>
</div></div>

<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>See also</b><br />As the SOAP dataformat inherits from the <a href="/confluence/display/CAMEL/JAXB" title="JAXB">JAXB</a> dataformat most settings apply here as well</td></tr></table></div>

<h3><a name="BookDataFormatAppendix-Examples"></a>Examples</h3>

<h4><a name="BookDataFormatAppendix-Webserviceclient"></a>Webservice client</h4>

<p>The following route supports marshalling the request and unmarshalling a response or fault. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">String</span> WS_URI = <span class="code-quote">"cxf:<span class="code-comment">//http://myserver/customerservice?serviceClass=com.example.customerservice&amp;dataFormat=MESSAGE"</span>;
</span>SoapJaxbDataFormat soapDF = <span class="code-keyword">new</span> SoapJaxbDataFormat(<span class="code-quote">"com.example.customerservice"</span>, <span class="code-keyword">new</span> ServiceInterfaceStrategy(CustomerService.class));
from(<span class="code-quote">"direct:customerServiceClient"</span>)
  .onException(Exception.class)
    .handled(<span class="code-keyword">true</span>)
    .unmarshal(soapDF)
  .end()
  .marshal(soapDF)
  .to(WS_URI)
  .unmarshal(soapDF);
</pre>
</div></div>

<p>The below snippet creates a proxy for the service interface and makes a SOAP call to the above route. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">import</span> org.apache.camel.Endpoint;
<span class="code-keyword">import</span> org.apache.camel.component.bean.ProxyHelper;
...

Endpoint startEndpoint = context.getEndpoint(<span class="code-quote">"direct:customerServiceClient"</span>);
<span class="code-object">ClassLoader</span> classLoader = <span class="code-object">Thread</span>.currentThread().getContextClassLoader();
<span class="code-comment">// CustomerService below is the service endpoint <span class="code-keyword">interface</span>, *not* the javax.xml.ws.Service subclass
</span>CustomerService proxy = ProxyHelper.createProxy(startEndpoint, classLoader, CustomerService.class);
GetCustomersByNameResponse response = proxy.getCustomersByName(<span class="code-keyword">new</span> GetCustomersByName());
</pre>
</div></div>

<h4><a name="BookDataFormatAppendix-WebserviceServer"></a>Webservice Server</h4>

<p>Using the following route sets up a webservice server that listens on jms queue customerServiceQueue and processes requests using the class CustomerServiceImpl. The customerServiceImpl of course should implement the interface CustomerService. Instead of directly instantiating the server class it could be defined in a spring context as a regular bean.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
SoapJaxbDataFormat soapDF = <span class="code-keyword">new</span> SoapJaxbDataFormat(<span class="code-quote">"com.example.customerservice"</span>, <span class="code-keyword">new</span> ServiceInterfaceStrategy(CustomerService.class));
CustomerService serverBean = <span class="code-keyword">new</span> CustomerServiceImpl();
from(<span class="code-quote">"jms:<span class="code-comment">//queue:customerServiceQueue"</span>)
</span>  .onException(Exception.class)
    .handled(<span class="code-keyword">true</span>)
    .marshal(soapDF)
  .end()
  .unmarshal(soapDF)
  .bean(serverBean)
  .marshal(soapDF);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use the SOAP dataformat in your camel routes you need to add the following dependency to your pom.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependency&gt;</span>
  <span class="code-tag">&lt;groupId&gt;</span>org.apache.camel<span class="code-tag">&lt;/groupId&gt;</span>
  <span class="code-tag">&lt;artifactId&gt;</span>camel-soap<span class="code-tag">&lt;/artifactId&gt;</span>
  <span class="code-tag">&lt;version&gt;</span>2.3.0<span class="code-tag">&lt;/version&gt;</span>
<span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>
<h2><a name="BookDataFormatAppendix-Crypto"></a>Crypto</h2>
<p><b>Available as of Camel 2.3</b></p>

<p>The Crypto <a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a> integrates the Java Cryptographic Extension into Camel, allowing simple and flexible encryption and decryption of messages using Camel's familiar marshall and unmarshal formatting mechanism. It assumes marshalling to mean encryption to cyphertext and unmarshalling decryption back to the original plaintext.</p>

<h3><a name="BookDataFormatAppendix-Options"></a>Options</h3>
<div class="confluenceTableSmall"><div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Name </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>algorithm</tt> </td>
<td class='confluenceTd'> <tt>String</tt> </td>
<td class='confluenceTd'> <tt>DES/CBC/PKCS5Padding</tt> </td>
<td class='confluenceTd'> The JCE algoorithm name indicating the cryptographic algorithm that will be used. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>algorithmParamterSpec</tt> </td>
<td class='confluenceTd'> <tt>AlgorithmParameterSpec</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'>A JCE AlgorithmParameterSpec used to initialize the Cipher. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>bufferSize</tt> </td>
<td class='confluenceTd'> <tt>Integer</tt> </td>
<td class='confluenceTd'> <tt>2048</tt> </td>
<td class='confluenceTd'> the size of the buffer used in the signature process. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>cryptoProvider</tt> </td>
<td class='confluenceTd'> <tt>String</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> The name of the JCE Security Provider that should be used. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>initializationVector</tt> </td>
<td class='confluenceTd'> <tt>byte[]</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> A byte array containing the Initialization Vector that will be used to initialize the Cipher. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>inline</tt> </td>
<td class='confluenceTd'> <tt>boolean</tt> </td>
<td class='confluenceTd'> <tt>false</tt> </td>
<td class='confluenceTd'> Flag indicating that the configured IV should be inlined into the encrypted data stream. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>macAlgorithm</tt> </td>
<td class='confluenceTd'> <tt>String</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> The JCE algorithm name indicating the Message Authentication algorithm. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>shouldAppendHMAC</tt> </td>
<td class='confluenceTd'> <tt>boolean</tt> </td>
<td class='confluenceTd'> <tt>null</tt> </td>
<td class='confluenceTd'> Flag indicating that a Message Authentication Code should be calculated and appended to the encrypted data.</td>
</tr>
</tbody></table>
</div>
</div>

<h3><a name="BookDataFormatAppendix-BasicUsage"></a>Basic Usage</h3>
<p>At its most basic all that is required to encrypt/decrypt an exchange is a shared secret key. If one or more instances of the Crypto data format are configured with this key the format can be used to encrypt the payload in one route (or part of one) and decrypted in another. For example, using the Java DSL as follows:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">KeyGenerator generator = KeyGenerator.getInstance(<span class="code-quote">"DES"</span>);

CryptoDataFormat cryptoFormat = <span class="code-keyword">new</span> CryptoDataFormat(<span class="code-quote">"DES"</span>, generator.generateKey());

from(<span class="code-quote">"direct:basic-encryption"</span>)
    .marshal(cryptoFormat)
    .to(<span class="code-quote">"mock:encrypted"</span>)
    .unmarshal(cryptoFormat)
    .to(<span class="code-quote">"mock:unencrypted"</span>);
</pre>
</div></div>

<p>In Spring the dataformat is configured first and then used in routes </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;camelContext id=<span class="code-quote">"camel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>
  <span class="code-tag">&lt;dataFormats&gt;</span>
    <span class="code-tag">&lt;crypto id=<span class="code-quote">"basic"</span> algorithm=<span class="code-quote">"DES"</span> keyRef=<span class="code-quote">"desKey"</span> /&gt;</span>
  <span class="code-tag">&lt;/dataFormats&gt;</span>
    ...
  <span class="code-tag">&lt;route&gt;</span>
    <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:basic-encryption"</span> /&gt;</span>
    <span class="code-tag">&lt;marshal ref=<span class="code-quote">"basic"</span> /&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:encrypted"</span> /&gt;</span>
    <span class="code-tag">&lt;unmarshal ref=<span class="code-quote">"basic"</span> /&gt;</span>
    <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:unencrypted"</span> /&gt;</span>
  <span class="code-tag">&lt;/route&gt;</span>
<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-SpecifyingtheEncryptionAlgorithm."></a>Specifying the Encryption Algorithm.</h3>

<p>Changing the algorithm is a matter of supplying the JCE algorithm name. If you change the algorithm you will need to use a compatible key.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">KeyGenerator generator = KeyGenerator.getInstance(<span class="code-quote">"DES"</span>);

CryptoDataFormat cryptoFormat = <span class="code-keyword">new</span> CryptoDataFormat(<span class="code-quote">"DES"</span>, generator.generateKey());
cryptoFormat.setShouldAppendHMAC(<span class="code-keyword">true</span>);
cryptoFormat.setMacAlgorithm(<span class="code-quote">"HmacMD5"</span>);

from(<span class="code-quote">"direct:hmac-algorithm"</span>)
    .marshal(cryptoFormat)
    .to(<span class="code-quote">"mock:encrypted"</span>)
    .unmarshal(cryptoFormat)
    .to(<span class="code-quote">"mock:unencrypted"</span>);
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-SpecifyinganInitializationVector."></a>Specifying an Initialization Vector.</h3>

<p>Some crypto algorhithms, particularly block algorithms, require configuration with an initial block of data known as an Initialization Vector. In the JCE this is passed as an AlgorithmParameterSpec when the Cipher is initialized. To use such a vector with the CryptoDataFormat you can configure it with a byte[] contianing the required data e.g.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">KeyGenerator generator = KeyGenerator.getInstance(<span class="code-quote">"DES"</span>);
<span class="code-object">byte</span>[] initializationVector = <span class="code-keyword">new</span> <span class="code-object">byte</span>[] {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07};

CryptoDataFormat cryptoFormat = <span class="code-keyword">new</span> CryptoDataFormat(<span class="code-quote">"DES/CBC/PKCS5Padding"</span>, generator.generateKey());
cryptoFormat.setInitializationVector(initializationVector);

from(<span class="code-quote">"direct:init-vector"</span>)
    .marshal(cryptoFormat)
    .to(<span class="code-quote">"mock:encrypted"</span>)
    .unmarshal(cryptoFormat)
    .to(<span class="code-quote">"mock:unencrypted"</span>);
</pre>
</div></div>

<p>or with spring, suppling a reference to a byte[]</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;crypto id=<span class="code-quote">"initvector"</span> algorithm=<span class="code-quote">"DES/CBC/PKCS5Padding"</span> keyRef=<span class="code-quote">"desKey"</span> initVectorRef=<span class="code-quote">"initializationVector"</span> /&gt;</span>
</pre>
</div></div>

<p>The same vector is required in both the encryption and decryption phases. As it is not necessary to keep the IV a secret, the DataFormat allows for it to be inlined into the encrypted data and subsequently read out in the decryption phase to initialize the Cipher. To inline the IV set the /oinline flag.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">KeyGenerator generator = KeyGenerator.getInstance(<span class="code-quote">"DES"</span>);
<span class="code-object">byte</span>[] initializationVector = <span class="code-keyword">new</span> <span class="code-object">byte</span>[] {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07};
SecretKey key = generator.generateKey();

CryptoDataFormat cryptoFormat = <span class="code-keyword">new</span> CryptoDataFormat(<span class="code-quote">"DES/CBC/PKCS5Padding"</span>, key);
cryptoFormat.setInitializationVector(initializationVector);
cryptoFormat.setShouldInlineInitializationVector(<span class="code-keyword">true</span>);
CryptoDataFormat decryptFormat = <span class="code-keyword">new</span> CryptoDataFormat(<span class="code-quote">"DES/CBC/PKCS5Padding"</span>, key);
decryptFormat.setShouldInlineInitializationVector(<span class="code-keyword">true</span>);

from(<span class="code-quote">"direct:inline"</span>)
    .marshal(cryptoFormat)
    .to(<span class="code-quote">"mock:encrypted"</span>)
    .unmarshal(decryptFormat)
    .to(<span class="code-quote">"mock:unencrypted"</span>);
</pre>
</div></div>

<p>or with spring.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">&lt;crypto id=<span class="code-quote">"inline"</span> algorithm=<span class="code-quote">"DES/CBC/PKCS5Padding"</span> keyRef=<span class="code-quote">"desKey"</span> initVectorRef=<span class="code-quote">"initializationVector"</span>
  inline=<span class="code-quote">"true"</span> /&gt;
<span class="code-tag">&lt;crypto id=<span class="code-quote">"inline-decrypt"</span> algorithm=<span class="code-quote">"DES/CBC/PKCS5Padding"</span> keyRef=<span class="code-quote">"desKey"</span> inline=<span class="code-quote">"true"</span> /&gt;</span>
</pre>
</div></div>

<p>For more information of the use of Initialization Vectors, consult</p>

<ul>
	<li><a href="http://en.wikipedia.org/wiki/Initialization_vector" class="external-link" rel="nofollow">http://en.wikipedia.org/wiki/Initialization_vector</a></li>
	<li><a href="http://www.herongyang.com/Cryptography/" class="external-link" rel="nofollow">http://www.herongyang.com/Cryptography/</a></li>
	<li><a href="http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation" class="external-link" rel="nofollow">http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation</a></li>
</ul>


<h3><a name="BookDataFormatAppendix-HashedMessageAuthenticationCodes%28HMAC%29"></a>Hashed Message Authentication Codes (HMAC)</h3>

<p>To avoid attacks against the encrypted data while it is in transit the CryptoDataFormat can also calculate a Message Authentication Code forthe encrypted exchange contents based on a configurable MAC algorithm. The calculated HMAC is appended to the stream after encryption. It is separated from the stream in the decryption phase. The MAC is recalculated and verified against the transmitted version to insure nothing was tampered with in transit.For more information on Message Authentication Codes see <a href="http://en.wikipedia.org/wiki/HMAC" class="external-link" rel="nofollow">http://en.wikipedia.org/wiki/HMAC</a></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">KeyGenerator generator = KeyGenerator.getInstance(<span class="code-quote">"DES"</span>);

CryptoDataFormat cryptoFormat = <span class="code-keyword">new</span> CryptoDataFormat(<span class="code-quote">"DES"</span>, generator.generateKey());
cryptoFormat.setShouldAppendHMAC(<span class="code-keyword">true</span>);

from(<span class="code-quote">"direct:hmac"</span>)
    .marshal(cryptoFormat)
    .to(<span class="code-quote">"mock:encrypted"</span>)
    .unmarshal(cryptoFormat)
    .to(<span class="code-quote">"mock:unencrypted"</span>);
</pre>
</div></div>

<p>or with spring.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;crypto id=<span class="code-quote">"hmac"</span> algorithm=<span class="code-quote">"DES"</span> keyRef=<span class="code-quote">"desKey"</span> shouldAppendHMAC=<span class="code-quote">"true"</span> /&gt;</span>
</pre>
</div></div>

<p>By default the HMAC is calculated using the HmacSHA1 mac algorithm though this can be easily changed by supplying a different algorithm name. See <a href="/confluence/pages/createpage.action?spaceKey=CAMEL&amp;title=here&amp;linkCreation=true&amp;fromPageId=17268915" class="createlink">here</a> for how to check what algorithms are available through the configured security providers</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">KeyGenerator generator = KeyGenerator.getInstance(<span class="code-quote">"DES"</span>);

CryptoDataFormat cryptoFormat = <span class="code-keyword">new</span> CryptoDataFormat(<span class="code-quote">"DES"</span>, generator.generateKey());
cryptoFormat.setShouldAppendHMAC(<span class="code-keyword">true</span>);
cryptoFormat.setMacAlgorithm(<span class="code-quote">"HmacMD5"</span>);

from(<span class="code-quote">"direct:hmac-algorithm"</span>)
    .marshal(cryptoFormat)
    .to(<span class="code-quote">"mock:encrypted"</span>)
    .unmarshal(cryptoFormat)
    .to(<span class="code-quote">"mock:unencrypted"</span>);
</pre>
</div></div>

<p>or with spring.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;crypto id=<span class="code-quote">"hmac-algorithm"</span> algorithm=<span class="code-quote">"DES"</span> keyRef=<span class="code-quote">"desKey"</span> macAlgorithm=<span class="code-quote">"HmacMD5"</span> shouldAppendHMAC=<span class="code-quote">"true"</span> /&gt;</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-SupplyingKeysdynamically."></a>Supplying Keys dynamically.</h3>

<p>When using a Recipient list or similar EIP the recipient of an exchange can vary dynamically. Using the same key across all recipients may neither be feasible or desirable. It would be useful to be able to specify keys dynamically on a per exchange basis. The exchange could then be dynamically enriched with the key of its target recipient before being processed by the data format. To facilitate this the DataFormat allow for keys to be supplied dynamically via the message headers below </p>

<ul>
	<li><tt>CryptoDataFormat.KEY</tt> <tt>"CamelCryptoKey"</tt></li>
</ul>


<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">CryptoDataFormat cryptoFormat = <span class="code-keyword">new</span> CryptoDataFormat(<span class="code-quote">"DES"</span>, <span class="code-keyword">null</span>);
/**
 * Note: the header containing the key should be cleared after
 * marshalling to stop it from leaking by accident and
 * potentially being compromised. The processor version below is
 * arguably better as the key is left in the header when you use
 * the DSL leaks the fact that camel encryption was used.
 */
from(<span class="code-quote">"direct:key-in-header-encrypt"</span>)
    .marshal(cryptoFormat)
    .removeHeader(CryptoDataFormat.KEY)
    .to(<span class="code-quote">"mock:encrypted"</span>);

from(<span class="code-quote">"direct:key-in-header-decrypt"</span>).unmarshal(cryptoFormat).process(<span class="code-keyword">new</span> Processor() {
    <span class="code-keyword">public</span> void process(Exchange exchange) <span class="code-keyword">throws</span> Exception {
        exchange.getIn().getHeaders().remove(CryptoDataFormat.KEY);
        exchange.getOut().copyFrom(exchange.getIn());
    }
}).to(<span class="code-quote">"mock:unencrypted"</span>);
</pre>
</div></div>

<p>or with spring.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;crypto id=<span class="code-quote">"nokey"</span> algorithm=<span class="code-quote">"DES"</span> /&gt;</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-Dependencies"></a>Dependencies</h3>

<p>To use the <a href="/confluence/display/CAMEL/Crypto" title="Crypto">Crypto</a> dataformat in your camel routes you need to add the following dependency to your pom.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependency&gt;</span>
  <span class="code-tag">&lt;groupId&gt;</span>org.apache.camel<span class="code-tag">&lt;/groupId&gt;</span>
  <span class="code-tag">&lt;artifactId&gt;</span>camel-crypto<span class="code-tag">&lt;/artifactId&gt;</span>
  <span class="code-tag">&lt;version&gt;</span>2.3.0<span class="code-tag">&lt;/version&gt;</span>
<span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>


<h3><a name="BookDataFormatAppendix-SeeAlso"></a>See Also</h3>
<ul>
	<li><a href="/confluence/display/CAMEL/Data+Format" title="Data Format">Data Format</a></li>
	<li><a href="/confluence/display/CAMEL/Crypto+%28Digital+Signatures%29" title="Crypto (Digital Signatures)">Crypto &#40;Digital Signatures&#41;</a></li>
</ul>

<h2><a name="BookDataFormatAppendix-SyslogDataFormat"></a>Syslog DataFormat</h2>
<p><b>Available as of Camel 2.6</b></p>

<p>The <b>syslog</b> dataformat is used for working with <a href="http://www.ietf.org/rfc/rfc3164.txt" class="external-link" rel="nofollow">RFC3164</a> messages.</p>

<p>This component supports the following:</p>
<ul class="alternate" type="square">
	<li>UDP consumption of syslog messages</li>
	<li>Agnostic data format using either plain String objects or SyslogMessage model objects.</li>
	<li><a href="/confluence/display/CAMEL/Type+Converter" title="Type Converter">Type Converter</a> from/to SyslogMessage and String</li>
	<li>Integration with the <a href="/confluence/display/CAMEL/MINA" title="MINA">camel-mina</a> component.</li>
	<li>Integration with the <a href="/confluence/display/CAMEL/Netty" title="Netty">camel-netty</a> component.</li>
</ul>


<p>Maven users will need to add the following dependency to their <tt>pom.xml</tt> for this component:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependency&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.camel<span class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>camel-syslog<span class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>x.x.x<span class="code-tag">&lt;/version&gt;</span>
    <span class="code-tag"><span class="code-comment">&lt;!-- use the same version as your Camel core version --&gt;</span></span>
<span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-RFC3164Syslogprotocol"></a>RFC3164 Syslog protocol</h3>
<p>Syslog uses the user datagram protocol (UDP) <a href="/confluence/pages/createpage.action?spaceKey=CAMEL&amp;title=1&amp;linkCreation=true&amp;fromPageId=24185759" class="createlink">1</a> as its underlying transport layer mechanism.  <br/>
The UDP port that has been assigned to syslog is 514.</p>

<p>To expose a Syslog listener service we reuse the existing <a href="/confluence/display/CAMEL/MINA" title="MINA">camel-mina</a> component or <a href="/confluence/display/CAMEL/Netty" title="Netty">camel-netty</a> where we just use the <tt>Rfc3164SyslogDataFormat</tt> to marshal and unmarshal messages</p>

<h4><a name="BookDataFormatAppendix-ExposingaSysloglistener"></a>Exposing a Syslog listener</h4>
<p>In our Spring XML file, we configure an endpoint to listen for udp messages on port 10514, note that in netty we disable the defaultCodec, this <br/>
will allow a fallback to a NettyTypeConverter and delivers the message as an InputStream:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;camelContext id=<span class="code-quote">"myCamel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>

    <span class="code-tag">&lt;dataFormats&gt;</span>
          <span class="code-tag">&lt;syslog id=<span class="code-quote">"mySyslog"</span>/&gt;</span>
    <span class="code-tag">&lt;/dataFormats&gt;</span>

    <span class="code-tag">&lt;route&gt;</span>
          <span class="code-tag">&lt;from uri=<span class="code-quote">"netty:udp://localhost:10514?sync=false&amp;amp;allowDefaultCodec=false"</span>/&gt;</span>
          <span class="code-tag">&lt;unmarshal ref=<span class="code-quote">"mySyslog"</span>/&gt;</span>
          <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:stop1"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>

<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<p>The same route using <a href="/confluence/display/CAMEL/MINA" title="MINA">camel-mina</a></p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;camelContext id=<span class="code-quote">"myCamel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>

    <span class="code-tag">&lt;dataFormats&gt;</span>
          <span class="code-tag">&lt;syslog id=<span class="code-quote">"mySyslog"</span>/&gt;</span>
    <span class="code-tag">&lt;/dataFormats&gt;</span>

    <span class="code-tag">&lt;route&gt;</span>
          <span class="code-tag">&lt;from uri=<span class="code-quote">"mina:udp://localhost:10514"</span>/&gt;</span>
          <span class="code-tag">&lt;unmarshal ref=<span class="code-quote">"mySyslog"</span>/&gt;</span>
          <span class="code-tag">&lt;to uri=<span class="code-quote">"mock:stop1"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>

<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>


<h4><a name="BookDataFormatAppendix-Sendingsyslogmessagestoaremotedestination"></a>Sending syslog messages to a remote destination</h4>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;camelContext id=<span class="code-quote">"myCamel"</span> xmlns=<span class="code-quote">"http://camel.apache.org/schema/spring"</span>&gt;</span>

    <span class="code-tag">&lt;dataFormats&gt;</span>
        <span class="code-tag">&lt;syslog id=<span class="code-quote">"mySyslog"</span>/&gt;</span>
    <span class="code-tag">&lt;/dataFormats&gt;</span>

    <span class="code-tag">&lt;route&gt;</span>
        <span class="code-tag">&lt;from uri=<span class="code-quote">"direct:syslogMessages"</span>/&gt;</span>
        <span class="code-tag">&lt;marshal ref=<span class="code-quote">"mySyslog"</span>/&gt;</span>
        <span class="code-tag">&lt;to uri=<span class="code-quote">"mina:udp://remotehost:10514"</span>/&gt;</span>
    <span class="code-tag">&lt;/route&gt;</span>

<span class="code-tag">&lt;/camelContext&gt;</span>
</pre>
</div></div>

<h3><a name="BookDataFormatAppendix-SeeAlso"></a>See Also</h3>
<ul>
	<li><a href="/confluence/display/CAMEL/Configuring+Camel" title="Configuring Camel">Configuring Camel</a></li>
	<li><a href="/confluence/display/CAMEL/Component" title="Component">Component</a></li>
	<li><a href="/confluence/display/CAMEL/Endpoint" title="Endpoint">Endpoint</a></li>
	<li><a href="/confluence/display/CAMEL/Getting+Started" title="Getting Started">Getting Started</a></li>
</ul>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/Book+DataFormat+Appendix">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=24186021&revisedVersion=2&originalVersion=1">View Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAMEL/Book+DataFormat+Appendix?showComments=true&amp;showCommentArea=true#addcomment">Add Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message