IPF Open eHealth Integration Platform

Inclusion Pattern

There are three different ways of including a transmogrifier into a Camel route:

• Pass a transmogrifier object as argument to the transmogrify method. This has already been shown in the example route above.
• Pass the name of a transmogrifier bean as argument to the transmogrify method (see below). A bean with that name must exist in the Camel registry.
• Define a transmogrifier logic inline using a Closure (see below). This is comparable to implement an anonymous Transmogrifier class.

    from('direct:input1')
        .transmogrify('myTransmogrifierBean')
        .to('mock:output')

    from('direct:input2')
        .transmogrify { body, headers ->
            def result = ... // create result from input body and headers
            return result    // return the transformation result
        }
        .to('mock:output')

This pattern also applies to all other DSL extensions for IPF module adapters: verify, parse, render, and aggregationStrategy.

Input and Parameters

Default arguments to the Transmogrifier.zap(S object, Object... params) method are:

• The in-message body for the object parameter.
• The in-message headers for the params parameter.

A transmogrify closure may define a one or two parameters:

• The first parameters corresponds to the object parameter of the zap method. The default argument is the in-message body.
• The second parameter corresponds to the params parameter of the zap method. The default argument is a Map containing the in-message headers.

Input to the zap method as well as the transmogrify closure can be customized via the following modifiers:

• input : Camel expression or closure to be used as input
• params: Camel expression or closure to be used as params
• staticParams: Object with static params

The following snippet causes the transmogrifier’s zap method to be called with the message’s foo-header as first argument and the messages bar-header as the second argument:

    from('direct:input')
        .transmogrify { fooHeader, barHeader ->
            // ...
        }
        .input { it.in.headers.foo }
        .params { it.in.headers.bar }
        .to('mock:output')

The params DSL extension also supports predefined expressions. These are accessible by calling params without arguments. The following predefined expressions are currently supported as part of the DSL:

• headers(): message headers (default for transmogrifiers)
• header('foo'): message foo-header
• builder(): a Groovy XML builder
• headersAndBuilder(): message headers and a Groovy XML builder (params array of length 2)

Thus, the example above could be rewritten to:

    from('direct:input')
        .transmogrify { fooHeader, barHeader ->
            // ...
        }
        .input { it.in.headers.foo }
        .params().header('bar')
        .to('mock:output')

The staticParams extension can be used to pass constant values to the transmogrifier or transmogrifier closure. This extension method defines a variable argument parameter. For example to pass a String array with elements ‘a’, ‘b’ and ‘c’:

    from('direct:input')
        .transmogrify { body, stringArray ->
            // ...
        }
        .staticParams('a', 'b', 'c')
        .to('mock:output')

Output

The return value of the Transmogrifier.zap(S object, Object... params) method or the return value of the transmogrify closure is written to the org.apache.camel.Exchange object from which the input was taken. It depends on the exchange pattern to which exchange message the result is written.

If the exchange is out-capable (i.e. exchange.getPattern().isOutCapable() returns true) then the result is written to the exchange’s out-message body, otherwise, it is written to the in-message body. Furthermore, if the exchange is out-capable, the in-message is copied onto the out-message before the result is written (this is useful e.g. for preserving message headers along a precessing chain).

Transmogrifier implementations

IPF provides three Transmogrifier implementations out of the box:

• org.openehealth.ipf.commons.xml.XsltTransmogrifier for xslt transforming XML documents
• org.openehealth.ipf.commons.xml.SchematronTransmogrifier for creating Schematron validation reports from XML documents
• org.openehealth.ipf.commons.xml.XqjTransmogrifier for xquering XML documents or collections

    from('direct:input1')
        .transmogrify().xslt().staticParams('path/to/stylesheet') // static stylesheet
        .to('mock:output')

    from('direct:input1')
        .transmogrify().xslt().staticParams('path/to/stylesheet', parameterMap) // static stylesheet with parameters
        .to('mock:output')

    from('direct:input3')
        .setHeader('stylesheet', constant('path/to/stylesheet'))
        .transmogrify().xslt().params().header('stylesheet') // dynamic stylesheet
        .to('mock:output')

    // In most cases you will need the SchematronValidator, which scans the Schematron report
    // for failed assertions. Use only if you require custom processing of the report in the
    // route.

    from('direct:input3')
        .transmogrify().schematron().staticParams('path/to/rules', options ) // static rules
        .to('mock:output')

    from('direct:input4')
        .setHeader('rules', constant('path/to/rules'))
        .transmogrify('schematron').params().header('rules') // dynamic rules
        .to('mock:output')

    from('direct:input1')
        .transmogrify().xslt(InputStream.class).staticParams('path/to/stylesheet')
        .to('mock:output')

    from('direct:input2')
        .transmogrify().xslt().staticParams('path/to/stylesheet')
        .convertBodyTo(InputStream.class)
        .to('mock:output')

    from('direct:input24') // using a dedicated XqjTransmogrifier bean
        .convertBodyTo(StreamSource.class)
        .transmogrify('xqj').staticParams('xquery/extract.xq', [id:'someid'])
        .to('mock:output')

    from('direct:input29') // passing classpath parameters as stream
        .transmogrify().xquery()
        .staticParams('xquery/extract-map-document.xq', [id:'someid',
            map: new StreamSource(new ClassPathResource('xquery/mapping.xml').getInputStream())])
        .to('mock:output')

    from('direct:input29') // passing parameters as map
        .transmogrify().xquery().params{
            [(XqjTransmogrifier.RESOURCE_LOCATION) : 'xquery/extract-map-document.xq',
              map: new StreamSource(new ClassPathResource('xquery/mapping.xml').getInputStream()),
              id:'someid']}
        .to('mock:output')

Skipping Validation

It is possible to switch off validation by means of a Camel message header. When there is input message header named org.openehealth.ipf.platform.camel.core.adapter.ValidatorAdapter#NEED_VALIDATION_HEADER_NAME and its value equals to Boolean.FALSE, the validation step will be skipped. This gives the possibility to validate conditionally based of user-defined properties and/or make it configurable e.g. via JMX.

Please be aware that the aforementioned Camel message header will remain untouched and deactivate subsequent validation steps as well.

XSD and Schematron validation

IPF provides a Validator implementation that validates an XML Source against an W3C XML Schema. The schema location value can be either a URL or a non-URL string, in the latter case the classpath is searched for the schema resource.

    from('direct:input1')
         .validate().xsd().staticProfile('schema location')
         .to('mock:output')

IPF also provides a Validator implementation that validates an XML Source against a set of Schematron rules.

    import org.openehealth.ipf.commons.xml.SchematronProfile;
    ...
    from('direct:input1')
         .validate().schematron().staticProfile(new SchematronProfile('rules location', options))
         .to('mock:output')

Note that you have to provide an instance of SchematronProfile, not just the plain Schematron rules location. The rules location value can be either a URL or a non-URL string, in the latter case the classpath is searched for the schema resource.

The options parameter is optional. If present, it must be of type Map<String, Object>. Its purpose is to configure Schematron’s validation process. Please refer to the Schematron website for more details.