HL7 Component
The hl7 component is used for working with the HL7 MLLP protocol and HL7 v2 messages using the HAPI library.
This component supports the following:
- HL7 MLLP codec for Mina
- Agnostic data format using either plain String objects or HAPI HL7 model objects.
- Type Converter from/to HAPI and String
- HL7 DataFormat using HAPI library
- Even more ease-of-use as it's integrated well with the camel-mina component.
Maven users will need to add the following dependency to their pom.xml
for this component:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-hl7</artifactId> <version>x.x.x</version> <!-- use the same version as your Camel core version --> </dependency>
HL7 MLLP protocol
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.
To expose a HL7 listener service we reuse the existing camel-mina component where we just use the HL7MLLPCodec
as codec.
The HL7 MLLP codec has the following options:
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 (is a charset name) to use for the codec. If not provided, Camel will use the JVM default Charset. |
|
|
Will convert |
|
|
Whether HAPI Parser should validate or not. |
|
|
Camel 2.11: To use a custom parser. Must be of type |
Exposing a HL7 listener
In our Spring XML file, we configure an endpoint to listen for HL7 requests using TCP:
<endpoint id="hl7listener" uri="mina:tcp://localhost:8888?sync=true&codec=#hl7codec"/>
Notice we configure it to use camel-mina with TCP on the localhost
on port 8888
. We use sync=true 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 codec=#hl7codec. Notice that hl7codec
is just a Spring bean ID, so we could have named it mygreatcodecforhl7
or whatever. The codec is also set up in the Spring XML file:
<bean id="hl7codec" class="org.apache.camel.component.hl7.HL7MLLPCodec"> <property name="charset" value="iso-8859-1"/> </bean>
Above we also configure the charset encoding to use (iso-8859-1
).
The endpoint hl7listener can then be used in a route as a consumer, as this Java DSL example illustrates:
from("hl7listener").to("patientLookupService");
This is a very simple route that will listen for HL7 and route it to a service named patientLookupService that is also a Spring bean ID we have configured in the Spring XML as:
<bean id="patientLookupService" class="com.mycompany.healthcare.service.PatientLookupService"/>
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:
import ca.uhn.hl7v2.HL7Exception; import ca.uhn.hl7v2.model.Message; import ca.uhn.hl7v2.model.v24.segment.QRD; public class PatientLookupService { public Message lookupPatient(Message input) throws HL7Exception { QRD qrd = (QRD)input.get("QRD"); String patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue(); // find patient data based on the patient id and create a HL7 model object with the response Message response = ... create and set response data return response }
Notice that this class uses just imports from the HAPI library and not from Camel.
HL7 Model using java.lang.String
The HL7MLLP codec uses plain String
as its data format. Camel uses its Type Converter to convert to/from strings to the HAPI HL7 model objects. However, you can use plain String
objects if you prefer, for instance if you wish to parse the data yourself.
See samples for such an example.
HL7v2 Model using HAPI
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.
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 sample below is a request to lookup a patient with the patient ID 0101701234
.
MSH|^~\\&|MYSENDER|MYRECEIVER|MYAPPLICATION||200612211200||QRY^A19|1234|P|2.4 QRD|200612211200|R|I|GetPatient|||1^RD|0101701234|DEM||
Using the HL7 model we can work with the data as a ca.uhn.hl7v2.model.Message
object.
To retrieve the patient ID in the message above, you can do this in Java code:
Message msg = exchange.getIn().getBody(Message.class); QRD qrd = (QRD)msg.get("QRD"); String patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue();
If you know the message type in advance, you can be more type-safe:
QRY_A19 msg = exchange.getIn().getBody(QRY_A19.class); String patientId = msg.getQRD().getWhoSubjectFilter(0).getIDNumber().getValue();
Camel has built-in type converters, so when this operation is invoked:
Message msg = exchange.getIn().getBody(Message.class);
Camel will convert the received HL7 data from String
to Message
. This is powerful when combined with the HL7 listener, then 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 HL7v2 model objects.
HL7 DataFormat
The HL7 component ships with a HL7 data format that can be used to marshal or unmarshal HL7 model objects.
marshal
= from Message to byte stream (can be used when responding using the HL7 MLLP codec)unmarshal
= from byte stream to Message (can be used when receiving streamed data from the HL7 MLLP
To use the data format, simply instantiate an instance and invoke the marshal or unmarshal operation in the route builder:
DataFormat hl7 = new HL7DataFormat(); ... from("direct:hl7in").marshal(hl7).to("jms:queue:hl7out");
In the sample above, the HL7 is marshalled from a HAPI Message object to a byte stream and put on a JMS queue.
The next example is the opposite:
DataFormat hl7 = new HL7DataFormat(); ... from("jms:queue:hl7out").unmarshal(hl7).to("patientLookupService");
Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.
Serializable messages
As of HAPI 2.0 (used by Camel 2.11), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling marshal()
and read them again directly from the queue (i.e. without calling unmarshal()
.
Segment separators
As of Camel 2.11, unmarshal
does not automatically fix segment separators anymore by converting \n
to \r
. If you
need this conversion, org.apache.camel.component.hl7.HL7#convertLFToCR
provides a handy Expression
for this purpose.
Charset
As of Camel 2.14.1, both marshal and unmarshal
evaluate the charset provided in the field MSH-18
. 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 guessCharsetName
method when inheriting from the HL7DataFormat
class.
There is a shorthand syntax in Camel for well-known data formats that are commonly used.
Then you don't need to create an instance of the HL7DataFormat
object:
from("direct:hl7in").marshal().hl7().to("jms:queue:hl7out"); from("jms:queue:hl7out").unmarshal().hl7().to("patientLookupService");
Message Headers
The unmarshal operation adds these MSH fields as headers on the Camel message:
Key |
MSH field |
Example |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
All headers 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 |
---|---|---|
validate |
true |
Whether the HAPI Parser should validate. |
|
|
Camel 2.11: To use a custom parser. Must be of type |
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 since Version 0.6 has been 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 a application works with HL7v2 message versions 2.4 and 2.5 then the following dependencies must be added:
<dependency> <groupId>ca.uhn.hapi</groupId> <artifactId>hapi-structures-v24</artifactId> <version>1.2</version> </dependency> <dependency> <groupId>ca.uhn.hapi</groupId> <artifactId>hapi-structures-v25</artifactId> <version>1.2</version> </dependency>
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.
<dependency> <groupId>ca.uhn.hapi</groupId> <artifactId>hapi-osgi-base</artifactId> <version>1.2</version> </dependency>
Note that the version number must match the version of the hapi-base library that is transitively referenced by this component.
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:
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:
Then we set up the Camel routes using the RouteBuilder
as follows:
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.
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 a 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 receive the response as a plain string, Bye World
.
Here we process the incoming data as plain String and send the response also as plain String: