Red Hat Training

A Red Hat training course is available for JBoss Enterprise SOA Platform

Chapter 16. Integrating Smooks With the JBoss Enterprise SOA Platform

16.1. Message Transformation

The JBoss Enterprise SOA Platform's message transformation functionality is provided by the SmooksAction component. This is an ESB Action module that allows you to plug the Smooks framework into an ESB action processing pipeline. This lets you set up an ESB action that exposes Smooks and needs a configuration file.

Note

Your JBoss Enterprise SOA Platform product comes with a number of sample transformation quick starts. Look at the transform_ quickstarts to gain an understanding of how they work. The XML2XML example is good to study when you are learning.

16.2. The resource-config Property

In its most basic configuration, message transformation uses a resource-config property that references a Smooks configuration file.
The value of the resource-config property can be any URI-based resource, as defined by the URIResourceLocator class: 
<action name="transform" class="org.jboss.soa.esb.actions.converters.SmooksTransformer">
        <property name="resource-config" value="/smooks-config.xml" ></property>
</action>

16.3. Input/Output Configuration

This action uses the MessagePayloadProxy to access the message payload. By default, it is configured to obtain the payload from the Message.Body.DEFAULT_LOCATION location. It will also return it to here after it has processed it.

Note

Override these default settings by altering the get-payload-location and set-payload-location action properties.

16.4. Java Output Configuration

  1. To transform your message into a Java object, observe the Transform_XML2POJO quickstarts examples.
  2. Use the constructed Java object models as part of a model-driven transformation. You can also allow them to be used by other ESB action instances that follow on after the SmooksAction in the pipeline. Such Java object graphs are available to subsequent pipeline action instances because they are attached to the ESB message output by this action and which is then input to the following actions.
  3. Attach the objects to the ESB message output using the Message.getBody().add(...) under a key based directly on the beanId objects as defined in the Smooks Java bean configuration. This means that the objects are available through the ESB Message Body by performing Body.get(beanId) calls.
  4. You can also attach the full Java object map to the output message by adding a java-output-location property: 
    <action name="transform" class="org.jboss.soa.esb.actions.converters.SmooksTransformer">
        <property name="resource-config" value="/smooks-config.xml" ></property>
        <property name="java-output-location" value="order-message-objects-map" ></property>
    </action>
  5. This is a shorthand way to bind the map to the Default Message Body Location: 
     <action name="transform" class="org.jboss.soa.esb.actions.converters.SmooksTransformer">
        <property name="resource-config" value="/smooks-config.xml" ></property>
        <property name="java-output-location" value="$default" ></property>
    </action>

16.5. Profile-Based Transformation

  1. To perform a profile-based transformation, observe the example below. You need to define a single transformation configuration file (smooks-config.xml). Messages are being exchanged between three different sources and one target destination. The ESB needs to transform the messages supplied (in different formats) by each of the different three sources into Java objects before sending them to the destination service. From an ESB perspective, there is a single service configuration for the destination: 
    <service category="ServiceCat" name="TargetService" description="Target Service">
        <listeners>
            <!-- Message listners for getting the message into the action pipeline... -->
            <jms-listener name="Gateway-Listener" busidref="quickstartGwChannel" is-gateway="true"></jms-listener>
            <jms-listener name="Service-Listener" busidref="quickstartEsbChannel"></jms-listener>
        </listeners>
        <actions>

            
            <action name="transform" class="org.jboss.soa.esb.actions.converters.SmooksTransformer">
                <property name="resource-config" value="/smooks-config.xml"></property>
            </action>

            <!-- An action to process the Java Object(s) -->
            <action name="process" class="com.acme.JavaProcessor" ></action>

        </actions>
    </service>
  2. Define three different transformation, one for each source. This is done using a Smooks Message Profiling.
  3. Store the definitions in three Smooks configuration files (from_source1.xml, from_source2.xml and from_source3.xml).
  4. In each of the above files, specify the default-target-profile for that configuration set: 
     <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.0.xsd" default-target-profile="from:source1">
        <!-- Source1 to Target Java message transformation resource configurations... -->
    </smooks-resource-list>
  5. Add those files to the top-level smooks-config.xml: 
    <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.0.xsd">
        <import file="classpath:/from_source1.xml" ></import>
        <import file="classpath:/from_source2.xml" ></import>
        <import file="classpath:/from_source3.xml" ></import>
    </smooks-resource-list>
    You have now configured the system to load a single SmooksAction instance with three different transformations, each of which is defined under it's own unique profile name.
  6. In order for the SmooksAction to know which of the three transformations is to be applied to a given message, you must set the message's from property before the message flows into the SmooksAction. You can either do this at the source itself or in a content-based action that precedes the SmooksAction.

    Note

    The JBoss Enterprise SOA Platform also supports other profiles in addition to from, namely from-type, to and to-type. You can use these combined, leading to more intricate exchange-based transformations.

16.6. Transform_XML2POJO2

Message transformations can be implemented as quickstarts called /samples/quickstarts/transform_XML2POJO2/. In this quickstart there are two message sources. The quickstart runs a Groovy script on the action pipeline that detects and sets the incoming message's from profile.

16.7. Transform_XML2POJO2 Files

These are the files used in transformations:
  • jboss-esb.xml: this is the JBoss ESB configuration file.
  • smooks-config.xml: this file contains the top-level transformation configuration.
  • from-dvdstore.xml: this contains the DVD Store message transformations configuration, which is imported into the top-level smooks-config.xml file. (Make note of the profile configuration.) This is configuration is designed to transform a DVD Store message into Java Objects.
  • from-petstore.xml: this file contains the Pet Store message transformations configuration, which is imported into the top-level smooks-config.xml file. (Make note of the profile configuration.) This is configuration is designed to transform a DVD Store message into Java Objects.
  • check-origin.groovy: this is a simple Groovy script that determines the origin of each message based on it's contents.