HL7 Component
The hl7 HL7 component is used for working with the HL7 MLLP protocol and the HL7 modelv2 messages using the HAPI library.
This component supports the following:
- HL7 MLLP codec for Mina
...
- HL7 MLLP codec for Netty4 from Camel 2.15 onwards
- Type Converter from/to HAPI and String
- HL7 DataFormat using the HAPI library
- Even more
...
- ease-of-use as
...
- it's integrated well with the camel-
...
- mina2 component.
Maven users will need to add the following dependency to their pom.xml
for this component:
...
HL7 MLLP protocol
HL7 is often used with the HL7 MLLP protocol that , which is a text based TCP socket based protocol. This component ships with a Mina and Netty4 Codec that conforms to the MLLP protocol so you can easily expose a an HL7 listener that accepts accepting HL7 requests over the TCP transport layer. To expose a HL7 listener service we reuse the existing , the camel-mina2 or camel-mina component where we just use the HL7MLLPCodec as codec.The HL7 MLLP codec has the following options:netty4 component is used with the HL7MLLPCodec
(mina2) or HL7MLLPNettyDecoder/HL7MLLPNettyEncoder
(Netty4).
HL7 MLLP codec can be configured as follows:
...
Name | Default Value | Description |
---|---|---|
|
| The start byte spanning the HL7 payload. |
|
| The first end byte spanning the HL7 payload. |
|
| The 2nd end byte spanning the HL7 payload. |
| JVM Default | The encoding ( |
...
a charset name) to use for the codec. If not provided, Camel will use the JVM default Charset. | |
| true |
...
convertLFtoCR
...
(as of Camel 2.14.1) 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. | |
| false |
...
Will convert \n to \r (0x0d , |
...
13 decimal) as HL7 |
...
stipulates \r as segment terminators. The HAPI library requires |
...
the use of \r . |
Exposing
...
an HL7 listener using Mina
In our spring xml file the Spring XML file, we configure an a mina2 endpoint to listen for HL7 requests using TCP :
...
on port 8888
:
...
Notice we configure it to use camel-mina with TCP on the localhost on port 8888. We use the sync=true to indicate indicates that this listener is synchronous and therefore will return a HL7 response to the caller. Then we setup mina to use our The HL7 codec is setup with codec=hl7codec#hl7codec. Notice Note that hl7codec
is just a spring Spring bean idID, so we it could have be named it mygreatcodecforhl7
or whatever. The codec is also setup set up in the spring xml Spring XML file:
...
...
And here we configure the charset encoding to use, and iso-8859-1
is commonly used.
The endpoint hl7listener hl7MinaLlistener can then be used in a route as a consumer, as this java Java DSL example illustrates:
...
...
This is a very simple route that will listen for HL7 and route it to a service named patientLookupService that . This is also a spring bean id we have Spring bean ID, configured in the spring xml Spring XML as:
...
...
And another powerful feature of Camel is that we can have our busines logic The business logic can be implemented in POJO classes that is not at all tied to Camel do not depend on Camel, as shown here:
...
...
Exposing an HL7 listener using Netty (available from Camel 2.15 onwards)
In the Spring XML file, we configure a netty4 endpoint to listen for HL7 requests using TCP on port 8888
:
...
sync=true indicates that this listener is synchronous and therefore will return a HL7 response to the caller. The HL7 codec is setup with encoder=#hl7encoder and decoder=#hl7decoder. Note that hl7encoder
and hl7decoder
are just bean IDs, so they could be named differently. The beans can be set in the Spring XML file:
...
The endpoint hl7NettyListener can then be used in a route as a consumer, as this Java DSL example illustrates:
...
HL7 Model using java.lang.String or byte[]
The HL7MLLP HL7 MLLP codec uses plain String as its data format. And Camel uses its Type Converter to convert to/from /to Strings strings to the HAPI HL7 model objects. However , but you can use the plain String objects if you would like toprefer, for instance if you need wish to parse the data yourself.
See samples for such an example.
As of Camel 2.14.1 you can also let both the Mina and Netty codecs use a plain byte[]
as its data format by setting the produceString
property to false. The Type Converter is also capable of converting the byte[]
to/from HAPI HL7 model objects.
HL7v2
...
Model using HAPI
The HL7 HL7v2 model is uses Java objects from the HAPI library. Using this library we , you can encode and decode from the EDI format (ER7) that is mostly used with HL7HL7v2. 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.
The ER7 sample below is a request to lookup a patient with the patient id ID 0101701234
.
...
...
Using the HL7 model we you can work with the data as a ca.uhn.hl7v2.model.Message
object, e.Message objectg.
To to retrieve the patient id for the patient in the ER7 above you can do this in java code:
...
a patient ID:
...
Camel has build in type converters so when this operation is invoked:
...
Message msg = exchange.getIn().getBody(Message.class);
Camel will converter the received HL7 data from String to the Message object. This is powerful when combined with the HL7 listener, then because you as the end-user don't have to work with byte[]
, String
or any other simple object formats. You can just use the HAPI HL7 HL7v2 model objects.
...
Samples
In the following example we send a HL7 request to a HL7 listener and retrieves a response. We use plain String types in this example:
Wiki Markup |
---|
{snippet:id=e2|lang=java|url=activemq/camel/trunk/components/camel-hl7/src/test/java/org/apache/camel/component/hl7/HL7MLLPCodecTest.java} |
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 hl7service
= for instance using Spring and letting the bean id = hl7service
.
Our business logic is a plain POJO only using the HAPI library so we have these operations defined:
Wiki Markup |
---|
{snippet:id=e2|lang=java|url=activemq/camel/trunk/components/camel-hl7/src/test/java/org/apache/camel/component/hl7/HL7RouteTest.java} |
Then we setup the Camel routes using the RouteBuilder as:
...
If you know the message type in advance, you can be more type-safe:
...
Message Headers
The unmarshal operation adds these fields from the MSH segment as headers on the Camel message:
...
Key | MSH field | Example |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CamelHL7Context
| - | (Camel 2.14) contains the HapiContext that |
CamelHL7Charset | MSH-18 | (Camel 2.14.1)
|
All headers except CamelHL7Context
are String
types. If a header value is missing, its value is null
.
Options
The HL7 Data Format supports the following options:
...
Option | Default | Description |
---|---|---|
| true | Whether the HAPI Parser should validate the message using the default validation rules. It is recommended to use the |
|
| Custom parser to be used. Must be of type |
hapiContext | ca.uhn.hl7v2.DefaultHapiContext | Camel 2.14: Custom HAPI context that can define a custom parser, custom ValidationContext etc. This gives you full control over the HL7 parsing and rendering process. |
Dependencies
To use HL7 in your Camel routes you'll need to add a dependency on camel-hl7 listed above, which implements this data format.
The HAPI library is split into a base library and several structure libraries, one for each HL7v2 message version:
- v2.1 structures library
- v2.2 structures library
- v2.3 structures library
- v2.3.1 structures library
- v2.4 structures library
- v2.5 structures library
- v2.5.1 structures library
- v2.6 structures library
By default camel-hl7
only references the HAPI base library. 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:
...
Alternatively, an OSGi bundle containing the base library, all structures libraries and required dependencies (on the bundle classpath) can be downloaded from the central Maven repository.
...
Terser language
HAPI provides a Terser class that provides access to fields using a commonly used terse location specification syntax. The Terser language allows to use this syntax to extract values from messages and to use them as expressions and predicates for filtering, content-based routing etc.
Sample:
...
HL7 Validation predicate
Often it is preferable to first parse a HL7v2 message and in a separate step validate it against a HAPI ValidationContext.
Sample:
...
HL7 Validation predicate using the HapiContext (Camel 2.14)
The HAPI Context is always configured with a ValidationContext (or a ValidationRuleBuilder), so you can access the validation rules indirectly. Furthermore, when unmarshalling the HL7DataFormat forwards the configured HAPI context in the CamelHL7Context
header, and the validation rules of this context can be easily reused:
...
HL7 Acknowledgement expression
A common task in HL7v2 processing is to generate an acknowledgement message as response to an incoming HL7v2 message, e.g. based on a validation result. The ack
expression lets us accomplish this very elegantly:
...
More Samples
In the following example, a plain String
HL7 request is sent to an HL7 listener that sends back a response:
...
Notice that we use the HL7 DataFormat to enrich our Camel Message with the MSH fields preconfigued on the Camel Message. This let us much more easily define our routes using the fluent builders.
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.
Sample using plain String objects
In this sample we use plain String objects as the data format, that we send, process and receive. As the sample is part of an unit test there is some code for assertions, but you should be able to understand what happens. First we send the plain String Hello World to the HL7MLLPCodec and receives the response that is also just plain string as we receive Bye World
.
...
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 hl7service
.
...
Here we process the incoming data as plain String and send the response also as plain String:
...
Then the Camel routes using the RouteBuilder
may look as follows:
...
...
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.
...