Scripting layer

IPF message processing routes are written with a domain-specific language (DSL) which is based on the Apache Camel DSL. Any DSL feature from Apache Camel is also available within IPF. One important design goal of IPF was to provide healthcare-specific message processing capabilities as extensions to the Camel DSL. For example, implementing an HL7 message validator should be as easy as implementing a XSD validator. To make DSL extensions possible IPF provides a DSL extension mechanism which is based on Groovy meta-programming. A meta-programming based approach was chosen because Camel currently doesn't provide an interface for extending its DSL. Consequently, for using the IPF DSL (i.e. the Camel DSL plus IPF DSL extensions) message processing routes must be written in the Groovy programming language. This doesn't mean that all parts of your program must be written in Groovy e.g. custom message transformers can still be implemented in Java (or any other JVM language). It is only important that route definitions (i.e the route builder) are written in Groovy.

All predefined DSL extensions provided by IPF have been implemented using this extensions mechansim. One important aspect of the extension mechanism is that it can also be used by IPF application to implement application-specific DSL extensions. There is a separate DSL extensions guide that explains how to. This makes application-specific message processing routes more readable and allows other projects to reuse these extensions. DSL extensions may also be based on other DSL extensions i.e. composition of DSL extensions is supported as well.

The DSL extension mechanism including all DSL extensions contributed by individual IPF components are referred to as the IPF scripting layer. The feature set of the IPF DSL therefore depends on which IPF components have been deployed. In other words, the DSL extension mechanism supports modularization of DSL extensions. An overview of all predefined IPF DSL extensions is given in the IPF extensions index. The following subsection exaplains the DSL extension mechanism in more detail.

DSL extension mechanism

DSL extensions guide and tutorials The example presented here is explained in much more detail in the DSL extensions guide. Furthermore, all tutorials make use of the DSL extension mechanism and the predefined DSL extensions.

The easiest way to learn the DSL extension mechanism is to start with a simple example. Let's say we want to introduce a new translate DSL element that translates a message from one language into another. To keep the examle simple we assume that the translation magic is done inside a single Translator processor.

package example;

import org.apache.camel.Exchange;
import org.apache.camel.Processor;

public class Translator implements Processor {

    public void process(Exchange exchange) throws Exception {
        // do language translation here ...
    }

}

Without using DSL extensions such a processor can be included into route definitions like in the following example.

package example

import org.apache.camel.spring.SpringRouteBuilder

class MyRouteBuilder extends SpringRouteBuilder {

    void configure() {
        from('direct:input')
        .process(new Translator())
        .to('direct:output')

    }

}

The goal however is to introduce a translate DSL extension that makes use of this processor. The result should look like.

package example

import org.apache.camel.spring.SpringRouteBuilder

class MyRouteBuilder extends SpringRouteBuilder {

    void configure() {
        from('direct:input')
        .translate()
        .to('direct:output')

    }

}

To be able to use the translate() method in our route definitions we need to add that method into the corresponding DSL model class which is org.apache.camel.model.ProcessorDefinition in our example. Adding the method is done via Groovy meta-programming inside an extensions block.

package example

import org.apache.camel.model.ProcessorDefinition

class MyExtension {

    static extensions = {

        ProcessorDefinition.metaClass.translate = {->
            delegate.process(new Translator())
        }

    }

}

You can add an extensions block to any class you like. To make the example work, the DSL extension, the route builder and the infrastructure components of the DSL extension mechanism must be wired together within a Spring application context.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:camel="http://camel.apache.org/schema/spring"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://camel.apache.org/schema/spring 
http://camel.apache.org/schema/spring/camel-spring.xsd">

    <camel:camelContext id="camelContext">
        <camel:routeBuilder ref="routeBuilder"/>        
    </camel:camelContext>
    
    <bean id="routeBuilder" depends-on="routeModelExtender"
        class="example.MyRouteBuilder">
    </bean>
    
    <bean id="exampleModelExtension"
        class="example.MyExtension">
    </bean>
    
    <bean id="coreModelExtension"
        class="org.openehealth.ipf.platform.camel.core.extend.CoreModelExtension">
    </bean>
    
    <bean id="routeModelExtender"
        class="org.openehealth.ipf.platform.camel.core.extend.DefaultModelExtender">
        <property name="routeModelExtensions">
            <list>
                <ref bean="coreModelExtension" />
                <ref bean="exampleModelExtension" />
            </list>
        </property>
    </bean>

</beans>

The above example also shows how to include the predefined DSL extensions provided by platform-camel-core. Please note that this is not required to make our example work. It's only an example how to combine predefined DSL extensions with custom DSL extensions.

DSL extensions and OSGi In an OSGi environment DSL extensions are automatically detected by IPF-specific extender bundles, so there is no need to add them to a Spring application context.

Limitations

There are some limitations you should be aware of when using the IPF extension mechanism. DSL extensions defined in Groovy are not available for Camel's Java DSL or for the Spring-based XML configuration. Also, DSL extensions currently do not show up for code completion in IDEs such as the Groovy plugins for Eclipse or IntelliJ IDEA. However, we are currently working on a solution for the code-completion problem.

Predefined DSL extensions

Predefined DSL extensions are provided by the following IPF components.

A description of these components is given on the IPF architecture page. For a detailed description of the extensions follow the links in the Documentation column. The extension classes can be combined as shown in the configuration example above.

DSL extensions index A summary of all predefined DSL extensions is given in the DSL extensions index.