Procedure 3.1. Task

1. Create a new Smooks configuration. This will be used to apply the visitor logic at the <xxx> element's visitBefore and visitAfter events.
2. Apply the logic at the visitBefore and visitAfter events in a specific element of the overall event stream. The visitor logic is applied to the events in the <xxx> element.
3. Use Smooks with FreeMarker to perform an XML-to-XML transformation on a huge message.
4. Insert the following source format:

   <order id='332'>
       <header>
           <customer number="123">Joe</customer>
       </header>
       <order-items>
           <order-item id='1'>
               <product>1</product>
               <quantity>2</quantity>
               <price>8.80</price>
           </order-item>
   Â 
           <!-- etc etc -->
   Â 
       </order-items>
   </order>
   

5. Insert this target format:

   <salesorder>
       <details>
           <orderid>332</orderid>
           <customer>
               <id>123</id>
               <name>Joe</name>
           </customer>
       <details>
       <itemList>
           <item>
               <id>1</id>
               <productId>1</productId>
               <quantity>2</quantity>
               <price>8.80</price>
           <item>        
    
           <!-- etc etc -->
    
       </itemList>
   </salesorder>
   

6. Use this Smooks configuration:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
                         xmlns:ftl="http://www.milyn.org/xsd/smooks/freemarker-1.1.xsd">
    
       <!--
       Filter the message using the SAX Filter (i.e. not DOM, so no
       intermediate DOM for the "complete" message - there are "mini" DOMs
       for the NodeModels below)....
       -->
       <params>
           <param name="stream.filter.type">SAX</param>
           <param name="default.serialization.on">false</param>
       </params>
    
       <!--
       Create 2 NodeModels.  One high level model for the "order"
       (header etc) and then one per "order-item".
    
       These models are used in the FreeMarker templating resources
       defined below.  You need to make sure you set the selector such
       that the total memory footprint is as low as possible.  In this
       example, the "order" model will contain everything accept the
       <order-item> data (the main bulk of data in the message).  The
       "order-item" model only contains the current <order-item> data
       (i.e. there's max 1 order-item in memory at any one time).
       -->
       <resource-config selector="order,order-item">
           <resource>org.milyn.delivery.DomModelCreator</resource>
       </resource-config>
    
       <!--
       Apply the first part of the template when we reach the start
       of the <order-items> element.  Apply the second part when we
       reach the end.
    
       Note the <?TEMPLATE-SPLIT-PI?> Processing Instruction in the
       template.  This tells Smooks where to split the template,
       resulting in the order-items being inserted at this point.
       -->
       <ftl:freemarker applyOnElement="order-items">
           <ftl:template><!--<salesorder>
       <details>
           <orderid>${order.@id}</orderid>
           <customer>
               <id>${order.header.customer.@number}</id>
               <name>${order.header.customer}</name>
           </customer>
       </details>
       <itemList>
           <?TEMPLATE-SPLIT-PI?>
       </itemList>
   </salesorder>--></ftl:template>
       </ftl:freemarker>
    
       <!--
       Output the <order-items> elements.  This will appear in the
       output message where the <?TEMPLATE-SPLIT-PI?> token appears in the
       order-items template.
       -->
       <ftl:freemarker applyOnElement="order-item">
           <ftl:template><!--        <item>
               <id>${.vars["order-item"].@id}</id>
               <productId>${.vars["order-item"].product}</productId>
               <quantity>${.vars["order-item"].quantity}</quantity>
               <price>${.vars["order-item"].price}</price>
           </item>
           --></ftl:template>
       </ftl:freemarker>
    
   </smooks-resource-list>
   

7. Use this code to execute:

   Smooks smooks = new Smooks("smooks-config.xml");
   try {
       smooks.filterSource(new StreamSource(new FileInputStream("input-message.xml")), new StreamResult(System.out));
   } finally {
       smooks.close();
   }
   

8. An XML-to-XML transformation occurs as a result.

Procedure 3.2. Task

• Configure namespace prefix-to-URI mappings through the core configuration namespace and modify the following XML code to include the namespaces you wish to use:

  <?xml version="1.0"?>
  <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
      xmlns:core="http://www.milyn.org/xsd/smooks/smooks-core-1.3.xsd">
  
      <core:namespaces>
          <core:namespace prefix="a" uri="http://a"/>
          <core:namespace prefix="b" uri="http://b"/>
          <core:namespace prefix="c" uri="http://c"/>
          <core:namespace prefix="d" uri="http://d"/>
      </core:namespaces>
  
      <resource-config selector="c:item[@c:code = '8655']/d:units[text() = 1]">
          <resource>com.acme.visitors.MyCustomVisitorImpl</resource>
      </resource-config>
  
  </smooks-resource-list>
  

1. Configure the DomModelCreator from within Smooks to create models for the order and order-item message fragments. See the following example:

   <resource-config selector="order,order-item">
       <resource>org.milyn.delivery.DomModelCreator</resource>
   </resource-config>
   

2. Configure the in-memory model for the order as shown:

   <order id='332'>
        <header>
            <customer number="123">Joe</customer>
        </header>
        <order-items />
   </order>
   

   Note

   Each new model overwrites the previous one so there will never be more than one order-item model in memory at once.

1. To have the contents of the bean context returned at the end of a Smooks.filterSource process, supply a org.milyn.delivery.java.JavaResult object in the call to the Smooks.filterSource method. This example shows you how:

    //Get the data to filter
   StreamSource source = new StreamSource(getClass().getResourceAsStream("data.xml"));
   
   //Create a Smooks instance (cachable)
   Smooks smooks = new Smooks("smooks-config.xml");
   
   //Create the JavaResult, which will contain the filter result after filtering
   JavaResult result = new JavaResult();
   
   //Filter the data from the source, putting the result into the JavaResult
   smooks.filterSource(source, result);
   
   //Getting the Order bean which was created by the Javabean cartridge
   Order order = (Order)result.getBean("order");
   

2. To access the bean contexts at start-up, specify this in the BeanContext object. You can retrieve it from the ExecutionContext via the getBeanContext() method.
3. When adding or retrieving objects from the BeanContext make sure you first retrieve a beanId object from the beanIdStore. (The beanId object is a special key that ensures higher performance than string keys, although string keys are also supported.)
4. You must retrieve the beanIdStore from the ApplicationContext using the getbeanIdStore() method.
5. To create a beanId object, call the register("beanId name") method. (If you know that the beanId is already registered, then you can retrieve it by calling the getbeanId("beanId name") method.)
6. beanId objects are ApplicationContext-scoped objects. Register them in your custom visitor implementation's initialization method and then put them in the visitor object as properties. You can then use them in the visitBefore and visitAfter methods. (The beanId objects and the beanIdStore are thread-safe.)

• Supply Smooks with multiple result instances as seen in the API:

  public void filterSource(Source source, Result... results) throws SmooksException
  

  Note

  Smooks does not support capturing result data from multiple result instances of the same type. For example, you can specify multiple StreamResult instances in the Smooks.filterSource method call, but Smooks will only output to one of these StreamResult instances (the first one).

1. To obtain an execution report from Smooks you must configure the ExecutionContext class to produce one. (Smooks will publish events as it processes messages.) The following sample code shows you how to configure Smooks to generate a HTML report:

   Smooks smooks = new Smooks("/smooks/smooks-transform-x.xml");
   ExecutionContext execContext = smooks.createExecutionContext();
   
   execContext.setEventListener(new HtmlReportGenerator("/tmp/smooks-report.html"));
   smooks.filterSource(execContext, new StreamSource(inputStream), new StreamResult(outputStream));
   

2. Use the HtmlReportGenerator feature to assist you when debugging.

   Note

   You can see a sample report on this web page: http://www.milyn.org/docs/smooks-report/report.html

   Note

   Alternatively, you can create a custom ExecutionEventListener implementation.

1. To terminate the Smooks filtering process before the end of the message is reached, add the <core:terminate> configuration to the Smooks settings. (This works for SAX and is not needed for DOM.)
   Here is an example configuration that terminates filtering at the end of the message's customer fragment:

   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" 
      xmlns:core="http://www.milyn.org/xsd/smooks/smooks-core-1.3.xsd">
   
       <!-- Visitors... -->
       <core:terminate onElement="customer" />
   
   </smooks-resource-list>

2. To terminate at the beginning of a message (on the visitBefore event), use this code:

   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" 
      xmlns:core="http://www.milyn.org/xsd/smooks/smooks-core-1.3.xsd">
   
      <!-- Visitors... -->
   
      <core:terminate onElement="customer" terminateBefore="true" />
   
   </smooks-resource-list>

1. Global parameters are specified in a <params> element as shown:

   <params>
       <param name="xyz.param1">param1-val</param>
   </params>
   

2. Access the global parameters via the ExecutionContext:

   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" 
       xmlns:xsl="http://www.milyn.org/xsd/smooks/xsl-1.1.xsd" 
       default-selector="order">
   
       <resource-config>
           <resource>com.acme.VisitorA</resource>
           ...
       </resource-config>
   
       <resource-config>
           <resource>com.acme.VisitorB</resource>
           ...
       </resource-config>
   
   <smooks-resource-list>
   

• To set filtering options, use the smooks-core configuration namespace. See the following example:

  ;smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" 
     xmlns:core="http://www.milyn.org/xsd/smooks/smooks-core-1.3.xsd">
     <core:filterSettings type="SAX" defaultSerialization="true" 
        terminateOnException="true" readerPoolSize="3" closeSource="true" 
        closeResult="true" rewriteEntities="true" />
  
        .. Other visitor configs etc...
  
  </smooks-resource-list>
  

• By default, Smooks reads XML data. To set features on the default XML reader, omit the class name from the configuration:

  <reader>
      <features>
          <setOn feature="http://a" />
          <setOn feature="http://b" />
          <setOff feature="http://c" />
          <setOff feature="http://d" />
      </features>
  </reader>
  

1. Use the http://www.milyn.org/xsd/smooks/csv-1.2.xsd configuration namespace to configure the reader.
   Here is a basic configuration:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:csv="http://www.milyn.org/xsd/smooks/csv-1.2.xsd">
    
       <!--
       Configure the CSV to parse the message into a stream of SAX events.
       -->
       <csv:reader fields="firstname,lastname,gender,age,country" separator="|" quote="'" skipLines="1" />
    
   </smooks-resource-list>
   

2. You will see the following event stream:

   <csv-set>
       <csv-record>
           <firstname>Tom</firstname>
           <lastname>Fennelly</lastname>
           <gender>Male</gender>
           <age>21</age>
           <country>Ireland</country>
       </csv-record>
       <csv-record>
           <firstname>Tom</firstname>
           <lastname>Fennelly</lastname>
           <gender>Male</gender>
           <age>21</age>
           <country>Ireland</country>
       </csv-record>
   </csv-set>
   

1. To define fields in XML configurations you must use a comma-separated list of names in the fields attribute.
2. Make sure the field names follow the same naming rules as XML element names:
3. • they can contain letters, numbers, and other characters
   • they cannot start with a number or punctuation character
   • they cannot start with the letters xml (or XML or Xml, etc)
   • they cannot contain spaces
4. Set the rootElementName and recordElementName attributes so you can modify the csv-set and csv-record element names. The same rules apply for these names.
5. You can define string manipulation functions on a per-field basis. These functions are executed before the data is converted into SAX events. Define them after the field name, separating the two with a question mark:

   
   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:csv="http://www.milyn.org/xsd/smooks/csv-1.2.xsd">
    
       <csv:reader fields="lastname?trim.capitalize,country?upper_case" />
    
   </smooks-resource-list>
   
   

6. To get Smooks to ignore fields in a CSV record, you must specify the $ignore$ token as the field's configuration value. Specify the number of fields to be ignored simply by following the $ignore$ token with a number (so use $ignore$3 to ignore the next three fields.) Use $ignore$+ to ignore all of the fields to the end of the CSV record.

   
   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:csv="http://www.milyn.org/xsd/smooks/csv-1.2.xsd">
    
       <csv:reader fields="firstname,$ignore$2,age,$ignore$+" />
    
   </smooks-resource-list>
   
   

1. Read the following to learn how to CSV records to Java objects. In this example, we will use CSV records for people:

   Tom,Fennelly,Male,4,Ireland
   Mike,Fennelly,Male,2,Ireland
   

2. Input this code to bind the record to a person:

   
   public class Person {
       private String firstname;
       private String lastname;
       private String country;
       private Gender gender;
       private int age;
   }
    
   public enum Gender {
       Male, 
       Female;
   }
   
   

3. Input the following code and modify it to suit your task:

   
   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:csv="http://www.milyn.org/xsd/smooks/csv-1.2.xsd">
    
       <csv:reader fields="firstname,lastname,gender,age,country">
           <!-- Note how the field names match the property names on the Person class. -->
           <csv:listBinding beanId="people" class="org.milyn.csv.Person" />
       </csv:reader>
    
   </smooks-resource-list>
   

4. To execute the configuration, use this code:

   
   Smooks smooks = new Smooks(configStream);
   JavaResult result = new JavaResult();
    
   smooks.filterSource(new StreamSource(csvStream), result);
    
   List<Person> people = (List<Person>) result.getBean("people");
   

5. You can create Maps from the CSV record set:

   
   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:csv="http://www.milyn.org/xsd/smooks/csv-1.2.xsd">
    
       <csv:reader fields="firstname,lastname,gender,age,country">
           <csv:mapBinding beanId="people" class="org.milyn.csv.Person" keyField="firstname" />
       </csv:reader>
    
   </smooks-resource-list>
   
   

6. The configuration above produces a map of person instances, keyed to the firstname value of each person. This is how it is executed:

   
   Smooks smooks = new Smooks(configStream);
   JavaResult result = new JavaResult();
    
   smooks.filterSource(new StreamSource(csvStream), result);
    
   Map<String, Person> people = (Map<String, Person>) result.getBean("people");
    
   Person tom = people.get("Tom");
   Person mike = people.get("Mike");
   
   

   Virtual models are also supported, so you can define the class attribute as a java.util.Map and bind the CSV field values to map instances which are, in turn, added to a list or map.

1. To configure a Smooks instance with a CSV reader to read a person record set, use the code below. It will bind the records to a list of person instances.

   
   Smooks smooks = new Smooks();
    
   smooks.setReaderConfig(new CSVReaderConfigurator("firstname,lastname,gender,age,country")
                     .setBinding(new CSVBinding("people", Person.class, CSVBindingType.LIST)));
    
   JavaResult result = new JavaResult();
   smooks.filterSource(new StreamSource(csvReader), result);
    
   List<Person> people = (List<Person>) result.getBean("people");
   
   

   Note

   You can also optionally configure the Java Bean. The Smooks instance could instead (or additionally) be configured programmatically to use other visitor implementations to process the CSV record set.
2. To bind the CSV's records to a list or map of a Java type that reflects the data in your CSV records, use the CSVListBinder or CSVMapBinder classes:

   
   // Note: The binder instance should be cached and reused...
   CSVListBinder binder = new CSVListBinder("firstname,lastname,gender,age,country", Person.class);
    
   List<Person> people = binder.bind(csvStream);
   
   CSVMapBinder:
   
   // Note: The binder instance should be cached and reused...
   CSVMapBinder binder = new CSVMapBinder("firstname,lastname,gender,age,country", Person.class, "firstname");
    
   Map<String, Person> people = binder.bind(csvStream);
   
   

   If you need more control over the binding process, revert back to using the lower-level APIs.

1. To configure the fixed-length reader, modify the http://www.milyn.org/xsd/smooks/fixed-length-1.3.xsd configuration namespace as shown below:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:fl="http://www.milyn.org/xsd/smooks/fixed-length-1.3.xsd">
    
       <!--
       Configure the Fixed length to parse the message into a stream of SAX events.
       -->
       <fl:reader fields="firstname[10],lastname[10],gender[1],age[2],country[2]" skipLines="1" />
    
   </smooks-resource-list>
   
   

   Here is an example input file:

   #HEADER
   Tom       Fennelly  M 21 IE
   Maurice  Zeijen     M 27 NL
   

   Here is the event stream that will be generated:

   
   <set>
       <record>
           <firstname>Tom       </firstname>
           <lastname>Fennelly  </lastname>
           <gender>M</gender>
           <age> 21</age>
           <country>IE</country>
       </record>
       <record>
           <firstname>Maurice  </firstname>
           <lastname>Zeijen     </lastname>
           <gender>M</gender>
           <age>27</age>
           <country>NL</country>
       </record>
   </set>
   ]]>
   

