You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by bu...@apache.org on 2014/12/08 10:25:53 UTC
svn commit: r931846 [2/3] - in /websites/production/camel/content:
book-component-appendix.html book-dataformat-appendix.html
book-in-one-page.html cache/main.pageCache hl7-dataformat.html hl7.html
Modified: websites/production/camel/content/book-in-one-page.html
==============================================================================
--- websites/production/camel/content/book-in-one-page.html (original)
+++ websites/production/camel/content/book-in-one-page.html Mon Dec 8 09:25:52 2014
@@ -4126,11 +4126,11 @@ While not actual tutorials you might fin
</div>
</div>
<h2 id="BookInOnePage-Preface">Preface</h2><p>This tutorial aims to guide the reader through the stages of creating a project which uses Camel to facilitate the routing of messages from a JMS queue to a <a shape="rect" class="external-link" href="http://www.springramework.org" rel="nofollow">Spring</a> service. The route works in a synchronous fashion returning a response to the client.</p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1417951040914 {padding: 0px;}
-div.rbtoc1417951040914 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1417951040914 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1418030442012 {padding: 0px;}
+div.rbtoc1418030442012 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1418030442012 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1417951040914">
+/*]]>*/</style></p><div class="toc-macro rbtoc1418030442012">
<ul class="toc-indentation"><li><a shape="rect" href="#Tutorial-JmsRemoting-TutorialonSpringRemotingwithJMS">Tutorial on Spring Remoting with JMS</a></li><li><a shape="rect" href="#Tutorial-JmsRemoting-Preface">Preface</a></li><li><a shape="rect" href="#Tutorial-JmsRemoting-Prerequisites">Prerequisites</a></li><li><a shape="rect" href="#Tutorial-JmsRemoting-Distribution">Distribution</a></li><li><a shape="rect" href="#Tutorial-JmsRemoting-About">About</a></li><li><a shape="rect" href="#Tutorial-JmsRemoting-CreatetheCamelProject">Create the Camel Project</a>
<ul class="toc-indentation"><li><a shape="rect" href="#Tutorial-JmsRemoting-UpdatethePOMwithDependencies">Update the POM with Dependencies</a></li></ul>
</li><li><a shape="rect" href="#Tutorial-JmsRemoting-WritingtheServer">Writing the Server</a>
@@ -6316,11 +6316,11 @@ So we completed the last piece in the pi
<style type="text/css">/*<![CDATA[*/
-div.rbtoc1417951041293 {padding: 0px;}
-div.rbtoc1417951041293 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1417951041293 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1418030443179 {padding: 0px;}
+div.rbtoc1418030443179 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1418030443179 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style><div class="toc-macro rbtoc1417951041293">
+/*]]>*/</style><div class="toc-macro rbtoc1418030443179">
<ul class="toc-indentation"><li><a shape="rect" href="#Tutorial-AXIS-Camel-TutorialusingAxis1.4withApacheCamel">Tutorial using Axis 1.4 with Apache Camel</a>
<ul class="toc-indentation"><li><a shape="rect" href="#Tutorial-AXIS-Camel-Prerequisites">Prerequisites</a></li><li><a shape="rect" href="#Tutorial-AXIS-Camel-Distribution">Distribution</a></li><li><a shape="rect" href="#Tutorial-AXIS-Camel-Introduction">Introduction</a></li><li><a shape="rect" href="#Tutorial-AXIS-Camel-SettinguptheprojecttorunAxis">Setting up the project to run Axis</a>
<ul class="toc-indentation"><li><a shape="rect" href="#Tutorial-AXIS-Camel-Maven2">Maven 2</a></li><li><a shape="rect" href="#Tutorial-AXIS-Camel-wsdl">wsdl</a></li><li><a shape="rect" href="#Tutorial-AXIS-Camel-ConfiguringAxis">Configuring Axis</a></li><li><a shape="rect" href="#Tutorial-AXIS-Camel-RunningtheExample">Running the Example</a></li></ul>
@@ -10495,7 +10495,7 @@ from("jms://queue/order").unma
<h3 id="BookInOnePage-Dependencies.23">Dependencies</h3>
<p>This data format is provided in <strong>camel-core</strong> so no additional dependencies is needed.</p>
-<h3 id="BookInOnePage-HL7DataFormat">HL7 DataFormat</h3><p>The <a shape="rect" href="hl7.html">HL7</a> component ships with a HL7 data format that can be used to marshal or unmarshal HL7 model objects.</p><ul class="alternate"><li><code>marshal</code> = from Message to byte stream (can be used when returning as response using the HL7 MLLP codec)</li><li><code>unmarshal</code> = 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 marshal or unmarshal operation in the route builder:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<h3 id="BookInOnePage-HL7DataFormat">HL7 DataFormat</h3><p>The <a shape="rect" href="hl7.html">HL7</a> component ships with a HL7 data format that can be used to marshal or unmarshal HL7 model objects.</p><ul class="alternate"><li><code>marshal</code> = from Message to byte stream (can be used when responding using the HL7 MLLP codec)</li><li><code>unmarshal</code> = 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 marshal or unmarshal operation in the route builder:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ DataFormat hl7 = new HL7DataFormat();
...
from("direct:hl7in").marshal(hl7).to("jms:queue:hl7out");
@@ -10505,7 +10505,14 @@ from("jms://queue/order").unma
...
from("jms:queue:hl7out").unmarshal(hl7).to("patientLookupService");
]]></script>
-</div></div><p>Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.</p> <div class="aui-message warning shadowed information-macro">
+</div></div><p>Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.</p> <div class="aui-message success shadowed information-macro">
+ <p class="title">Serializable messages</p>
+ <span class="aui-icon icon-success">Icon</span>
+ <div class="message-content">
+ <p>As of HAPI 2.0 (used by <strong>Camel 2.11</strong>), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling <code>marshal()</code> and read them again directly from the queue (i.e. without calling <code>unmarshal()</code>.</p>
+ </div>
+ </div>
+ <div class="aui-message warning shadowed information-macro">
<p class="title">Segment separators</p>
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
@@ -10516,20 +10523,14 @@ from("jms://queue/order").unma
<p class="title">Charset</p>
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
- <p>As of <strong>Camel 2.14.1</strong>, both <code>marshal and unmarshal</code> consider the charset provided in the field <code>MSH-18</code>. If this field is empty, by default the charset contained in the corresponding Camel charset property/header is assumed. You can even change this default behavior by overriding the <code>guessCharsetName</code> method when inheriting from the <code>HL7DataFormat</code> class.</p>
+ <p>As of <strong>Camel 2.14.1</strong>, both <code>marshal and unmarshal</code> evaluate the charset provided in the field <code>MSH-18</code>. If this field is empty, by default the charset contained in the corresponding Camel charset property/header is assumed. You can even change this default behavior by overriding the <code>guessCharsetName</code> method when inheriting from the <code>HL7DataFormat</code> class.</p>
</div>
</div>
-<p> </p><p>Notice there is a shorthand syntax in Camel for well-known data formats that is commonly used.<br clear="none"> Then you don't need to create an instance of the <code>HL7DataFormat</code> object:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<p> </p><p>There is a shorthand syntax in Camel for well-known data formats that are commonly used.<br clear="none"> Then you don't need to create an instance of the <code>HL7DataFormat</code> object:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ from("direct:hl7in").marshal().hl7().to("jms:queue:hl7out");
from("jms:queue:hl7out").unmarshal().hl7().to("patientLookupService");
]]></script>
-</div></div> <div class="aui-message success shadowed information-macro">
- <p class="title">Serializable messages</p>
- <span class="aui-icon icon-success">Icon</span>
- <div class="message-content">
- <p>As of HAPI 2.0 (used by <strong>Camel 2.11</strong>), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling <code>marshal()</code> and read them again directly from the queue (i.e. without calling <code>unmarshal()</code>.</p>
- </div>
- </div>
+</div></div><p> </p><p> </p>
<h2 id="BookInOnePage-EDIDataFormat">EDI DataFormat</h2>
<p>We encourage end users to look at the <a shape="rect" class="external-link" href="http://milyn.codehaus.org/Home" rel="nofollow">Smooks</a> which supports EDI and Camel natively.</p>
@@ -19334,11 +19335,11 @@ template.send("direct:alias-verify&
</div>
</div>
<p>The <strong>cxf:</strong> component provides integration with <a shape="rect" href="http://cxf.apache.org">Apache CXF</a> for connecting to JAX-WS services hosted in CXF.</p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1417951045875 {padding: 0px;}
-div.rbtoc1417951045875 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1417951045875 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1418030453963 {padding: 0px;}
+div.rbtoc1418030453963 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1418030453963 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1417951045875">
+/*]]>*/</style></p><div class="toc-macro rbtoc1418030453963">
<ul class="toc-indentation"><li><a shape="rect" href="#CXF-CXFComponent">CXF Component</a>
<ul class="toc-indentation"><li><a shape="rect" href="#CXF-URIformat">URI format</a></li><li><a shape="rect" href="#CXF-Options">Options</a>
<ul class="toc-indentation"><li><a shape="rect" href="#CXF-Thedescriptionsofthedataformats">The descriptions of the dataformats</a>
@@ -22808,7 +22809,7 @@ hibernate:[entityClassName][?options]
<h3 id="BookInOnePage-SeeAlso.40">See Also</h3>
<ul><li><a shape="rect" href="configuring-camel.html">Configuring Camel</a></li><li><a shape="rect" href="component.html">Component</a></li><li><a shape="rect" href="endpoint.html">Endpoint</a></li><li><a shape="rect" href="getting-started.html">Getting Started</a></li></ul>
<ul class="alternate"><li><a shape="rect" href="hibernate-example.html">Hibernate Example</a></li></ul>
-<h2 id="BookInOnePage-HL7Component">HL7 Component</h2><p>The <strong>hl7</strong> component is used for working with the HL7 MLLP protocol and <a shape="rect" class="external-link" href="http://www.hl7.org/" rel="nofollow">HL7 v2 messages</a> using the <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net" rel="nofollow">HAPI library</a>.</p><p>This component supports the following:</p><ul class="alternate"><li>HL7 MLLP codec for <a shape="rect" class="external-link" href="http://mina.apache.org/">Mina</a></li><li>Agnostic data format using either plain String objects or HAPI HL7 model objects.</li><li><a shape="rect" href="type-converter.html">Type Converter</a> from/to HAPI and String</li><li>HL7 DataFormat using HAPI library</li><li class="confluence-link">Even more ease-of-use as it's integrated well with the  <a shape="rect" href="mina2.html">camel-mina2</a> component.</li></ul><p>Maven users will need to add the following dependency to their <code>pom.
xml</code> for this component:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<h2 id="BookInOnePage-HL7Component">HL7 Component</h2><p>The <strong>HL7</strong> component is used for working with the HL7 MLLP protocol and <a shape="rect" class="external-link" href="http://www.hl7.org/implement/standards/product_brief.cfm?product_id=185" rel="nofollow">HL7 v2 messages</a> using the <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net" rel="nofollow">HAPI library</a>.</p><p>This component supports the following:</p><ul class="alternate"><li>HL7 MLLP codec for <a shape="rect" class="external-link" href="http://mina.apache.org/">Mina</a></li><li><a shape="rect" href="type-converter.html">Type Converter</a> from/to HAPI and String</li><li>HL7 DataFormat using the HAPI library</li><li class="confluence-link">Even more ease-of-use as it's integrated well with the <a shape="rect" href="mina2.html">camel-mina2</a> component.</li></ul><p>Maven users will need to add the following dependency to their <code>pom.xml</code> for this component:</p><div c
lass="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-hl7</artifactId>
@@ -22816,22 +22817,21 @@ hibernate:[entityClassName][?options]
<!-- use the same version as your Camel core version -->
</dependency>
]]></script>
-</div></div><h3 id="BookInOnePage-HL7MLLPprotocol">HL7 MLLP protocol</h3><p>HL7 is often used with the HL7 MLLP protocol that is a text based TCP socket based protocol. This component ships with a Mina Codec that conforms to the MLLP protocol so you can easily expose a HL7 listener that accepts HL7 requests over the TCP transport.</p><p>To expose a HL7 listener service we reuse the existing mina2 component where we just use the <code>HL7MLLPCodec</code> as codec.</p><p>The HL7 MLLP codec has the following options:</p><div class="confluenceTableSmall"><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Name</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default Value</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>startByte</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>0x0b</code></
p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The start byte spanning the HL7 payload.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>endByte1</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>0x1c</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The first end byte spanning the HL7 payload.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>endByte2</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>0x0d</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The 2nd end byte spanning the HL7 payload.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>charset</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>JVM Default</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The encoding (is a <a shape="rect" class="external-link" href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.
html" rel="nofollow">charset name</a>) to use for the codec. If not provided, Camel will use the <a shape="rect" class="external-link" href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html#defaultCharset()" rel="nofollow">JVM default Charset</a>.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>convertLFtoCR</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Will convert <code>\n</code> to <code>\r</code> (<code>0x0d</code>, 13 decimal) as HL7 stipulates <code>\r</code> as segment terminators. The HAPI library requires the use of <code>\r</code>.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>produceString</code></td><td colspan="1" rowspan="1" class="confluenceTd"><code>true</code></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>(Camel 2.14.1)</strong> If true, the codec creates a string using the defin
ed charset. If false, the codec sends the plain byte array into the route, so that the HL7 Data Format can determine the actual charset from the HL7 message content.</td></tr></tbody></table></div></div><h4 id="BookInOnePage-ExposingaHL7listener">Exposing a HL7 listener</h4><p>In our Spring XML file, we configure an endpoint to listen for HL7 requests using TCP:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <endpoint id="hl7listener" uri="mina:tcp://localhost:8888?sync=true&amp;codec=#hl7codec"/>
- <!-- Camel 2.11: uri="mina2:tcp... -->
+</div></div><h3 id="BookInOnePage-HL7MLLPprotocol">HL7 MLLP protocol</h3><p>HL7 is often used with the HL7 MLLP protocol, which is a text based TCP socket based protocol. This component ships with a Mina Codec that conforms to the MLLP protocol so you can easily expose an HL7 listener accepting HL7 requests over the TCP transport layer. To expose a HL7 listener service, the <a shape="rect" href="mina2.html">camel-mina2</a> component is used with the <code>HL7MLLPCodec</code> as codec.</p><p>The HL7 MLLP codec has the following options:</p><div class="confluenceTableSmall"><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Name</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default Value</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>startByte</code></p></td><td colspan="1" rowspan="1" class="confluenceTd">
<p><code>0x0b</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The start byte spanning the HL7 payload.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>endByte1</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>0x1c</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The first end byte spanning the HL7 payload.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>endByte2</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>0x0d</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The 2nd end byte spanning the HL7 payload.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>charset</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>JVM Default</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>The encoding (a <a shape="rect" class="external-link" href="http://docs.oracle.com/javase/6/docs/api/java/n
io/charset/Charset.html" rel="nofollow">charset name</a>) to use for the codec. If not provided, Camel will use the <a shape="rect" class="external-link" href="http://docs.oracle.com/javase/6/docs/api/java/nio/charset/Charset.html#defaultCharset()" rel="nofollow">JVM default Charset</a>.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>produceString</code></td><td colspan="1" rowspan="1" class="confluenceTd"><code>true</code></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>(Camel 2.14.1)</strong> If true, the codec creates a string using the defined charset. If false, the codec sends a plain byte array into the route, so that the HL7 Data Format can determine the actual charset from the HL7 message content.</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>convertLFtoCR</code></td><td colspan="1" rowspan="1" class="confluenceTd"><code>false</code></td><td colspan="1" rowspan="1" class="confluenceTd">Will convert <code>\n</code> t
o <code>\r</code> (<code>0x0d</code>, 13 decimal) as HL7 stipulates <code>\r</code> as segment terminators. The HAPI library requires the use of <code>\r</code>.</td></tr></tbody></table></div></div><h4 id="BookInOnePage-ExposinganHL7listener">Exposing an HL7 listener</h4><p>In the Spring XML file, we configure a mina2 endpoint to listen for HL7 requests using TCP on port <code>8888</code>:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <endpoint id="hl7listener" uri="mina2:tcp://localhost:8888?sync=true&amp;codec=#hl7codec"/>
]]></script>
-</div></div><p>Notice that we use TCP on <code>localhost</code> on port <code>8888</code>. We use <strong>sync=true</strong> to indicate that this listener is synchronous and therefore will return a HL7 response to the caller. Then we setup mina to use our HL7 codec with <strong>codec=#hl7codec</strong>. Notice that <code>hl7codec</code> is just a Spring bean ID, so we could have named it <code>mygreatcodecforhl7</code> or whatever. The codec is also set up in the Spring XML file:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p><strong>sync=true</strong> indicates that this listener is synchronous and therefore will return a HL7 response to the caller. The HL7 codec is setup with <strong>codec=#hl7codec</strong>. Note that <code>hl7codec</code> is just a Spring bean ID, so it could be named <code>mygreatcodecforhl7</code> or whatever. The codec is also set up in the Spring XML file:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <bean id="hl7codec" class="org.apache.camel.component.hl7.HL7MLLPCodec">
<property name="charset" value="iso-8859-1"/>
</bean>
]]></script>
-</div></div><p>Above we also configure the charset encoding to use (<code>iso-8859-1</code>).</p><p>The endpoint <strong>hl7listener</strong> can then be used in a route as a consumer, as this Java DSL example illustrates:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ from("hl7listener").to("patientLookupService");
+</div></div><p>The endpoint <strong>hl7listener</strong> can then be used in a route as a consumer, as this Java DSL example illustrates:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ from("hl7listener").beanRef("patientLookupService");
]]></script>
-</div></div><p>This is a very simple route that will listen for HL7 and route it to a service named <strong>patientLookupService</strong> that is also a Spring bean ID we have configured in the Spring XML as:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This is a very simple route that will listen for HL7 and route it to a service named <strong>patientLookupService</strong>. This is also Spring bean ID, configured in the Spring XML as:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <bean id="patientLookupService" class="com.mycompany.healthcare.service.PatientLookupService"/>
]]></script>
-</div></div><p>Another powerful feature of Camel is that we can have our business logic in POJO classes that is not tied to Camel as shown here:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>The business logic can be implemented in POJO classes that do not depend on Camel, as shown here:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[import ca.uhn.hl7v2.HL7Exception;
import ca.uhn.hl7v2.model.Message;
import ca.uhn.hl7v2.model.v24.segment.QRD;
@@ -22846,23 +22846,20 @@ public class PatientLookupService {
return response
}
]]></script>
-</div></div><p>Notice that this class uses just imports from the HAPI library and <strong>not</strong> from Camel.</p><h3 id="BookInOnePage-HL7Modelusingjava.lang.Stringorbyte[]">HL7 Model using java.lang.String or byte[]</h3><p>The HL7MLLP codec uses plain <code>String</code> as its data format. Camel uses its <a shape="rect" href="type-converter.html">Type Converter</a> to convert to/from strings to the HAPI HL7 model objects. However, you can use plain <code>String</code> objects if you prefer, for instance if you wish to parse the data yourself.</p><p>See samples for such an example.</p><p>As of Camel 2.14.1 you can also let the codec use a plain <code>byte[]</code> as its data format. The Type Converter is also capable of converting the <code>byte[]</code> to/from HAPI HL7 model objects. Furthermore,</p><h3 id="BookInOnePage-HL7v2ModelusingHAPI">HL7v2 Model using HAPI</h3><p>The HL7v2 model uses Java objects from the HAPI library. Using this library, we can encode and
decode from the EDI format (ER7) that is mostly used with HL7v2.<br clear="none"> With this model you can code with Java objects instead of the EDI based HL7 format that can be hard for humans to read and understand.</p><p>The sample below is a request to lookup a patient with the patient ID <code>0101701234</code>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3 id="BookInOnePage-HL7Modelusingjava.lang.Stringorbyte[]">HL7 Model using java.lang.String or byte[]</h3><p>The HL7 MLLP codec uses plain String as its data format. Camel uses its <a shape="rect" href="type-converter.html">Type Converter</a> to convert to/from strings to the HAPI HL7 model objects, but you can use the plain String objects if you prefer, for instance if you wish to parse the data yourself.</p><p>As of Camel 2.14.1 you can also let the codec use a plain <code>byte[]</code> as its data format. The Type Converter is also capable of converting the <code>byte[]</code> to/from HAPI HL7 model objects.</p><h3 id="BookInOnePage-HL7v2ModelusingHAPI">HL7v2 Model using HAPI</h3><p>The HL7v2 model uses Java objects from the HAPI library. Using this library, you can encode and decode from the EDI format (ER7) that is mostly used with HL7v2.</p><p>The sample below is a request to lookup a patient with the patient ID <code>0101701234</code>.</p><div class="c
ode panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[MSH|^~\\&|MYSENDER|MYRECEIVER|MYAPPLICATION||200612211200||QRY^A19|1234|P|2.4
QRD|200612211200|R|I|GetPatient|||1^RD|0101701234|DEM||
]]></script>
-</div></div><p>Using the HL7 model we can work with the data as a <code>ca.uhn.hl7v2.model.Message</code> object.<br clear="none"> To retrieve the patient ID in the message above, you can do this in Java code:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Using the HL7 model you can work with a <code>ca.uhn.hl7v2.model.Message</code> object, e.g. to retrieve a patient ID:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[Message msg = exchange.getIn().getBody(Message.class);
QRD qrd = (QRD)msg.get("QRD");
-String patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue();
+String patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue(); // 0101701234
]]></script>
-</div></div><p>If you know the message type in advance, you can be more type-safe:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This is powerful when combined with the HL7 listener, because you don't have to work with <code>byte[]</code>, <code>String</code> or any other simple object formats. You can just use the HAPI HL7v2 model objects. If you know the message type in advance, you can be more type-safe:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[QRY_A19 msg = exchange.getIn().getBody(QRY_A19.class);
String patientId = msg.getQRD().getWhoSubjectFilter(0).getIDNumber().getValue();
]]></script>
-</div></div><p>Camel has built-in type converters, so when this operation is invoked:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[Message msg = exchange.getIn().getBody(Message.class);
-]]></script>
-</div></div><p>Camel will convert the received HL7 data to <code>Message</code>. This is powerful when combined with the HL7 listener, then you as the end-user don't have to work with <code>byte[]</code>, <code>String</code> or any other simple object formats. You can just use the HAPI HL7v2 model objects.</p><p></p><h3 id="BookInOnePage-HL7DataFormat.1">HL7 DataFormat</h3><p>The <a shape="rect" href="hl7.html">HL7</a> component ships with a HL7 data format that can be used to marshal or unmarshal HL7 model objects.</p><ul class="alternate"><li><code>marshal</code> = from Message to byte stream (can be used when returning as response using the HL7 MLLP codec)</li><li><code>unmarshal</code> = 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 marshal or unmarshal operation in the route builder:</p><div class="code panel pdl" style="border-width: 1px;"><div class="cod
eContent panelContent pdl">
+</div></div><p> </p><p> </p><p></p><h3 id="BookInOnePage-HL7DataFormat.1">HL7 DataFormat</h3><p>The <a shape="rect" href="hl7.html">HL7</a> component ships with a HL7 data format that can be used to marshal or unmarshal HL7 model objects.</p><ul class="alternate"><li><code>marshal</code> = from Message to byte stream (can be used when responding using the HL7 MLLP codec)</li><li><code>unmarshal</code> = 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 marshal or unmarshal operation in the route builder:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ DataFormat hl7 = new HL7DataFormat();
...
from("direct:hl7in").marshal(hl7).to("jms:queue:hl7out");
@@ -22872,7 +22869,14 @@ String patientId = msg.getQRD().getWhoSu
...
from("jms:queue:hl7out").unmarshal(hl7).to("patientLookupService");
]]></script>
-</div></div><p>Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.</p> <div class="aui-message warning shadowed information-macro">
+</div></div><p>Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.</p> <div class="aui-message success shadowed information-macro">
+ <p class="title">Serializable messages</p>
+ <span class="aui-icon icon-success">Icon</span>
+ <div class="message-content">
+ <p>As of HAPI 2.0 (used by <strong>Camel 2.11</strong>), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling <code>marshal()</code> and read them again directly from the queue (i.e. without calling <code>unmarshal()</code>.</p>
+ </div>
+ </div>
+ <div class="aui-message warning shadowed information-macro">
<p class="title">Segment separators</p>
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
@@ -22883,20 +22887,14 @@ String patientId = msg.getQRD().getWhoSu
<p class="title">Charset</p>
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
- <p>As of <strong>Camel 2.14.1</strong>, both <code>marshal and unmarshal</code> consider the charset provided in the field <code>MSH-18</code>. If this field is empty, by default the charset contained in the corresponding Camel charset property/header is assumed. You can even change this default behavior by overriding the <code>guessCharsetName</code> method when inheriting from the <code>HL7DataFormat</code> class.</p>
+ <p>As of <strong>Camel 2.14.1</strong>, both <code>marshal and unmarshal</code> evaluate the charset provided in the field <code>MSH-18</code>. If this field is empty, by default the charset contained in the corresponding Camel charset property/header is assumed. You can even change this default behavior by overriding the <code>guessCharsetName</code> method when inheriting from the <code>HL7DataFormat</code> class.</p>
</div>
</div>
-<p> </p><p>Notice there is a shorthand syntax in Camel for well-known data formats that is commonly used.<br clear="none"> Then you don't need to create an instance of the <code>HL7DataFormat</code> object:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<p> </p><p>There is a shorthand syntax in Camel for well-known data formats that are commonly used.<br clear="none"> Then you don't need to create an instance of the <code>HL7DataFormat</code> object:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ from("direct:hl7in").marshal().hl7().to("jms:queue:hl7out");
from("jms:queue:hl7out").unmarshal().hl7().to("patientLookupService");
]]></script>
-</div></div> <div class="aui-message success shadowed information-macro">
- <p class="title">Serializable messages</p>
- <span class="aui-icon icon-success">Icon</span>
- <div class="message-content">
- <p>As of HAPI 2.0 (used by <strong>Camel 2.11</strong>), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling <code>marshal()</code> and read them again directly from the queue (i.e. without calling <code>unmarshal()</code>.</p>
- </div>
- </div><h3 id="BookInOnePage-MessageHeaders.5">Message Headers</h3><p>The <strong>unmarshal</strong> operation adds these MSH fields as headers on the Camel message:</p><div class="confluenceTableSmall"><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Key</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>MSH field</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Example</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7SendingApplication</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-3</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MYSERVER</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7SendingFacility</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-4</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MYSERVERAP
P</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7ReceivingApplication</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-5</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MYCLIENT</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7ReceivingFacility</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-6</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MYCLIENTAPP</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7Timestamp</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-7</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>20071231235900</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7Security</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-8</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7MessageType</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-9-1</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>ADT</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7TriggerEvent</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-9-2</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>A01</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7MessageControl</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-10</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>1234</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7ProcessingId</code></p></td><td colspan="1" rowspan
="1" class="confluenceTd"><p><code>MSH-11</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>P</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7VersionId</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-12</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>2.4</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>CamelHL7Context </code><code><br clear="none"></code></td><td colspan="1" rowspan="1" class="confluenceTd">-</td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>(Camel 2.14)</strong> contains the HapiContext that<br clear="none">was used to parse the message</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>CamelHL7Charset</code></td><td colspan="1" rowspan="1" class="confluenceTd"><code>MSH-18</code></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>(Camel 2.14.1)</strong> <code><br clear="non
e">UNICODE UTF-8</code></td></tr></tbody></table></div></div><p>All headers except <code>CamelHL7Context </code>are <code>String</code> types. If a header value is missing, its value is <code>null</code>.</p><h3 id="BookInOnePage-Options.42">Options</h3><p>The HL7 Data Format supports the following options:</p><div class="confluenceTableSmall"><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>validate</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>true</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Whether the HAPI Parser should validate using the default validation rules. Better use the <code>parser</code> or <code>hapiContext</code> option and initialize it w
ith the desired HAPI <code>ValidationContext</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>parser</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>ca.uhn.hl7v2.parser.GenericParser</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Use a custom parser. Must be of type <code>ca.uhn.hl7v2.parser.Parser</code>. Note that <code>GenericParser</code> also allows to parse XML-encoded HL7v2 messages</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>hapiContext</code></td><td colspan="1" rowspan="1" class="confluenceTd"><code>ca.uhn.hl7v2.DefaultHapiContext</code></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>Camel 2.14:</strong> Use a custom HAPI context that can define a custom parser, custom ValidationContext etc. This gives you full control over the HL7 parsing and rendering process.</td></tr></tbody></table></div></div><h3 id="BookInOnePage-Dependencies.36">Dependencies</h3><
p>To use HL7 in your Camel routes you'll need to add a dependency on <strong>camel-hl7</strong> listed above, which implements this data format.</p><p>The HAPI library is split into a <a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-base" rel="nofollow">base library</a> and several structure libraries, one for each HL7v2 message version:</p><ul><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v21" rel="nofollow">v2.1 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v22" rel="nofollow">v2.2 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v23" rel="nofollow">v2.3 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v231" rel="nofollow">v2.3.1
structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v24" rel="nofollow">v2.4 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v25" rel="nofollow">v2.5 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v251" rel="nofollow">v2.5.1 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v26" rel="nofollow">v2.6 structures library</a></li></ul><p>By default <code>camel-hl7</code> only references the HAPI <a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-base" rel="nofollow">base library</a>. Applications are responsible for including structure libraries themselves. For example, if a application works with HL7v2 message versions
2.4 and 2.5 then the following dependencies must be added:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p> </p><p> </p><h3 id="BookInOnePage-MessageHeaders.5">Message Headers</h3><p>The unmarshal operation adds these fields from the MSH segment as headers on the Camel message:</p><div class="confluenceTableSmall"><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Key</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>MSH field</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Example</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7SendingApplication</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-3</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MYSERVER</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7SendingFacility</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-4</code></p></td><td colspan="1" rowspan="1" class="confl
uenceTd"><p><code>MYSERVERAPP</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7ReceivingApplication</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-5</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MYCLIENT</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7ReceivingFacility</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-6</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MYCLIENTAPP</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7Timestamp</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-7</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>20071231235900</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7Security</code></p></td><td colspan="1" rowspan="1" class="conflue
nceTd"><p><code>MSH-8</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>null</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7MessageType</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-9-1</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>ADT</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7TriggerEvent</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-9-2</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>A01</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7MessageControl</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-10</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>1234</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7ProcessingId</code></p>
</td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-11</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>P</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>CamelHL7VersionId</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>MSH-12</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>2.4</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>CamelHL7Context </code><code><br clear="none"></code></td><td colspan="1" rowspan="1" class="confluenceTd">-</td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>(Camel 2.14)</strong> contains the <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/HapiContext.html" rel="nofollow">HapiContext</a> that<br clear="none">was used to parse the message</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>CamelHL7Charset</code></td><td colsp
an="1" rowspan="1" class="confluenceTd"><code>MSH-18</code></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>(Camel 2.14.1)</strong> <code><br clear="none">UNICODE UTF-8</code></td></tr></tbody></table></div></div><p>All headers except <code>CamelHL7Context </code>are <code>String</code> types. If a header value is missing, its value is <code>null</code>.</p><h3 id="BookInOnePage-Options.42">Options</h3><p>The HL7 Data Format supports the following options:</p><div class="confluenceTableSmall"><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>validate</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>true</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>
Whether the HAPI Parser should validate the message using the default validation rules. It is recommended to use the <code>parser</code> or <code>hapiContext</code> option and initialize it with the desired HAPI <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/validation/ValidationContext.html" rel="nofollow"><code>ValidationContext</code></a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><code>parser</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>ca.uhn.hl7v2.parser.GenericParser</code></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Custom parser to be used. Must be of type <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/parser/Parser.html" rel="nofollow"><code>ca.uhn.hl7v2.parser.Parser</code></a>. Note that <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/parser/Gener
icParser.html" rel="nofollow"><code>GenericParser</code></a> also allows to parse XML-encoded HL7v2 messages</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><code>hapiContext</code></td><td colspan="1" rowspan="1" class="confluenceTd"><code>ca.uhn.hl7v2.DefaultHapiContext</code></td><td colspan="1" rowspan="1" class="confluenceTd"><strong>Camel 2.14:</strong> Custom HAPI context that can define a custom parser, custom ValidationContext etc. This gives you full control over the HL7 parsing and rendering process.</td></tr></tbody></table></div></div><h3 id="BookInOnePage-Dependencies.36">Dependencies</h3><p>To use HL7 in your Camel routes you'll need to add a dependency on <strong>camel-hl7</strong> listed above, which implements this data format.</p><p>The HAPI library is split into a <a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-base" rel="nofollow">base library</a> and several structure libraries, one for each HL7v2 mes
sage version:</p><ul><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v21" rel="nofollow">v2.1 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v22" rel="nofollow">v2.2 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v23" rel="nofollow">v2.3 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v231" rel="nofollow">v2.3.1 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v24" rel="nofollow">v2.4 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v25" rel="nofollow">v2.5 structures library</a></li><li><a shape="rect" class
="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v251" rel="nofollow">v2.5.1 structures library</a></li><li><a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-structures-v26" rel="nofollow">v2.6 structures library</a></li></ul><p>By default <code>camel-hl7</code> only references the HAPI <a shape="rect" class="external-link" href="http://repo1.maven.org/maven2/ca/uhn/hapi/hapi-base" rel="nofollow">base library</a>. Applications are responsible for including structure libraries themselves. For example, if an application works with HL7v2 message versions 2.4 and 2.5 then the following dependencies must be added:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<dependency>
<groupId>ca.uhn.hapi</groupId>
<artifactId>hapi-structures-v24</artifactId>
@@ -22925,14 +22923,14 @@ String patientId = msg.getQRD().getWhoSu
from("direct:test1")
.setHeader("PATIENT_ID",terser("QRD-8(0)-1"))
.to("mock:test1");
- // continue processing if extracted field equals a message header
+
+ Â // continue processing if extracted field equals a message header
from("direct:test2")
- .filter(terser("QRD-8(0)-1")
- .isEqualTo(header("PATIENT_ID"))
+ .filter(terser("QRD-8(0)-1").isEqualTo(header("PATIENT_ID"))
.to("mock:test2");
]]></script>
-</div></div><h3 id="BookInOnePage-HL7Validationpredicate">HL7 Validation predicate</h3><p>Often it is preferable to parse a HL7v2 message and validate it against a HAPI <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/validation/ValidationContext.html" rel="nofollow">ValidationContext</a> in a separate step afterwards.</p><p>Sample:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3 id="BookInOnePage-HL7Validationpredicate">HL7 Validation predicate</h3><p>Often it is preferable to first parse a HL7v2 message and in a separate step validate it against a HAPI <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/validation/ValidationContext.html" rel="nofollow">ValidationContext</a>.</p><p>Sample:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[import static org.apache.camel.component.hl7.HL7.messageConformsTo;
import ca.uhn.hl7v2.validation.impl.DefaultValidation;
...
@@ -22941,9 +22939,11 @@ import ca.uhn.hl7v2.validation.impl.Defa
ValidationContext defaultContext = new DefaultValidation();
// Throws PredicateValidationException if message does not validate
- from("direct:test1").validate(messageConformsTo(defaultContext)).to("mock:test1");
+ from("direct:test1")
+ .validate(messageConformsTo(defaultContext))
+ .to("mock:test1");
]]></script>
-</div></div><h3 id="BookInOnePage-HL7ValidationpredicateusingtheHapiContext(Camel2.14)">HL7 Validation predicate using the HapiContext (Camel 2.14)</h3><p>The HAPI Context is always configured with a <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/validation/ValidationContext.html" rel="nofollow">ValidationContext</a> (or a <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/validation/builder/ValidationRuleBuilder.html" rel="nofollow">ValidationRuleBuilder</a>), so you can access the validation rules indirectly. Furthermore, when unmarshalling the HL7DataFormat forwards the configured  HAPI context  in the <code>CamelHL7Context </code>header, and the validation rules of this context can be easily reused:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3 id="BookInOnePage-HL7ValidationpredicateusingtheHapiContext(Camel2.14)">HL7 Validation predicate using the HapiContext (Camel 2.14)</h3><p>The HAPI Context is always configured with a <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/validation/ValidationContext.html" rel="nofollow">ValidationContext</a> (or a <a shape="rect" class="external-link" href="http://hl7api.sourceforge.net/base/apidocs/ca/uhn/hl7v2/validation/builder/ValidationRuleBuilder.html" rel="nofollow">ValidationRuleBuilder</a>), so you can access the validation rules indirectly. Furthermore, when unmarshalling the HL7DataFormat forwards the configured HAPI context in the <code>CamelHL7Context</code> header, and the validation rules of this context can be easily reused:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[import static org.apache.camel.component.hl7.HL7.messageConformsTo;
import static org.apache.camel.component.hl7.HL7.messageConforms
...
@@ -22990,7 +22990,7 @@ import ca.uhn.hl7v2.validation.impl.Defa
// acknowledgement
.transform(ack())
]]></script>
-</div></div><h3 id="BookInOnePage-MoreSamples">More Samples</h3><p>In the following example we send a HL7 request to a HL7 listener and retrieves a response. We use plain <code>String</code> types in this example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3 id="BookInOnePage-MoreSamples">More Samples</h3><p>In the following example, a plain <code>String</code> HL7 request is sent to an HL7 listener that sends back a response:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
String line1 = "MSH|^~\\&|MYSENDER|MYRECEIVER|MYAPPLICATION||200612211200||QRY^A19|1234|P|2.4";
String line2 = "QRD|200612211200|R|I|GetPatient|||1^RD|0101701234|DEM||";
@@ -23002,7 +23002,7 @@ in.append(line2);
String out = (String)template.requestBody("mina2:tcp://127.0.0.1:8888?sync=true&codec=#hl7codec", in.toString());
]]></script>
-</div></div><p>In the next sample, we want to route HL7 requests from our HL7 listener to our business logic. We have our business logic in a plain POJO that we have registered in the registry as <code>hl7service</code> = for instance using Spring and letting the bean id = <code>hl7service</code>.</p><p>Our business logic is a plain POJO only using the HAPI library so we have these operations defined:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>In the next sample, HL7 requests from the HL7 listener are routed to the business logic, which is implemented as plain POJO registered in the registry as <code>hl7service</code>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
public class MyHL7BusinessLogic {
@@ -23024,7 +23024,7 @@ public class MyHL7BusinessLogic {
}
}
]]></script>
-</div></div><p>Then we set up the Camel routes using the <code>RouteBuilder</code> as follows:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Then the Camel routes using the <code>RouteBuilder</code> may look as follows:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
DataFormat hl7 = new HL7DataFormat();
// we setup or HL7 listener on port 8888 (using the hl7codec) and in sync mode so we can return a response
@@ -23051,35 +23051,7 @@ from("mina2:tcp://127.0.0.1:8888?sy
// marshal response back
.marshal(hl7);
]]></script>
-</div></div><p>Notice that we use the HL7 DataFormat to enrich our Camel Message with the MSH fields preconfigured on the Camel Message. This lets us much more easily define our routes using the fluent builders.<br clear="none"> If we do not use the HL7 DataFormat, then we do not gains these headers and we must resort to a different technique for computing the MSH trigger event (= what kind of HL7 message it is). This is a big advantage of the HL7 DataFormat over the plain HL7 type converters.</p><h4 id="BookInOnePage-SampleusingplainStringobjects">Sample using plain String objects</h4><p>In this sample we use plain <code>String</code> objects as the data format, that we send, process and receive. As the sample is part of a unit test, there is some code for assertions, but you should be able to understand what happens. First we send the plain string, <code>Hello World</code>, to the <code>HL7MLLPCodec</code> and receive the response as a plain string, <code>Bye World</code>.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-MockEndpoint mock = getMockEndpoint("mock:result");
-mock.expectedBodiesReceived("Bye World");
-
-// send plain hello world as String
-Object out = template.requestBody("mina2:tcp://127.0.0.1:8888?sync=true&codec=#hl7codec", "Hello World");
-
-assertMockEndpointsSatisfied();
-
-// and the response is also just plain String
-assertEquals("Bye World", out);
-]]></script>
-</div></div><p>Here we process the incoming data as plain String and send the response also as plain String:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-from("mina2:tcp://127.0.0.1:8888?sync=true&codec=#hl7codec")
- .process(new Processor() {
- public void process(Exchange exchange) throws Exception {
- // use plain String as message format
- String body = exchange.getIn().getBody(String.class);
- assertEquals("Hello World", body);
-
- // return the response as plain string
- exchange.getOut().setBody("Bye World");
- }
- })
- .to("mock:result");
-]]></script>
-</div></div><p></p><h3 id="BookInOnePage-SeeAlso.41">See Also</h3>
+</div></div><p>Note that by using the HL7 DataFormat the Camel message headers are populated with the fields from the MSH segment. The headers are particularly useful for filtering or content-based routing as shown in the example above.</p><p> </p><p></p><h3 id="BookInOnePage-SeeAlso.41">See Also</h3>
<ul><li><a shape="rect" href="configuring-camel.html">Configuring Camel</a></li><li><a shape="rect" href="component.html">Component</a></li><li><a shape="rect" href="endpoint.html">Endpoint</a></li><li><a shape="rect" href="getting-started.html">Getting Started</a></li></ul>
<h2 id="BookInOnePage-HTTPComponent">HTTP Component</h2><p>The <strong>http:</strong> component provides HTTP based <a shape="rect" href="endpoint.html">endpoints</a> for consuming external HTTP resources (as a client to call external servers using HTTP).</p><p>Maven users will need to add the following dependency to their <code>pom.xml</code> for this component:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<dependency>
Modified: websites/production/camel/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/camel/content/hl7-dataformat.html
==============================================================================
--- websites/production/camel/content/hl7-dataformat.html (original)
+++ websites/production/camel/content/hl7-dataformat.html Mon Dec 8 09:25:52 2014
@@ -84,7 +84,7 @@
<tbody>
<tr>
<td valign="top" width="100%">
-<div class="wiki-content maincontent"><h3 id="HL7DataFormat-HL7DataFormat">HL7 DataFormat</h3><p>The <a shape="rect" href="hl7.html">HL7</a> component ships with a HL7 data format that can be used to marshal or unmarshal HL7 model objects.</p><ul class="alternate"><li><code>marshal</code> = from Message to byte stream (can be used when returning as response using the HL7 MLLP codec)</li><li><code>unmarshal</code> = 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 marshal or unmarshal operation in the route builder:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<div class="wiki-content maincontent"><h3 id="HL7DataFormat-HL7DataFormat">HL7 DataFormat</h3><p>The <a shape="rect" href="hl7.html">HL7</a> component ships with a HL7 data format that can be used to marshal or unmarshal HL7 model objects.</p><ul class="alternate"><li><code>marshal</code> = from Message to byte stream (can be used when responding using the HL7 MLLP codec)</li><li><code>unmarshal</code> = 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 marshal or unmarshal operation in the route builder:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ DataFormat hl7 = new HL7DataFormat();
...
from("direct:hl7in").marshal(hl7).to("jms:queue:hl7out");
@@ -94,7 +94,14 @@
...
from("jms:queue:hl7out").unmarshal(hl7).to("patientLookupService");
]]></script>
-</div></div><p>Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.</p> <div class="aui-message warning shadowed information-macro">
+</div></div><p>Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.</p> <div class="aui-message success shadowed information-macro">
+ <p class="title">Serializable messages</p>
+ <span class="aui-icon icon-success">Icon</span>
+ <div class="message-content">
+ <p>As of HAPI 2.0 (used by <strong>Camel 2.11</strong>), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling <code>marshal()</code> and read them again directly from the queue (i.e. without calling <code>unmarshal()</code>.</p>
+ </div>
+ </div>
+ <div class="aui-message warning shadowed information-macro">
<p class="title">Segment separators</p>
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
@@ -105,20 +112,14 @@
<p class="title">Charset</p>
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
- <p>As of <strong>Camel 2.14.1</strong>, both <code>marshal and unmarshal</code> consider the charset provided in the field <code>MSH-18</code>. If this field is empty, by default the charset contained in the corresponding Camel charset property/header is assumed. You can even change this default behavior by overriding the <code>guessCharsetName</code> method when inheriting from the <code>HL7DataFormat</code> class.</p>
+ <p>As of <strong>Camel 2.14.1</strong>, both <code>marshal and unmarshal</code> evaluate the charset provided in the field <code>MSH-18</code>. If this field is empty, by default the charset contained in the corresponding Camel charset property/header is assumed. You can even change this default behavior by overriding the <code>guessCharsetName</code> method when inheriting from the <code>HL7DataFormat</code> class.</p>
</div>
</div>
-<p> </p><p>Notice there is a shorthand syntax in Camel for well-known data formats that is commonly used.<br clear="none"> Then you don't need to create an instance of the <code>HL7DataFormat</code> object:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<p> </p><p>There is a shorthand syntax in Camel for well-known data formats that are commonly used.<br clear="none"> Then you don't need to create an instance of the <code>HL7DataFormat</code> object:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ from("direct:hl7in").marshal().hl7().to("jms:queue:hl7out");
from("jms:queue:hl7out").unmarshal().hl7().to("patientLookupService");
]]></script>
-</div></div> <div class="aui-message success shadowed information-macro">
- <p class="title">Serializable messages</p>
- <span class="aui-icon icon-success">Icon</span>
- <div class="message-content">
- <p>As of HAPI 2.0 (used by <strong>Camel 2.11</strong>), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling <code>marshal()</code> and read them again directly from the queue (i.e. without calling <code>unmarshal()</code>.</p>
- </div>
- </div></div>
+</div></div><p> </p><p> </p></div>
</td>
<td valign="top">
<div class="navigation">