Developing using HAPI - By Example
This page is intended to explain how to develop an application that uses HAPI to send or receive messages, using straightforward examples.
It is a new section of the HAPI documentation, and is still very much a work in progress. If you have any comments/suggestions/corrections, please send them to mailto:jamesagnew@sourceforge.net.
Please note that this page assumes at least a basic familiarity with HL7 and it's terminology.
The Basics
- A good starting point with regards to using HAPI would be to parse a message.
Creating messages
- Next, let's try creating a new message from scratch.
- Another common problem is to populate an ORU message's OBX segment.
Sending and receiving
- First, you will need a HAPI Context.
- Now, let's introduce some network operations to send messages from a client and receive messages to a server.
- Read messages from a file and send multiple messages out using ConnectionHub.
- Handle different character encoding schemes (charsets), such as UTF-8, or ISO-8859/2.
- Message encryption is possible using SSL/TLS
- Configure threading strategies by using custom ExecutorServices.
Sending and receiving using HL7 over HTTP
- See the HL7 over HTTP page for information on how to incorporate HL7-over-HTTP instead of MLLP for a more robust and secure communication method.
Parsing Messages
- There are several ways to handle multiple versions of HL7 within a single application.
- Another way of reading and writing to message objects is to use a Terser
- We can use a subclassed parser to correct invalid messages before parsing them.
- SuperStructures can be used to write applications which deal with various different ADT structures without writing different routines for each structure.
- Allow parsing of ORU^R01 (and other messages with OBX segments) which have an invalid value in OBX-2, which specifies the type used to parse OBX-5 using ParserConfiguration.
Custom Segments and Structures
- Custom Model Classes and generic segments can be used to handle custom message types and Z-segments.
- The Conformance page has information about the "confgen" maven plugin, which can be used to generate custom classes easily using HL7 conformance profiles.
Validating Messages
- Once we're parsing messages, we can validate messages to make sure they contain no invalid data.
- We can define our own validation rules to adapt validation to site-specific requirements.
- Another variant is to use a MessageVisitor for validating e.g. that mandatory fields in a message instance are not empty.
- To be even more advanced, we can validate messages using conformance profiles. Note that the conformance profile used in this example can be seen HERE. See the FAQ for notes on using this in your own applications.
Advanced Creating Messages
- Alessandro Delprete submitted this example of how to embed a CDA document as MIME content in an MDM^T02 message.
Configuring HAPI
- The Configuring HAPI page explains several options for advanced configuration.