NetKernel News Volume 3 Issue 9

December 23rd 2011

What's new this week?

• Repository Updates
• Holiday Support Cover
• Festive Camel Recipe
• HL7 Transport
• The Concise ROC Review of the Year

Catch up on last week's news here

Repository Updates

No changes this week - steady as you are.

Holiday Support Cover

For those of you with a comprehensive support contract we will be here to deal with any critical issues over the holiday period. If you get into trouble and need us, we recommend you raise your support issue through the NK support portal so that we can triage and assign one of the team.

General support cover will resume on Tuesday 3rd January 2012.

Festive Camel Recipe

Here's a little cocktail for you to impress your Christmas guests with.

Ingredients

You will need

• one NetKernel
• one Camel (thinly sliced)
• one Java endpoint.

Method

1. First get your Camel and clean thoroughly - making sure to remove any unnecessary baggage.
2. Take your NetKernel and create a new module.
3. Create a new Java class extending StandardTransportImpl
4. Add a lib/ directory to your module.
5. Pour the following libraries into the lib/ directory - taking care not to drop the jars, they break easily...
   • camel-context-2.8.3.jar
   • camel-core-2.8.3.jar
   • commons-logging-1.0.4.jar
   • commons-management-1.0.jar
   • log4j-1.2.16.jar
   • slf4j-api-1.6.1.jar
   • slf4j-log4j12-1.6.1.jar

Congratulations you now have a vanilla Camel cocktail. So next lets add some fruit to give it more flavour...

HL7 Transport

Here's how to take your vanilla camel module and turn it into an HL7 transport. HL7 is a domain specific format and protocol (MLLP) used extensively in the medical sector - it could prove invaluable if any of your guests over-indulge and require medical intervention.

Method - HL7

1. Add postCommission() and preDecommission() methods to your StandardTransportImpl class.
2. In postCommission() create a SimpleRegistry - Camel looks up everything from a registry. Experienced ROC people will at this point be hearing bells (not festive variety, but alarm bells). To an ROCer, when you hear the word "registry", its a sure sign of architectural peril - but its the season of forgiveness so just this once lets go with it. (If you're feeling "enterprisey" and want to impress your guests or, perhaps you just want to slow your solution down to a crawl, you can use a JNDI registry.)
3. Add a couple of beans to the registry.
   • The first bean should be an instance of HL7MLLPCodec (the MLLP codec used for the wire protocol).
   • The other bean should be a named reference to this (the StandardTransportImpl instance class - you're going to need to get back to it when your Camel carries you to the end of the road).
   • You might want to lighten the mixture by giving your beans "amusing" names.
4. Create a DefaultCamelContext() and pour in the SimpleRegistry.
5. Add some extra HL7 and Mina spices to the lib/ directory from the following spice jars...
   • camel-hl7-2.8.3.jar
   • camel-mina-2.8.3.jar
   • hapi-base-1.2.jar (get it from your nearest HAPI shopper)
   • mina-core-1.1.7.jar (get it here)
6. Finally add a route to your CamelContext - to tell it to start an MLLP socket and send received HL7 messages to a Handler class (we'll bake this later as our final topping).

HL7 NetKernel Transport

Here's one I made earlier, a complete HL7 MLLP NetKernel Transport in a dozen lines of code...

import org.apache.camel.CamelContext;
import org.apache.camel.builder.RouteBuilder;
import org.apache.camel.component.hl7.HL7MLLPCodec;
import org.apache.camel.impl.DefaultCamelContext;
import org.apache.camel.impl.SimpleRegistry;
import org.netkernel.layer0.nkf.INKFRequestContext;
import org.netkernel.module.standard.endpoint.StandardTransportImpl;

public class HL7Transport extends StandardTransportImpl
{
    public static final String HL7NKTRANSPORT="NEEDLE";
    private CamelContext mCamelContext;

    @Override
    protected void postCommission(INKFRequestContext aContext) throws Exception
    {
        SimpleRegistry reg=new SimpleRegistry();
        HL7MLLPCodec codec=new HL7MLLPCodec();
        codec.setCharset("iso-8859-1");
        reg.put("hl7codec", codec);
        reg.put(HL7NKTRANSPORT, this);
        
        mCamelContext = new DefaultCamelContext(reg);
        mCamelContext.addRoutes
        (   new RouteBuilder()
            {
                public void configure()
                {
                    from("mina:tcp://localhost:8888?sync=true&codec=#hl7codec")
                            .to("class:org.netkernel.tpt.hl7.endpoint.HL7MessageHandler?method=onMessage");
                }
            }
        );
        mCamelContext.start();
    }

    @Override
    protected void preDecommission(INKFRequestContext aContext) throws Exception
    {   mCamelContext.stop();
    }
    
}

Decorate with a Handler

Just one final thing needed - we need to decorate the HL7 cocktail with a cocktail umbrella. A handler that will actually receive HL7 messages when they arrive. Here's one I made earlier...

import org.apache.camel.Message;
import org.netkernel.layer0.nkf.INKFRequestContext;
import ca.uhn.hl7v2.HL7Exception;

public class HL7MessageHandler
{
    public Message onMessage(Message input) throws HL7Exception {

    //Get hold of your NK transport again - we need the ROC transport context
    HL7Transport transport=(HL7Transport)input
            .getExchange()
            .getContext()
            .getRegistry()
            .lookup(HL7Transport.HL7NKTRANSPORT);
    INKFRequestContext aContext=transport.getTransportContext();

    /*
    Use the context to issue requests into the ROC domain. 
    You'd probably want to pass the message as an argument too.
    */

    Message response = ... here you'd create and set HL7 response data...
    return response;
    }
}

This handler class is just a POJO and it should have been referenced in the to() route you set up in the main transport. Notice that we get back to the NK Transport (so that we can use its ROC request context) by retrieving its instance from the Camel registry that comes along inside the message (ROCers be merciful and forgive the Children-of-Java this sin - for they come from an ancient land and know not any other way).

Download

If you can't be bothered with doing this all by hand - here's a gift wrapped container of HL7 just ready for you to shake and pour over the ROCs...

http://temp.1060research.com/2011/12/urn.org.netkernel.tpt.hl7-1.2.1.jar

Comparison

You might want to take a look at the Camel HL7 reference page. You'll see that we've extracted the essence and used this to provide our concentrated flavouring.

Camel Cocktail Variations

The vanilla Camel cocktail recipe can be readily adapted. Why not try the

• SMTP-iced-tea
• HDFS-wall-banger
• SNMP-gueritta
• JMS-comfortable-screw...

Of course you can also invert the pattern and have Camel live inside an Accessor and using a ProducerTemplate you have the recipe for an outbound client. And for the adventurous ROCer why not consider the symmetrical Traccessor pattern - where your endpoint is simultaneously a Transport-server and Accessor-client (take a look at the existing JMS or XMPP modules for examples of this ROC pattern).

Summary

Christmas frivolity aside - this really simple recipe shows how you can leverage the hard work of all the people who have contributed connectors to the Camel project. You will also see that you can readily use Camel's simple routing patterns on the edge of the ROC domain - whilst still leveraging the power, scaling and computational efficiency of doing the real state processing in NetKernel's ROC domain. For added benefit you also get the power of NetKernel's hot deployment and modularisation to enable you to herd a host of Camels...

The Concise ROC Review of the Year

• Its been good, we've had fun, 2012 is going to be even better...
• Have a great holiday and a successful and prosperous New Year.