Upgrading from HAPI 2.0 or before

This document describes some of the changes between the HAPI 2.0 API newer versions of the API. Note that none of these changes are required yet. The "old way" of doing things is deprecated but still supported for the time being.

Upgrading HL7 Servers

HAPI 2.0 contains two complete modules for creating an HL7 Server capable of listening for connections from outside applications, receiving messages and processing them:

The .app.* package contains the original server implementation and has always been the implementation suggested by the HAPI documentation. While it was very simplistic in its original implementation, it has received a good deal of improvement over the years from the HAPI community.

The .protocol.* package contains a more recent server implementation, which had a number of great ideas but was never completed and never received much attention from the HAPI community in general. As such, .protocol.* is being largely deprecated, and its best parts are being merged into the server implementations in .app.* .

Migrating Existing code which uses ca.uhn.hl7v2.protocol.impl.HL7Server

If your code uses ca.uhn.hl7v2.protocol.impl.HL7Server to provide an HL7 server, as in the following example:

      // Create a router
      ApplicationRouterImpl router = new ApplicationRouterImpl();
      AppRoutingDataImpl routingData = new AppRoutingDataImpl("*", "*", "*", "*");

      // Create an application and bind it to the router
      MyReceivingApplication application = new MyReceivingApplication();
      router.bindApplication(routingData, application);

      // Create a server and start it
      ServerSocket socket = new ServerSocket(8888);
      NullSafeStorage storage = new NullSafeStorage();
      HL7Server hl7Server = new HL7Server(socket, router, storage);
      hl7Server.start(null);

The migration is as simple as converting your code to use ca.uhn.hl7v2.protocol.app.HL7Service instead, as in the following example:

      // Create a context and ask it for a service
      DefaultHapiContext ctx = new DefaultHapiContext();
      HL7Service server = ctx.newServer(8888, false);

      // Create an application and bind it to the server
      MyReceivingApplication application = new MyReceivingApplication();
      server.registerApplication(application);

      // Start the server
      server.start();

Migrating Existing code which uses ca.uhn.hl7v2.Application

HAPI applications which use ca.uhn.hl7v2.app.Application (which is provided to a SimpleService or TwoPortServer either directly or using the newer HapiContext#getServer() methods) should migrate to the newer ca.uhn.hl7v2.protocol.ReceivingApplication .

A typical old style Application looks like the following:

public class MyApplication implements ca.uhn.hl7v2.app.Application {

   public Message processMessage(Message theMessage) throws HL7Exception {
      // ...Do something with theMessage...
      try {
         return theMessage.generateACK();
      } catch (IOException e) {
         throw new HL7Exception(e);
      }
   }

   public boolean canProcess(Message theMessage) {
      return true;
   }

}

Converting to a ReceivingApplication is as simple as changing the interface implemented by your handling application, and modifying the signature of the processMessage method to add a metadata Map<String, Object> to the parameter list, like so:

public class MyReceivingApplication implements ca.uhn.hl7v2.protocol.ReceivingApplication {

   public Message processMessage(Message theMessage, Map<String, Object> theMetadata) throws ReceivingApplicationException, HL7Exception {

      // ...Do something with theMessage...

      try {
         return theMessage.generateACK();
      } catch (IOException e) {
         throw new HL7Exception(e);
      }
   }

   public boolean canProcess(Message theMessage) {
      return true;
   }

}

Once you've migrated to the ReceivingApplication interface, you might want to take advantage of the new metadata keys available in MetadataKeys