2. Define the string manipulation functions as shown below:

   
   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:fl="http://www.milyn.org/xsd/smooks/fixed-length-1.3.xsd">
    
       <!--
       Configure the fixed length reader to parse the message into a stream of SAX events.
       -->
       <fl:reader fields="firstname[10]?trim,lastname[10]trim.capitalize,gender[1],age[2],country[2]" skipLines="1" />
    
   </smooks-resource-list>
   
   

3. You can also ignore these fields if you choose:

   
   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:fl="http://www.milyn.org/xsd/smooks/fixed-length-1.3.xsd">
    
       <fl:reader fields="firstname,$ignore$[2],age,$ignore$[10]" />
    
   </smooks-resource-list>
   
   

1. To bind fixed-length records to a person, see the configuration below. In this example we will use these sample records:

   Tom       Fennelly  M 21 IE
   Maurice  Zeijen     M 27 NL
   

   This is how you bind them to a person:

   [
   public class Person {
       private String firstname;
       private String lastname;
       private String country;
       private String gender;
       private int age;
   }
   
   

2. Configure the records so they look like this:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"  xmlns:fl="http://www.milyn.org/xsd/smooks/fixed-length-1.3.xsd">
    
       <fl:reader fields="firstname[10]?trim,lastname[10]?trim,gender[1],age[3]?trim,country[2]">
           <!-- Note how the field names match the property names on the Person class. -->
           <fl:listBinding BeanId="people" class="org.milyn.fixedlength.Person" />
       </fl:reader>
    
   </smooks-resource-list>
   
   

3. Execute it as shown:

   Smooks smooks = new Smooks(configStream);
   JavaResult result = new JavaResult();
    
   smooks.filterSource(new StreamSource(fixedLengthStream), result);
    
   List<Person> people = (List<Person>) result.getBean("people");
   
   

4. Optionally, use this configuration to create maps from the fixed-length record set:

   
   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"  xmlns:fl="http://www.milyn.org/xsd/smooks/fixed-length-1.3.xsd">
    
       <fl:reader fields="firstname[10]?trim,lastname[10]?trim,gender[1],age[3]?trim,country[2]">
           <fl:mapBinding BeanId="people" class="org.milyn.fixedlength.Person" keyField="firstname" />
       </fl:reader>
   

5. This is how you execute the map of person instances that is produced:

   Smooks smooks = new Smooks(configStream);
   JavaResult result = new JavaResult();
    
   smooks.filterSource(new StreamSource(fixedLengthStream), result);
    
   Map<String, Person> people = (Map<String, Person>) result.getBean("people");
    
   Person tom = people.get("Tom");
   Person mike = people.get("Maurice");
   

   Virtual Models are also supported, so you can define the class attribute as a java.util.Map and bind the fixed-length field values to map instances, which are in turn added to a list or a map.

1. Use this code to configure the fixed-length reader to read a person record set, binding the record set into a list of person instances:

   Smooks smooks = new Smooks();
    
   smooks.setReaderConfig(new FixedLengthReaderConfigurator("firstname[10]?trim,lastname[10]?trim,gender[1],age[3]?trim,country[2]")
                     .setBinding(new FixedLengthBinding("people", Person.class, FixedLengthBindingType.LIST)));
    
   JavaResult result = new JavaResult();
   smooks.filterSource(new StreamSource(fixedLengthStream), result);
    
   List<Person> people = (List<Person>) result.getBean("people");
   

   Configuring the Java binding is not mandatory. You can instead programmatically configure the Smooks instance to use other visitor implementations to carry out various forms of processing on the fixed-length record set.
2. To bind fixed-length records directly to a list or map of a Java type that reflects the data in your fixed-length records, use either the FixedLengthListBinder or the FixedLengthMapBinder classes:

   // Note: The binder instance should be cached and reused...
   FixedLengthListBinder binder = new FixedLengthListBinder("firstname[10]?trim,lastname[10]?trim,gender[1],age[3]?trim,country[2]", Person.class);
    
   List<Person> people = binder.bind(fixedLengthStream);
   
   FixedLengthMapBinder:
   
   // Note: The binder instance should be cached and reused...
   FixedLengthMapBinder binder = new FixedLengthMapBinder("firstname[10]?trim,lastname[10]?trim,gender[1],age[3]?trim,country[2]", Person.class, "firstname");
    
   Map<String, Person> people = binder.bind(fixedLengthStream);
   

   If you need more control over the binding process, revert back to the lower level APIs.

1. To utilize EDI processing in Smooks, access the http://www.milyn.org/xsd/smooks/edi-1.2.xsd configuration namespace.
2. Modify this configuration to suit your needs:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:edi="http://www.milyn.org/xsd/smooks/edi-1.2.xsd">    
    <!--
       Configure the EDI Reader to parse the message stream into a stream of SAX events.
       -->
       <edi:reader mappingModel="edi-to-xml-order-mapping.xml" validate="false"/>
   </smooks-resource-list>
   

• Use the EDIReaderConfigurator to programmatically configure the Smooks instance to use the EDIReader as shown in the code below:

  Smooks smooks = new Smooks();
   
  // Create and initialise the Smooks config for the parser...
  smooks.setReaderConfig(new EDIReaderConfigurator("/edi/models/invoice.xml"));
   
  // Use the smooks as normal
  smooks.filterSource(....);
  

• To execute the Edifact Java Compiler through Maven, add the plug-in in your POM file:

  <build>
      <plugins>
          <plugin>
              <groupId>org.milyn</groupId>
              <artifactId>maven-ejc-plugin</artifactId>
              <version>1.2</version>
              <configuration>
                  <ediMappingFile>edi-model.xml</ediMappingFile>
                  <packageName>com.acme.order.model</packageName>
              </configuration>
              <executions>
                  <execution><goals><goal>generate</goal></goals></execution>
              </executions>
          </plugin>
      </plugins>
  </build>
  

• Create and execute the EJC task as shown below:

  <target name="ejc">
   
      <taskdef resource="org/milyn/ejc/ant/anttasks.properties">
          <classpath><fileset dir="/smooks-1.2/lib" includes="*.jar"/></classpath>
      </taskdef>
   
      <ejc edimappingmodel="src/main/resources/edi-model.xml"
           destdir="src/main/java"
           packagename="com.acme.order.model"/>
   
      <!-- Ant as usual from here on... compile and jar the source... -->
   
  </target>
  

• Set the http://www.milyn.org/xsd/smooks/unedifact-1.4.xsd namespace like this:

  <?xml version="1.0"?>
  <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:unedifact="http://www.milyn.org/xsd/smooks/unedifact-1.4.xsd">
   
      <unedifact:reader mappingModel="urn:org.milyn.edi.unedifact:d03b-mapping:v1.4" ignoreNewLines="true" />
   
  </smooks-resource-list>
  

  The mappingModel attribute defines an URN that refers to the mapping model ZIP set's Maven artifact, which is used by the reader.

1. To programmatically configure Smooks to consume a UN/EDIFACT interchange (via, for instance, an UNEdifactReaderConfigurator), use the code below:

   Smooks smooks = new Smooks();
    
   smooks.setReaderConfig(new UNEdifactReaderConfigurator("urn:org.milyn.edi.unedifact:d03b-mapping:v1.4"));
   

2. Insert the following on the containing application's classpath:
   • the requisite EDI mapping models
   • the Smooks EDI cartridge
3. There may be some Maven dependancies your configuration will require. See the example below:

   <dependency>
       <groupId>org.milyn</groupId>
       <artifactId>milyn-smooks-edi</artifactId>
       <version>1.4</version>
   </dependency>
    
   <!-- Required Mapping Models -->
   <dependency>
       <groupId>org.milyn.edi.unedifact</groupId>
       <artifactId>d93a-mapping</artifactId>
       <version>v1.4</version>
   </dependency>
   <dependency>
       <groupId>org.milyn.edi.unedifact</groupId>
       <artifactId>d03b-mapping</artifactId>
       <version>v1.4</version>
   </dependency>
   

4. Once an application has added an EDI mapping model ZIP set to its classpath, you can configure Smooks to use this model by simply referencing the Maven artifact using a URN as the unedifact:reader configuration's mappingModel attribute value:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:unedifact="http://www.milyn.org/xsd/smooks/unedifact-1.4.xsd"
    
       <unedifact:reader mappingModel="urn:org.milyn.edi.unedifact:d03b-mapping:v1.4" ignoreNewLines="true" />
    
   </smooks-resource-list>
   

1. To add the D93A mapping model ZIP set to your application classpath, set the following dependency to your application's POM file:

   <!-- The mapping model sip set for the D93A directory... -->
   <dependency>
       <groupId>org.milyn.edi.unedifact</groupId>
       <artifactId>d93a-mapping</artifactId>
       <version>v1.4</version>
   </dependency>
   

2. Configure Smooks to use this ZIP set by adding the unedifact:reader configuration to your Smooks configuration as shown below:

   <unedifact:reader mappingModel="urn:org.milyn.edi.unedifact:d93a-mapping:v1.4" />
   

   Note how you configure the reader using a URN derived from the Maven artifac's dependency information.
3. You can also add multiple mapping model ZIP sets to your application's classpath. To do so, add all of them to your unedifact:reader configuration by comma-separating the URNs.
4. Pre-generated Java binding model sets are provided with the tool (there is one per mapping model ZIP set). Use these to process UN/EDIFACT interchanges using a very simple, generated factory class.

1. To process a D03B UN/EDIFACT message interchange, follow the example below:

   
   Reading:
   
   // Create an instance of the EJC generated factory class... cache this and reuse !!!
   D03BInterchangeFactory factory = D03BInterchangeFactory.getInstance();
    
   // Deserialize the UN/EDIFACT interchange stream to Java...
   UNEdifactInterchange interchange = factory.fromUNEdifact(ediInStream);
    
   // Need to test which interchange syntax version.  Supports v4.1 at the moment...
   if(interchange instanceof UNEdifactInterchange41) {
       UNEdifactInterchange41 interchange41 = (UNEdifactInterchange41) interchange;
    
       for(UNEdifactMessage41 message : interchange41.getMessages()) {
           // Process the messages...
    
           Object messageObj = message.getMessage();
    
           if(messageObj instanceof Invoic) {
               // It's an INVOIC message....
               Invoic invoic = (Invoic) messageObj;
               ItemDescription itemDescription = invoic.getItemDescription();
               // etc etc....
           } else if(messageObj instanceof Cuscar) {
               // It's a CUSCAR message...
           } else if(etc etc etc...) {
               // etc etc etc...
           }
       }
   }
   
   
   Writing:
   
   factory.toUNEdifact(interchange, ediOutStream);
   
   

2. Use Maven to add the ability to process a D03B message interchange by adding the binding dependency for that directory (you can also use pre-generated UN/EDIFACT Java object models distributed via the MavenSNAPSHOT and Central repositories):

   <dependency>
       <groupId>org.milyn.edi.unedifact</groupId>
       <artifactId>d03b-binding</artifactId>
       <version>v1.4</version>
   </dependency>
   

1. To process JSON data, you must configure a JSON reader:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:json="http://www.milyn.org/xsd/smooks/json-1.1.xsd">
    
       <json:reader/>
    
   </smooks-resource-list>
   

2. Set the XML names of the root, document and array elements by using the following configuration options:
   • rootName: this is the name of the root element. The default is yaml.
   • elementName: this is the name of a sequence element. The default is element.
3. You may wish to use characters in the key name that are not allowed in the XML element name. The reader offers multiple solutions to this problem. It can search and replace white spaces, illegal characters and the number in key names that start with a number. You can also use it to replace one key name with a completely different one. The following sample code shows you how to do this:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:json="http://www.milyn.org/xsd/smooks/json-1.1.xsd">
    
       <json:reader keyWhitspaceReplacement="_" keyPrefixOnNumeric="n" illegalElementNameCharReplacement=".">
           <json:keyMap>
               <json:key from="some key">someKey</json:key>
               <json:key from="some&key" to="someAndKey" />
           </json:keyMap>
       </json:reader>
    
   </smooks-resource-list>
   

   • keyWhitspaceReplacement: this is the replacement character for white spaces in a JSON map key. By default this is not defined, so the reader does not automatically search for white spaces.
   • keyPrefixOnNumeric: this is the prefix character to add if the JSON node name starts with a number. By default, this is not defined, so the reader does not search for element names that start with a number.
   • illegalElementNameCharReplacement: if illegal characters are encountered in a JSON element name then they are replaced with this value.
4. You can also configure these optional settings:
5. • nullValueReplacement: this is the replacement string for JSON null values. The default is an empty string.
   • encoding: this is the default encoding of any JSON message InputStream processed by the reader. The default encoding is UTF-8.

     Note

     This feature is deprecated. Instead, you should now manage the JSON streamsource character encoding by supplying a java.io.Reader to the Smooks.filterSource() method.
6. To configure Smooks programmatically to read a JSON configuration, use the JSONReaderConfiguratorclass:

   Smooks smooks = new Smooks();
    
   smooks.setReaderConfig(new JSONReaderConfigurator()
           .setRootName("root")
           .setArrayElementName("e"));
    
   // Use Smooks as normal...
   

Procedure 4.1. Task

1. Configure your reader to process YAML files as shown:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:yaml="http://www.milyn.org/xsd/smooks/yaml-1.4.xsd">
    
       <yaml:reader/>
    
   </smooks-resource-list>
   

2. Configure the YAML stream to contain multiple documents. The reader handles this by adding a document element as a child of the root element. An XML-serialized YAML stream with one empty YAML document looks like this:

   <yaml>
       <document>
       </document>
   </yaml>
   

3. Configure Smooks programmatically to read a YAML configuration by exploiting the YamlReaderConfigurator class:

   Smooks smooks = new Smooks();
    
   smooks.setReaderConfig(new YamlReaderConfigurator()
           .setRootName("root")
           .setDocumentName("doc")
           .setArrayElementName("e"))
           .setAliasStrategy(AliasStrategy.REFER_RESOLVE)
           .setAnchorAttributeName("anchor")
           .setAliasAttributeName("alias");
    
   // Use Smooks as normal...
   

• You can use characters in the key name that are not allowed in the XML element name. The reader offers multiple solutions to this problem. It can search and replace white spaces, illegal characters and the number in key names that start with a number. You can configure it to replace one key name with a completely different one, as shown below:

  <?xml version="1.0"?>
  <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:yaml="http://www.milyn.org/xsd/smooks/yaml-1.4.xsd">
   
      <yaml:reader keyWhitspaceReplacement="_" keyPrefixOnNumeric="n" illegalElementNameCharReplacement=".">
          <yaml:keyMap>
              <yaml:key from="some key">someKey</yaml:key>
              <yaml:key from="some&key" to="someAndKey" />
          </yaml:keyMap>
      </yaml:reader>
   
  </smooks-resource-list>
  

1. Smooks can transform one Java object graph into another. To do this, it uses the SAX processing model, which means no intermediate object model is constructed. Instead, the source Java object graph is turned directly into a stream of SAX events, which are used to populate the target Java object graph.
   If you use the HTML Smooks Report Generator tool, you will see that the event stream produced by the source object model is as follows:

   <example.srcmodel.Order>
       <header>
           <customerNumber>
               </customerNumber>
              <customerName>
          </customerName>;
       </header>
       <orderItems>
           <example.srcmodel.OrderItem>
               <productId>
              </productId>
               <quantity>
               >/quantity>
               <price>
               </price>
           </example.srcmodel.OrderItem>
       </orderItems>
   </example.srcmodel.Order>
   

2. Aim the Smooks Java bean resources at this event stream. The Smooks configuration for performing this transformation (smooks-config.xml) is as follows:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.4.xsd">
    
       <jb:bean BeanId="lineOrder" class="example.trgmodel.LineOrder" createOnElement="example.srcmodel.Order">
           <jb:wiring property="lineItems" BeanIdRef="lineItems" />
           <jb:value property="customerId" data="header/customerNumber" />
           <jb:value property="customerName" data="header/customerName" />
       </jb:bean<
    
       <jb:bean BeanId="lineItems" class="example.trgmodel.LineItem[]" createOnElement="orderItems">
           <jb:wiring BeanIdRef="lineItem" />
       </jb:bean>
    
    
       <jb:bean BeanId="lineItem" class="example.trgmodel.LineItem" createOnElement="example.srcmodel.OrderItem">
           <jb:value property="productCode" data="example.srcmodel.OrderItem/productId" />
           <jb:value property="unitQuantity" data="example.srcmodel.OrderItem/quantity" />
           <jb:value property="unitPrice" data="example.srcmodel.OrderItem/price" />
       </jb:bean>
    
   </smooks-resource-list>
   

3. The source object model is provided to Smooks via a org.milyn.delivery.JavaSource object. Create this object by passing the constructor the source model's root object. The resulting Java Source object is used in the Smooks#filter method. Here is the resulting code:

   protected LineOrder runSmooksTransform(Order srcOrder) throws IOException, SAXException {
       Smooks smooks = new Smooks("smooks-config.xml");
       ExecutionContext executionContext = smooks.createExecutionContext();
    
       // Transform the source Order to the target LineOrder via a
       // JavaSource and JavaResult instance...
       JavaSource source = new JavaSource(srcOrder);
       JavaResult result = new JavaResult();
    
       // Configure the execution context to generate a report...
       executionContext.setEventListener(new HtmlReportGenerator("target/report/report.html"));
    
       smooks.filterSource(executionContext, source, result);
    
       return (LineOrder) result.getBean("lineOrder");
   }
   

1. Use this example code to configure a Regex ruleBase:

   <?xml version="1.0"?>
   <smooks-resource-list  xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"  xmlns:rules="http://www.milyn.org/xsd/smooks/rules-1.0.xsd">
    
       <rules:ruleBases>
           <rules:ruleBase name="customer" src="/org/milyn/validation/order/rules/customer.properties" provider="org.milyn.rules.regex.RegexProvider"/>
       </rules:ruleBases>
    
   </smooks-resource-list>
   

2. Define the Regex expressions in a standard .properties file format. The following customer.properties Regex rule definition file example shows you how:

   # Customer data rules...
   customerId=[A-Z][0-9]{5}
   customerName=[A-Z][a-z]*, [A-Z][a-z]
   

1. To configure an MVEL ruleBase, see the code below:

   <?xml version="1.0"?>
   <smooks-resource-list  xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"  xmlns:rules="http://www.milyn.org/xsd/smooks/rules-1.0.xsd">
    
       <rules:ruleBases>
           <rules:ruleBase name="order" src="/org/milyn/validation/order/rules/order-rules.csv" provider="org.milyn.rules.mvel.MVELProvider"/>
       </rules:ruleBases>
    
   </smooks-resource-list>
   

2. You must store your MVEL rules in CSV files. The easiest way to edit these files is through a spreadsheet application such as LibreOffice Calc or Gnumeric. Each rule record contains a rule name and an MVEL expression.
3. If you wish to create comment and header rows, prefix the first field with a hash (#) character.

1. You can set a maximum number of validation failures per Smooks filter operation. (An exception will be thrown if this maximum is exceeded.) Validations configured with OnFail.FATAL will always throw an exception and stop processing.
   To configure the maximum validation failures, add this code to your Smooks configuration:

   <params>
       <param name="validation.maxFails">5</param>
   </params>
   

2. The onFail attribute in the validation configuration specifies what action is to be taken. This determines how validation failures are to be reported. To utilize it, modify the following options to suit your needs:
   • OK: Use this to save the validation as "okay". By calling ValidationResults.getOks all validation warnings will be returned. This option is useful for content-based routing.
   • WARN: Use this to save the validation as a warning. By calling ValidationResults.getWarnings all validation warnings will be returned.
   • ERROR: Use this to save the validation as an error. By calling ValidationResults.getErrors you will return all validation errors.
   • FATAL: Use this to throw a ValidationException as soon as a validation failure occurs. If you call ValidationResults.getFatal you will see the fatal validation failure.

• Use a composite rule name in the following format for a rule base:

  <ruleProviderName>.<ruleName>
  

  • ruleProviderName identifies the rule provider and maps to the name attribute in the ruleBase element.
  • ruleName identifies a specific rule the rule provider knows about. This could be a rule defined in the src file.

• To run validaton rules, go to the example root folder and execute:
  1. mvn clean install
  2. mvn exec:java

1. When processing an order message, you should perform a number of validations. First, check that the supplied username follows a format of an upper case character, followed by five digits (for example, S12345 or G54321). To perform this validation, you should use regular expression.
2. Next, check that the supplied e-mail address is in a valid format. Use a regular expression to check it.
3. Confirm that each order item's productId field follows a format of exactly three digits (such as 123). Use a regular expression to do this.
4. Finally, you need to confirm that the total for each order item does not exceed 50.00 (price * quantity is not greater than 50.00). Perform this validation using an MVEL expression.

1. To use an MVEL expression on a rule set, divide the Regex rules and place them in two separate .properties files.
2. Drop these rules into the example rules directory.
3. Put the MVEL expression in a .csv file, also in the rules directory.
   The customer-related Regex rules that go in the customer.properties file look like this:

   # Customer data rules...
   customerId=[A-Z][0-9]{5}
    
   # Email address...
   email=^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$
   

4. Insert the product-related Regex rule in the product.properties file:

   # Product data rules...
   productId=[0-9]{3}
   

5. Insert the MVEL expression for performing the order item total check into the order-rules.csv file.

   Note

   The easiest way to edit a .csv file is through using a spreadsheet application like LibeOffice Calc or Gnumeric.
6. Create resource bundle .properties files for each of the rule source files.

   Note

   The names of these files are derived from the names of their corresponding rule files.
   The message bundle for the rules defined in rules/customer.properties is located in the rules/i18n/customer.properties file:

   customerId=ftl:Invalid customer number '${ruleResult.text}' at '${path}'.  
   <!--  Customer number must begin with an uppercase character, followed by 5 digits. -->
   email=ftl:Invalid email address '${ruleResult.text}' at '${path}'.  
   <!--  Email addresses match pattern '${ruleResult.pattern}'. -->
   

   The message bundle for the rule defined in rules/product.properties is located in the rules/i18n/product.properties file:

   # Product data rule messages...
   productId=ftl:Invalid product ID '${ruleResult.text}' at '${path}'. 
   <!--  Product ID must match pattern '${ruleResult.pattern}'. -->
   

   The message bundle for the rule defined in rules/order-rules.csv is located in the rules/i18n/order-rules.properties file:

   # <!--  Order item rule messages. The "orderDetails" and "orderItem" beans are populated by Smooks bindings - see config in following section. -->
   order_item_total=ftl:Order ${orderDetails.orderId} 
   <!-- contains an order item for product ${orderItem.productId} with a quantity of ${orderItem.quantity} and a unit price of ${orderItem.price}. This exceeds the permitted per order item total. -->
   

7. Apply this validation to the rules:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
                         xmlns:rules="http://www.milyn.org/xsd/smooks/rules-1.0.xsd"
                         xmlns:validation="http://www.milyn.org/xsd/smooks/validation-1.0.xsd"
                         xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.2.xsd">
    
       <params>
           <!-- Generate a ValidationException if we get more than 5 validation failures... -->
           <param name="validation.maxFails">5</param>
       </params>
    
       <!-- Define the ruleBases that are used by the validation rules... -->
       <rules:ruleBases>
           <!-- Field value rules using regex... -->
           <rules:ruleBase name="customer" src="rules/customer.properties" provider="org.milyn.rules.regex.RegexProvider"/>
           <rules:ruleBase name="product" src="rules/product.properties" provider="org.milyn.rules.regex.RegexProvider"/>
    
           <!-- Order business rules using MVEL expressions... -->
           <rules:ruleBase name="order" src="rules/order-rules.csv" provider="org.milyn.rules.mvel.MVELProvider"/>
       </rules:ruleBases>
    
       <!-- Capture some data into the bean context - required by the business rule validations... -->
       <jb:bean beanId="orderDetails" class="java.util.HashMap" createOnElement="header">
           <jb:value data="header/*"/>
       </jb:bean>
       <jb:bean beanId="orderItem" class="java.util.HashMap" createOnElement="order-item">
           <jb:value data="order-item/*"/>
       </jb:bean>
    
       <!-- Target validation rules... -->
       <validation:rule executeOn="header/username" name="customer.customerId" onFail="ERROR"/>
       <validation:rule executeOn="email" name="customer.email" onFail="WARN"/>
       <validation:rule executeOn="order-item/productId" name="product.productId" onFail="ERROR"/>
    
       <validation:rule executeOn="order-item" name="order.order_item_total" onFail="ERROR"/>
    
   </smooks-resource-list>
   

8. Execute from the example's Main class using this code:

   protected static ValidationResult runSmooks(final String messageIn) throws IOException, SAXException, SmooksException {
       // Instantiate Smooks with the config...
       final Smooks smooks = new Smooks("smooks-config.xml");
    
       try {
           // Create an exec context - no profiles....
           final ExecutionContext executionContext = smooks.createExecutionContext();
           final ValidationResult validationResult = new ValidationResult();
    
           // Configure the execution context to generate a report...
           executionContext.setEventListener(new HtmlReportGenerator("target/report/report.html"));
    
           // Filter the input message...
           smooks.filterSource(executionContext, new StringSource(messageIn), validationResult);
    
           return validationResult;
       }
       finally {
           smooks.close();
       }
   }
   

1. Using the Order XML message, look at the full XML-to-Java binding configuration. Here are the Java objects that you must populate from that XML message (the "getters" and "setters" are not shown):

   public class Order {
       private Header header;
       private List<OrderItem> orderItems;
   }
    
   public class Header {
       private Date date;
       private Long customerNumber;
       private String customerName;
       private double total;
   }
    
   public class OrderItem {
       private long productId;
       private Integer quantity;
       private double price;
   }
   

2. Use this configuration to bind the data from the order XML to the object model:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.4.xsd">
    
   (1)   <jb:bean beanId="order" class="com.acme.Order" createOnElement="order">
   (1.a)     <jb:wiring property="header" beanIdRef="header" />
   (1.b)     <jb:wiring property="orderItems" beanIdRef="orderItems" />
         </jb:bean>
    
   (2)   <jb:bean beanId="header" class="com.acme.Header" createOnElement="order">
   (2.a)     <jb:value property="date" decoder="Date" data="header/date">
                 <jb:decodeParam name="format">EEE MMM dd HH:mm:ss z yyyy</jb:decodeParam>
             </jb:value>
   (2.b)     <jb:value property="customerNumber" data="header/customer/@number" />
   (2.c)     <jb:value property="customerName" data="header/customer" />
   (2.d)     <jb:expression property="total" execOnElement="order-item" >
                 += (orderItem.price * orderItem.quantity);
             </jb:expression>
         </jb:bean>
    
   (3)   <jb:bean beanId="orderItems" class="java.util.ArrayList" createOnElement="order">
   (3.a)     <jb:wiring beanType="com.acme.OrderItem" /> <!-- Could also wire using beanIdRef="orderItem" -->
         </jb:bean>
    
   (4)   <jb:bean beanId="orderItem" class="com.acme.OrderItem" createOnElement="order-item">
   (4.a)     <jb:value property="productId" data="order-item/product" />
   (4.b)     <jb:value property="quantity" data="order-item/quantity" />
   (4.c)     <jb:value property="price" data="order-item/price" />
         </jb:bean>
    
   </smooks-resource-list>
   

1. Configure the Mapping Decoder as shown below to bind a different value to your object model, based on the data in your input message:

   <jb:value property="name" decoder="Mapping" data="history/@warehouse">
       <jb:decodeParam name="1">Dublin</jb:decodeParam>
       <jb:decodeParam name="2">Belfast</jb:decodeParam>
       <jb:decodeParam name="3">Cork</jb:decodeParam>
   </jb:value>
   

2. An input data value of "1" is mapped to the name property as a value of "Dublin". Likewise for values "2" and "3".

1. In the following example, the header/priority field in the input message contains values of LOW, MEDIUM and HIGH. You should map these to the LineOrderPriority enum values of NOT_IMPORTANT, IMPORTANTand VERY_IMPORTANT respectively:

   <jb:value property="priority" data="header/priority" decoder="Enum">
       <jb:decodeParam name="enumType">example.trgmodel.LineOrderPriority</jb:decodeParam>
       <jb:decodeParam name="LOW">NOT_IMPORTANT</jb:decodeParam>
       <jb:decodeParam name="MEDIUM">IMPORTANT</jb:decodeParam>
       <jb:decodeParam name="HIGH">VERY_IMPORTANT</jb:decodeParam>
   </jb:value>
   

2. If mappings are required, specify the enumeration type using the enumType decodeParam.

1. Follow this example to instantiate an ArrayList object using a static factory method:

   <jb:bean
      beanId="orders"
      class="java.util.List"
      factory="some.package.ListFactory#newList"
      createOnElement="orders"
   >
        <!-- ... bindings -->
   </jb:bean>
   

   The some.package.ListFactory#newList factory definition establishes that the newList method must be called on the some.package.ListFactory class in order to create the bean. The class attributes define the bean as a List object. The specific kind of List object that it is (be it an ArrayList or a LinkedList), is decided by the ListFactory itself.
2. Observe this additional example:

   <jb:bean
      beanId="orders"
      class="java.util.List"
      factory="some.package.ListFactory#getInstance.newList"
      createOnElement="orders"
   >
        <!-- ... bindings -->
   </jb:bean>
   

   This defines that an instance of the ListFactory needs to be retrieved using the static method getInstance and then the newList method needs to be called on the ListFactory object to create the List object. This construct lets you use singleton factories.

1. To define your own language, implement the org.milyn.javabean.factory.FactoryDefinitionParser interface. Observe the org.milyn.javabean.factory.MVELFactoryDefinitionParser or org.milyn.javabean.factory.BasicFactoryDefinitionParser for examples.
2. To define the alias for a definition language, add the org.milyn.javabean.factory.Alias annotation with the alias name to your FactoryDefinitionParser class.
3. For Smooks to find your alias you need create the file META-INF/smooks-javabean-factory-definition-parsers.inf on the root of your classpath. T

1. For each jb:bean element, set the createOnElement attribute to the event element that should be used to create the bean instance.
2. Update the jb:value data attributes to select the event element/attribute supplying the binding data for that BFean property.
3. Check the jb:value decoder attributes. Not all will be set, depending on the actual property type. These must be configured by hand. You may need to configure jb:decodeParam sub-elements for the decoder on some of the bindings, for example, on a date field.
4. Double-check the binding configuration elements (jb:value and jb:wiring), making sure all Java properties have been covered in the generated configuration.

1. Access the HTML Reporting Tool when determining selector values. It helps you visualise the input message model (against which the selectors will be applied) as seen by Smooks.
2. Generate a report using your Source data, but with an empty transformation configuration. In the report, you can see the model against which you need to add your configurations. Add the configurations one at a time, rerunning the report to check they are being applied.
3. Add the configurations one at a time, rerunning the report to check they are being applied.
4. As a result, a configuration that looks like this will be generated (note the $TODO$ tokens):

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.4.xsd">
    
       <jb:bean beanId="order" class="org.milyn.javabean.Order" createOnElement="$TODO$">
           <jb:wiring property="header" beanIdRef="header" />
           <jb:wiring property="orderItems" beanIdRef="orderItems" />
           <jb:wiring property="orderItemsArray" beanIdRef="orderItemsArray" />
       </jb:bean>
    
       <jb:bean beanId="header" class="org.milyn.javabean.Header" createOnElement="$TODO$">
           <jb:value property="date" decoder="$TODO$" data="$TODO$" />
           <jb:value property="customerNumber" decoder="Long" data="$TODO$" />
           <jb:value property="customerName" decoder="String" data="$TODO$" />
           <jb:value property="privatePerson" decoder="Boolean" data="$TODO$" />
           <jb:wiring property="order" beanIdRef="order" />
       </jb:bean>
    
       <jb:bean beanId="orderItems" class="java.util.ArrayList" createOnElement="$TODO$">
           <jb:wiring beanIdRef="orderItems_entry" />
       </jb:bean>
    
       <jb:bean beanId="orderItems_entry" class="org.milyn.javabean.OrderItem" createOnElement="$TODO$">
           <jb:value property="productId" decoder="Long" data="$TODO$" />
           <jb:value property="quantity" decoder="Integer" data="$TODO$" />
           <jb:value property="price" decoder="Double" data="$TODO$" />
           <jb:wiring property="order" beanIdRef="order" />
       </jb:bean>
    
       <jb:bean beanId="orderItemsArray" class="org.milyn.javabean.OrderItem[]" createOnElement="$TODO$">
           <jb:wiring beanIdRef="orderItemsArray_entry" />
       </jb:bean>
    
       <jb:bean beanId="orderItemsArray_entry" class="org.milyn.javabean.OrderItem" createOnElement="$TODO$">
           <jb:value property="productId" decoder="Long" data="$TODO$" />
           <jb:value property="quantity" decoder="Integer" data="$TODO$" />
           <jb:value property="price" decoder="Double" data="$TODO$" />
           <jb:wiring property="order" beanIdRef="order" />
       </jb:bean>
    
   </smooks-resource-list>
   

   Note

   There is no guarantee as to the exact contents of a JavaResult instance after calling the Smooks.filterSource method. After calling this method, the JavaResult instance will contain the final contents of the bean context, which can be added to by any Visitor implementation.

1. Access the HTML Reporting Tool when determining selector values. It helps you visualise the input message model (against which the selectors will be applied) as seen by Smooks.
2. Generate a report using your Source data, but with an empty transformation configuration. In the report, you can see the model against which you need to add your configurations. Add the configurations one at a time, rerunning the report to check they are being applied.
3. Add the configurations one at a time, rerunning the report to check they are being applied.
4. As a result, a configuration that looks like this will be generated (note the $TODO$ tokens):

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.4.xsd">
    
       <jb:bean beanId="order" class="org.milyn.javabean.Order" createOnElement="$TODO$">
           <jb:wiring property="header" beanIdRef="header" />
           <jb:wiring property="orderItems" beanIdRef="orderItems" />
           <jb:wiring property="orderItemsArray" beanIdRef="orderItemsArray" />
       </jb:bean>
    
       <jb:bean beanId="header" class="org.milyn.javabean.Header" createOnElement="$TODO$">
           <jb:value property="date" decoder="$TODO$" data="$TODO$" />
           <jb:value property="customerNumber" decoder="Long" data="$TODO$" />
           <jb:value property="customerName" decoder="String" data="$TODO$" />
           <jb:value property="privatePerson" decoder="Boolean" data="$TODO$" />
           <jb:wiring property="order" beanIdRef="order" />
       </jb:bean>
    
       <jb:bean beanId="orderItems" class="java.util.ArrayList" createOnElement="$TODO$">
           <jb:wiring beanIdRef="orderItems_entry" />
       </jb:bean>
    
       <jb:bean beanId="orderItems_entry" class="org.milyn.javabean.OrderItem" createOnElement="$TODO$">
           <jb:value property="productId" decoder="Long" data="$TODO$" />
           <jb:value property="quantity" decoder="Integer" data="$TODO$" />
           <jb:value property="price" decoder="Double" data="$TODO$" />
           <jb:wiring property="order" beanIdRef="order" />
       </jb:bean>
    
       <jb:bean beanId="orderItemsArray" class="org.milyn.javabean.OrderItem[]" createOnElement="$TODO$">
           <jb:wiring beanIdRef="orderItemsArray_entry" />
       </jb:bean>
    
       <jb:bean beanId="orderItemsArray_entry" class="org.milyn.javabean.OrderItem" createOnElement="$TODO$">
           <jb:value property="productId" decoder="Long" data="$TODO$" />
           <jb:value property="quantity" decoder="Integer" data="$TODO$" />
           <jb:value property="price" decoder="Double" data="$TODO$" />
           <jb:wiring property="order" beanIdRef="order" />
       </jb:bean>
    
   </smooks-resource-list>
   

   Note

   There is no guarantee as to the exact contents of a JavaResult instance after calling the Smooks.filterSource method. After calling this method, the JavaResult instance will contain the final contents of the bean context, which can be added to by any Visitor implementation.

• To use XSL templates in Smooks, configure the http://www.milyn.org/xsd/smooks/xsl-1.1.xsd XSD in an integrated development environment.

  Important

  In JBoss SOA, the fragment filter is bypassed when the Smooks configuration only contains a single XSLT that is applied to the root fragment. The XSLT is applied directly. This is done for performance reasons and can be disabled by adding a parameter called enableFilterBypass and setting it to false:

  <param name="enableFilterBypass">false</param>
  

1. To process and persist an XML "order" message, you should bind the order data into the Order entities (Order, OrderLine and Product). To do this, create and populate the Order and OrderLine entities using the Java Binding framework.
2. Wire each OrderLine instance into the Order instance.
3. In each OrderLine instance, you should lookup and wire in the associated order line Product entity.
4. Finally, insert (persist) the Order instance as seen below:

   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" 
                         xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.4.xsd" 
                         xmlns:dao="http://www.milyn.org/xsd/smooks/persistence-1.2.xsd">
    
       <jb:bean beanId="order" class="example.entity.Order" createOnElement="order">
           <jb:value property="ordernumber" data="ordernumber" />
           <jb:value property="customerId" data="customer" />
           <jb:wiring setterMethod="addOrderLine" beanIdRef="orderLine" />
       </jb:bean>
    
       <jb:bean beanId="orderLine" class="example.entity.OrderLine" createOnElement="order-item">
           <jb:value property="quantity" data="quantity" />
           <jb:wiring property="order" beanIdRef="order" />
           <jb:wiring property="product" beanIdRef="product" />
       </jb:bean>
    
       <dao:locator beanId="product" lookupOnElement="order-item" onNoResult="EXCEPTION" uniqueResult="true">
           <dao:query>from Product p where p.id = :id</dao:query>
           <dao:params>
               <dao:value name="id" data="product" decoder="Integer" />
           </dao:params>
       </dao:locator>
    
       <dao:inserter beanId="order" insertOnElement="order" />
    
   </smooks-resource-list>
   

5. If you want to use the named query productById instead of the query string, the DAO locator configuration will look like this:

   <dao:locator beanId="product" lookupOnElement="order-item" lookup="product.byId" onNoResult="EXCEPTION" uniqueResult="true">
       <dao:params>
           <dao:value name="id" data="product" decoder="Integer"/>
       </dao:params>
   </dao:locator>
   

1. To persist an order with DAO, observe the example code below. This example will read an XML file containing order information (this works the same for EDI, CSV, and so on). Using the Javabean cartridge, it will bind the XML data into a set of entity beans. It will locate the product entities and bind them to the order entity bean using the ID of the products within the order items (the product element). Finally, the order bean will be persisted.
   The order XML message looks like this:

   <order>
       <ordernumber>1</ordernumber>
       <customer>123456</customer>
       <order-items>
           <order-item>
               <product>11</product>
               <quantity>2</quantity>
           </order-item>
           <order-item>
               <product>22</product>
               <quantity>7</quantity>
           </order-item>
       </order-items>
   </order>
   

2. Use a custom DAO such as the example below to persist the Order entity:

   @Dao
   public class OrderDao {
    
       private final EntityManager em;
    
       public OrderDao(EntityManager em) {
           this.em = em;
       }
    
       @Insert
       public void insertOrder(Order order) {
           em.persist(order);
       }
   }
   

   When looking at this class you should notice the @Dao and @Insert annotations. The @Dao annotation declares that the OrderDao is a DAO object. The @Insert annotation declares that the insertOrder method should be used to insert Order entities.
3. Use a custom DAO as shown in the following example to lookup the Product entities:

   @Dao
   public class ProductDao {
    
       private final EntityManager em;
    
       public ProductDao(EntityManager em) {
           this.em = em;
       }
    
       @Lookup(name = "id")
       public Product findProductById(@Param("id")int id) {
           return em.find(Product.class, id);
       }
   }
   

   When looking at this class, you should notice the @Lookup and @Param annotation. The @Lookup annotation declares that the ProductDao#findByProductId method is used to lookup Product entities. The name parameter in the @Lookup annotation sets the lookup name reference for that method. When the name isn’t declared, the method name will be used. The optional @Param annotation lets you name the parameters. This creates a better abstraction between Smooks and the DAO. If you don’t declare the @Param annotation the parameters are resolved by there position.
4. When you have configured your order as shown above, the resulting Smooks configuration will look like this:

   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
                         xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.4.xsd"
                         xmlns:dao="http://www.milyn.org/xsd/smooks/persistence-1.2.xsd">
    
       <jb:bean BeanId="order" class="example.entity.Order" createOnElement="order">
           <jb:value property="ordernumber" data="ordernumber"/>
           <jb:value property="customerId" data="customer"/>
           <jb:wiring setterMethod="addOrderLine" BeanIdRef="orderLine"/>
       </jb:bean>
    
       <jb:bean BeanId="orderLine" class="example.entity.OrderLine" createOnElement="order-item">
           <jb:value property="quantity" data="quantity"/>
           <jb:wiring property="order" BeanIdRef="order"/>
           <jb:wiring property="product" BeanIdRef="product"/>
       </jb:bean>
    
       <dao:locator BeanId="product" dao="product" lookup="id" lookupOnElement="order-item" onNoResult="EXCEPTION">
           <dao:params>
               <dao:value name="id" data="product" decoder="Integer"/>
           </dao:params>
       </dao:locator>
    
       <dao:inserter BeanId="order" dao="order" insertOnElement="order"/>
    
   </smooks-resource-list>
   

5. Use the following code to execute Smooks:

   Smooks smooks=new Smooks("./smooks-configs/smooks-dao-config.xml");
   ExecutionContext executionContext=smooks.createExecutionContext();
    
   // The register is used to map the DAO's to a DAO name. The DAO name isbe used in
   // the configuration.
   // The MapRegister is a simple Map like implementation of the DaoRegister.
   DaoRegister<object>register = MapRegister.builder()
           .put("product",new ProductDao(em))
           .put("order",new OrderDao(em))
           .build();
    
   PersistenceUtil.setDAORegister(executionContext,mapRegister);
    
   // Transaction management from within Smooks isn't supported yet,
   // so we need to do it outside the filter execution
   EntityTransaction tx=em.getTransaction();
   tx.begin();
    
   smooks.filter(new StreamSource(messageIn),null,executionContext);
    
   tx.commit();
   

Procedure 9.1. Task

1. Take an XML message such as the following sample:

   <shopping>
       <category type="groceries">
           <item>Chocolate</item>
           <item>Coffee</item>
       </category>
       <category type="supplies">
           <item>Paper</item>
           <item quantity="4">Pens</item>
       </category>
           <category type="present">
           <item when="Aug 10">Kathryn's Birthday</item>
       </category>
   </shopping>
   

2. You can modify the "supplies" category in the above shopping list by adding two more "pens". To do this, write a simple Groovy script and aim it at the message's <category> elements.
3. As a result, the script simply iterates over the <item> elements in the category, and in instances where the category type is "supplies" and the item is "pens", the quantity is incremented by two:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" 
      xmlns:core="http://www.milyn.org/xsd/smooks/smooks-core-1.3.xsd"
      xmlns:g="http://www.milyn.org/xsd/smooks/groovy-1.1.xsd">
   
      <core:filterSettings type="SAX" />
       
      <g:groovy executeOnElement="category">
         <g:script>
         <!--
            use(DOMCategory) {
             // Modify "supplies": we need an extra 2 pens...
             if (category.'@type' == 'supplies') {
                 category.item.each { item ->
                     if (item.text() == 'Pens') {
                         item['@quantity'] = item.'@quantity'.toInteger() + 2;
                     }
                 }
             }
         }
           
         // When using the SAX filter, we need to explicitly write the fragment
         // to the result stream...
         writeFragment(category);
         -->
         </g:script>
      </g:groovy>
   
   </smooks-resource-list>
   

1. To route message fragments to Apache Camel endpoints, use the camel:route configuration from the http://www.milyn.org/xsd/smooks/camel-1.4.xsd configuration namespace.
2. Route to a Camel endpoint by specifying the following in your Smooks configuration:

   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
            xmlns:camel="http://www.milyn.org/xsd/smooks/camel-1.4.xsd">
    
     <!-- Create some bean instances from the input source... -->
     <jb:bean beanId="orderItem"  ... ">
       <!-- etc... See Smooks Java Binding docs -->
     </jb:bean>
    
     <!-- Route bean to camel endpoints... -->
     <camel:route beanId="orderItem">
       <camel:to endpoint="direct:slow" if="orderItem.priority == 'Normal'" />
       <camel:to endpoint="direct:express" if="orderItem.priority == 'High'" />
     </camel:route>
    
   </smooks-resource-list>
   
   

   In the above example, Javabeans is routed from the Smooks BeanContext to the Camel Endpoints. You can also apply templates (such as FreeMarker) to these same beans and route the templating result instead of the beans (such as as XML and CSV).
   routeOnElement.

• To undertake unit testing with Smooks, follow the example below:

  public class MyMessageTransformTest
  {
      @Test
      public void test_transform() throws IOException, SAXException
      {
          Smooks smooks = new Smooks(
              getClass().getResourceAsStream("smooks-config.xml") );
  
          try {
              Source source = new StreamSource(
                  getClass().getResourceAsStream("input-message.xml" ) );
              StringResult result = new StringResult();
  
              smooks.filterSource(source, result);
  
              // compare the expected xml with the transformation result.
              XMLUnit.setIgnoreWhitespace( true );
              XMLAssert.assertXMLEqual(
                  new InputStreamReader(
                  getClass().getResourceAsStream("expected.xml")), 
                  new StringReader(result.getResult()));
          } finally {
              smooks.close();
          }
      }
  }
  

  The test case above uses a piece of software called XMLUnit (see http://xmlunit.sourceforge.net for more information.)

  Note

  The following Maven dependency was needed for the above test:

  <dependency>
      <groupId>xmlunit</groupId>
      <artifactId>xmlunit</artifactId>
      <version>1.1</version>
  </dependency>
  

1. To configure Smooks to capture multiple NodeModels for use by the FreeMarker templates, you should configure the DomModelCreator visitor. It should be targeted at the root node of each model. Note again that Smooks also makes this available to SAX filtering (the key to processing huge messages).
   This is The Smooks configuration for creating the NodeModels for the message:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" 
                         xmlns:core="http://www.milyn.org/xsd/smooks/smooks-core-1.3.xsd"
                         xmlns:ftl="http://www.milyn.org/xsd/smooks/freemarker-1.1.xsd">
    
       <!--
       Filter the message using the SAX Filter (i.e. not DOM, so no
       intermediate DOM for the "complete" message - there are "mini" DOMs
       for the NodeModels below)....
       -->
       <core:filterSettings type="SAX" defaultSerialization="false" />
    
       <!--
       Create 2 NodeModels. One high level model for the "order"
       (header etc) and then one for the "order-item" elements...
       -->
       <resource-config selector="order,order-item">
           <resource>org.milyn.delivery.DomModelCreator</resource>
       </resource-config>
    
       <!-- FreeMarker templating configs to be added below... -->
   

2. Next, apply the following FreeMarker templates:
   • A template to output the order header details, up to but not including the order items.
   • A template for each of the order items, to generate the item elements in the salesorder.
   • A template to close out the message.
   With Smooks, you can implement this by defining two FreeMarker templates. One to cover points one and three (combined) above, and a second to cover the item elements.
3. Applt the first FreeMarker template. It is targeted at the order-items element and looks like this:

   <ftl:freemarker applyOnElement="order-items">
           <ftl:template><!--<salesorder>
       <details>
           <orderid>${order.@id}</orderid>
           <customer>
               <id>${order.header.customer.@number}</id>
               <name>${order.header.customer}</name>
           </customer>
       </details>
       <itemList>
       <?TEMPLATE-SPLIT-PI?> 
       </itemList>
   </salesorder>-->
           </ftl:template>
       </ftl:freemarker>
   

   The ?TEMPLATE-SPLIT-PI? processing instruction tells Smooks where to split the template, outputting the first part of the template at the start of the order-items element, and the other part at the end of the order-items element. The item element template (the second template) will be output in between.
4. Apply the second FreeMarker template. This outputs the item elements at the end of every order-item element in the source message:

   <ftl:freemarker applyOnElement="order-item">
           <ftl:template><!-- <item>
       <id>${.vars["order-item"].@id}</id>
       <productId>${.vars["order-item"].product}</productId>
       <quantity>${.vars["order-item"].quantity}</quantity>
       <price>${.vars["order-item"].price}</price>
   </item>-->
           </ftl:template>
       </ftl:freemarker>
   </smooks-resource-list>
   

   Because the second template fires on the end of the order-item elements, it effectively generates output into the location of the ?TEMPLATE-SPLIT-PI? processing instruction in the first template. Note that the second template could have also referenced data in the order NodeModel.
5. Apply a closing template of your choice.

   Note

   This approach to performing a one-to-one transformation of a huge message works because the only objects in memory at any one time are the order header details and the current order-item details (in the Virtual Object Model). Obviously it can' work if the transformation is so obscure as to always require full access to all the data in the source message, for example if the messages needs to have all the order items reversed in order (or sorted). In such a case however, you do have the option of routing the order details and items to a database and then using the database's storage, query and paging features to perform the transformation.

1. To split and route fragments of a message, use the basic frag:serialize and *:router components (jms:router, file:router and so on) from the Routing Cartridge. The frag:serialize component has its own configuration in the http://www.milyn.org/xsd/smooks/fragment-routing-1.2.xsd namespace.
2. Use the example below for serializing the contents of a SOAP message body and storing it in the bean context under the beanId of soapBody:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:frag="http://www.milyn.org/xsd/smooks/fragment-routing-1.2.xsd">
    
       <frag:serialize fragment="Envelope/Body" bindTo="soapBody" childContentOnly="true"/>
    
   </smooks-resource-list>
   

3. Use this code to execute it:

   Smooks smooks = new Smooks(configStream);
   JavaResult javaResult = new JavaResult();
    
   smooks.filterSource(new StreamSource(soapMessageStream), javaResult);
    
   String bodyContent = javaResult.getBean("soapBody").toString().trim();
   

4. To do this programatically, use this code:

   Smooks smooks = new Smooks();
    
   smooks.addVisitor(new FragmentSerializer().setBindTo("soapBody"), "Envelope/Body");
    
   JavaResult javaResult = new JavaResult();
   smooks.filterSource(new StreamSource(soapMessageStream), javaResult);
    
   String bodyContent = javaResult.getBean("soapBody").toString().trim();
   

1. To route an order and order item data to a database, you should define a set of Java bindings that extract the order and order-item data from the data stream:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" 
                         xmlns:jb="http://www.milyn.org/xsd/smooks/javabean-1.4.xsd">
    
       <!-- Extract the order data... -->
       <jb:bean beanId="order" class="java.util.Hashtable" createOnElement="order">
           <jb:value property="orderId" decoder="Integer" data="order/@id"/>
           <jb:value property="customerNumber" decoder="Long" data="header/customer/@number"/>
           <jb:value property="customerName" data="header/customer"/>
       </jb:bean>
    
       <!-- Extract the order-item data... -->
       <jb:bean beanId="orderItem" class="java.util.Hashtable" createOnElement="order-item">
           <jb:value property="itemId" decoder="Integer" data="order-item/@id"/>
           <jb:value property="productId" decoder="Long" data="order-item/product"/>
           <jb:value property="quantity" decoder="Integer" data="order-item/quantity"/>
           <jb:value property="price" decoder="Double" data="order-item/price"/>
       </jb:bean>
   

2. Next you need to define datasource configuration and a number of db:executor configurations that will use that datasource to insert the data that was bound into the Java Object model into the database. This is the datasource configuration (namespace http://www.milyn.org/xsd/smooks/datasource-1.3.xsd) for retrieving a direct database connection:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:ds="http://www.milyn.org/xsd/smooks/datasource-1.3.xsd">
    
       <ds:direct bindOnElement="#document"
               datasource="DBExtractTransformLoadDS"
               driver="org.hsqldb.jdbcDriver"
               url="jdbc:hsqldb:hsql://localhost:9201/milyn-hsql-9201"
               username="sa"
               password=""
               autoCommit="false" />
    
   </smooks-resource-list>
   

3. It is possible to use a JNDI datasource for retrieving a database connection:

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd" xmlns:ds="http://www.milyn.org/xsd/smooks/datasource-1.3.xsd">
    
       <!-- This JNDI datasource can handle JDBC and JTA transactions or 
              it can leave the transaction managment to an other external component.
              An external component could be an other Smooks visitor, the EJB transaction manager
              or you can do it your self. -->
       <ds:JNDI
           bindOnElement="#document"
           datasource="DBExtractTransformLoadDS"
           datasourceJndi="java:/someDS"
           transactionManager="JTA"
           transactionJndi="java:/mockTransaction"
           targetProfile="jta"/>
    
   </smooks-resource-list>
   

4. The datasource schema describes and documents how you can configure the datasource. This is the db:executor configuration (namespace http://www.milyn.org/xsd/smooks/db-routing-1.1.xsd):

   <?xml version="1.0"?>
   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd"
                         xmlns:db="http://www.milyn.org/xsd/smooks/db-routing-1.1.xsd">
    
       <!-- Assert whether it's an insert or update. Need to do this just before we do the insert/update... -->
       <db:executor executeOnElement="order-items" datasource="DBExtractTransformLoadDS" executeBefore="true">
           <db:statement>select OrderId from ORDERS where OrderId = ${order.orderId}</db:statement>
           <db:resultSet name="orderExistsRS"/>
       </db:executor>
    
       <!-- If it's an insert (orderExistsRS.isEmpty()), insert the order before we process the order items... -->
       <db:executor executeOnElement="order-items" datasource="DBExtractTransformLoadDS" executeBefore="true">
           <condition>orderExistsRS.isEmpty()</condition>
           <db:statement>INSERT INTO ORDERS VALUES(${order.orderId}, ${order.customerNumber}, ${order.customerName})</db:statement>
       </db:executor>
    
       <!-- And insert each orderItem... -->
       <db:executor executeOnElement="order-item" datasource="DBExtractTransformLoadDS" executeBefore="false">
           <condition>orderExistsRS.isEmpty()</condition>
           <db:statement>INSERT INTO ORDERITEMS VALUES (${orderItem.itemId}, ${order.orderId}, ${orderItem.productId}, ${orderItem.quantity}, ${orderItem.price})</db:statement>
       </db:executor>
    
       <!-- Ignoring updates for now!! -->
    
   </smooks-resource-list>
   

1. You should first implement a basic reader class as shown below:

    public class MyCSVReader implements SmooksXMLReader 
   {
      // Implement all of the XMLReader methods...
   }
   

   Two methods from the org.xml.sax.XMLReader interface are of particular interest:
   1. setContentHandler(ContentHandler) is called by Smooks Core. It sets the org.xml.sax.ContentHandler instance for the reader. The org.xml.sax.ContentHandler instance methods are called from inside the parse(InputSource) method.
   2. parse(InputSource) : This is the method that receives the Source data input stream, parses it (i.e. in the case of this example, the CSV stream) and generates the SAX event stream through calls to the org.xml.sax.ContentHandler instance supplied in the setContentHandler(ContentHandler) method.
   Refer to http://download.oracle.com/javase/6/docs/api/org/xml/sax/ContentHandler.html for more details.
2. Configure your CSV reader with the names of the fields associated with the CSV records. Configuring a custom reader implementation is the same for any Smooks component. See the example below:

   public class MyCSVReader implements SmooksXMLReader 
   {
   
       private ContentHandler contentHandler;
   
       @ConfigParam
       private String[] fields; // Auto decoded and injected from the "fields" <param> on the reader config.
   
       public void setContentHandler(ContentHandler contentHandler) {
           this.contentHandler = contentHandler;
       }
   
       public void parse(InputSource csvInputSource) throws IOException, SAXException {
           // TODO: Implement parsing of CSV Stream...
       }
   
       // Other XMLReader methods...
   }
   

3. Now that you have the basic Reader implementation stub, you can start writing unit tests to test the new reader implementation. To do this you will need something with CSV input. Observe the example below featuring a simple list of names in a file with the name names.csv:

   Tom,Jones
   Mike,Jones
   Mark,Jones

4. Use a test Smooks configuration to configure Smooks with your MyCSVReader. As stated before, everything in Smooks is a resource and can be configured with the basic <resource-config> configuration. While this works fine, it's a little noisy, so Smooks provides a basic <reader> configuration element specifically for the purpose of configuring a reader. The configuration for the test looks like the following, in the mycsvread-config.xml:

   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd">
      <reader class="com.acme.MyCSVReader">
         <params>
            <param name="fields">firstname,lastname</param>
         </params>
      </reader>
   </smooks-resource-list>
   

5. Implement the JUnit test class:

   public class MyCSVReaderTest extends TestCase 
   {
       
       public void test() {
           Smooks smooks = new Smooks(getClass().getResourceAsStream("mycsvread-config.xml"));
           StringResult serializedCSVEvents = new StringResult();
   
           smooks.filterSource(new StreamSource(getClass().getResourceAsStream("names.csv")), serializedCSVEvents);
   
           System.out.println(serializedCSVEvents);
   
           // TODO: add assertions etc
       }
   }
   

6. Implement the parse method:

   public class MyCSVReader implements SmooksXMLReader 
   {
       private ContentHandler contentHandler;
   
       @ConfigParam
       private String[] fields; // Auto decoded and injected from the "fields" <param> on the reader config.
   
       public void setContentHandler(ContentHandler contentHandler) 
       {
           this.contentHandler = contentHandler;
       }
   
       public void parse(InputSource csvInputSource) throws IOException, SAXException 
       {
           BufferedReader csvRecordReader = new BufferedReader(csvInputSource.getCharacterStream());
           String csvRecord;
   
           // Send the start of message events to the handler...
           contentHandler.startDocument();
           contentHandler.startElement(XMLConstants.NULL_NS_URI, "message-root", "", new AttributesImpl());
   
           csvRecord = csvRecordReader.readLine();
           while(csvRecord != null) 
           {
               String[] fieldValues = csvRecord.split(",");
           
               // perform checks...
   
               // Send the events for this record...
               contentHandler.startElement(XMLConstants.NULL_NS_URI, "record", "", new AttributesImpl());
               for(int i = 0; i < fields.length; i++) 
               {
                   contentHandler.startElement(XMLConstants.NULL_NS_URI, fields[i], "", new AttributesImpl());
                   contentHandler.characters(fieldValues[i].toCharArray(), 0, fieldValues[i].length());
                   contentHandler.endElement(XMLConstants.NULL_NS_URI, fields[i], "");            
               }
               contentHandler.endElement(XMLConstants.NULL_NS_URI, "record", "");            
   
               csvRecord = csvRecordReader.readLine();    
           }
   
           // Send the end of message events to the handler...
           contentHandler.endElement(XMLConstants.NULL_NS_URI, "message-root", "");
           contentHandler.endDocument();
       }
   
       // Other XMLReader methods...
   }
   

7. Run the unit test class to see the following output on the console (formatted):

   <message-root>
       <record>
           <firstname>Tom</firstname>
           <lastname>Jones</lastname>
       </record>
       <record>
           <firstname>Mike</firstname>
           <lastname>Jones</lastname>
       </record>
       <record>
           <firstname>Mark</firstname>
           <lastname>Jones</lastname>
       </record>
   </message-root>
   

   After this, it is a case of expanding the tests, hardening the reader implementation code, and so on. Then you can use your reader to perform all sorts of operations supported by Smooks.

1. To implement a binary source reader, observe the following parse method implementation:

   public static class BinaryFormatXXReader implements SmooksXMLReader, StreamReader 
   {
       @ConfigParam
       private String xProtocolVersion;
   
       @ConfigParam
       private int someOtherXProtocolConfig;
   
       // etc...
   
       public void parse(InputSource inputSource) throws IOException, SAXException {
           // Use the InputStream (binary) on the InputSource...
           InputStream binStream = inputSource.getByteStream();
   
           // Create and configure the data decoder... 
           BinaryFormatXDecoder xDecoder = new BinaryFormatXDecoder();
           xDecoder.setProtocolVersion(xProtocolVersion);
           xDecoder.setSomeOtherXProtocolConfig(someOtherXProtocolConfig);
           xDecoder.setXSource(binStream);
   
           // Generate the XML Events on the contentHandler...
           contentHandler.startDocument();
   
           // Use xDecoder to fire startElement, endElement etc events on the contentHandler (see previous section)...
   
           contentHandler.endDocument();
       }
   
       // etc....
   }
   

2. Configure the BinaryFormatXXReader reader in your Smooks configuration as you would any other reader:

   <smooks-resource-list xmlns="http://www.milyn.org/xsd/smooks-1.1.xsd">
   
       <reader class="com.acme.BinaryFormatXXReader">
           <params>
            <param name="xProtocolVersion">2.5.7</param>
            <param name="someOtherXProtocolConfig">1</param>
               ... etc... 
           </params>
       </reader>
   
       ... Other Smooks configurations e.g. <jb:bean> configs for binding the binary data into Java objects... 
   
   </smooks-resource-list>
   

3. Run the Smooks execution code (note the InputStream supplied to the StreamSource). In this case, two results are generated: XML and Java objects.

   StreamResult xmlResult = new StreamResult(xmlOutWriter);
   JavaResult javaResult = new JavaResult();
   
   InputStream xBinaryInputStream = getXByteStream();
   
   smooks.filterSource(new StreamSource(xBinaryInputStream), xmlResult, javaResult);
   
   // etc... Use the beans in the javaResult...
   

1. To turn the default serialization behavior on or off, access the filter settings and configure them to do so.
2. To modify the serialized form of one of the message fragments, implement a SAXVisitor to perform the transformation and target it at the message fragment using an XPath-like expression.
3. To modify the serialized form of a message fragment, use one of the provided templating components. These components are also SAXVisitor implementations.

1. To implement a SAXVisitor geared towards transforming the serialized form of a fragment, program Smooks so the SAXVisitor implementation will be writing to the StreamResult. This is because Smooks supports targeting of multiple SAXVisitor implementations at a single fragment, but only one SAXVisitor is allowed to write to the StreamResult, per fragment.
2. If a second SAXVisitor attempts to write to the StreamResult, a SAXWriterAccessException will result and you will need to modify your Smooks configuration.
3. To specify the StreamResult to write, the SAXVisitor needs to "acquire ownership" of the Writer to the StreamResult. It does this by making a call to the SAXElement.getWriter(SAXVisitor) method from inside the SAXVisitBefore.visitBefore methods implementation, passing this as the SAXVisitor parameter.

1. When writing a SAXVisitor implementation with the SAXToXMLWriter, set the SAXToXMLWriter constructor to a boolean. This is the encodeSpecialChars arg and it should be set based on the rewriteEntities filter setting.
2. Move the @StreamResultWriter annotation from the class and onto the SAXToXMLWriter instance declaration. This results in Smooks creating the SAXToXMLWriter instance which is then initialized with the rewriteEntities filter setting for the associated Smooks instance:

   @TextConsumer
   public class MyVisitor implements SAXVisitAfter 
   {
      @StreamResultWriter
      private SAXToXMLWriter xmlWriter;
   
      public void visitAfter(SAXElement element, ExecutionContext executionContext) 
                                                throws SmooksException, IOException 
      {
         xmlWriter.writeStartElement(element);
         xmlWriter.writeText(element);
         xmlWriter.writeEndElement(element);
      }
   }
   

1. Add a route to your Camel route configuration as shown below:

   from("file://inputDir?noop=true")
   .to("smooks://smooks-config.xml")
   .to("jms:queue:order")
   

2. Edit the values in the 'smooks-config-xml' file. You cannot tell what type of output the SmooksComponent is producing just by looking at the route configuration. Instead, this is expressed in the Smooks configuration via the exports element.

   Note

   If you would prefer to configure Smooks programmatically, you can set this using the SmooksProcessor

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>
   

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.