Smooks Development Guide

Procedure 1.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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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();
   }
   

   Copy to Clipboard Toggle word wrap
8. An XML-to-XML transformation occurs as a result.

Procedure 1.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>
  

  Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
2. Configure the in-memory model for the order as shown:

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

   Copy to Clipboard Toggle word wrap
   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.

   Example 1.1. 

   // 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");
   

   Copy to Clipboard Toggle word wrap
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.

   Example 1.2. 

   // Create a bean to pass on to the Smooks execution context
   HashMap<String,Object> transformConfig = new HashMap<String,Object>();
   transformConfig.put("Version", new Integer(1));    
   
   // 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();
   
   // Add bean to Smooks execution context
   executionContext.getBeanContext().addBean("transformConfig", transformConfig);
   
   // 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");
   

   Copy to Clipboard Toggle word wrap
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
  

  Copy to Clipboard Toggle word wrap
  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));
   

   Copy to Clipboard Toggle word wrap
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:

   <?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">
   
       <!-- Visitors... -->
       <core:terminate onElement="customer" />
   
   </smooks-resource-list>

   Copy to Clipboard Toggle word wrap
2. To terminate at the beginning of a message (on the visitBefore event), use this code:

   <?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">
   
      <!-- Visitors... -->
   
      <core:terminate onElement="customer" terminateBefore="true" />
   
   </smooks-resource-list>

   Copy to Clipboard Toggle word wrap

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

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

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap

• 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>
  

  Copy to Clipboard Toggle word wrap

• 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>
  

  Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap

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>
   
   

   Copy to Clipboard Toggle word wrap
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>
   
   

   Copy to Clipboard Toggle word wrap

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
   

   Copy to Clipboard Toggle word wrap
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;
   }
   
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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");
   

   Copy to Clipboard Toggle word wrap
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>
   
   

   Copy to Clipboard Toggle word wrap
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");
   
   

   Copy to Clipboard Toggle word wrap
   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");
   
   

   Copy to Clipboard Toggle word wrap
   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);
   
   

   Copy to Clipboard Toggle word wrap
   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>
   
   

   Copy to Clipboard Toggle word wrap
   Here is an example input file:

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

   Copy to Clipboard Toggle word wrap
   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>
   
   

   Copy to Clipboard Toggle word wrap
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>
   
   

   Copy to Clipboard Toggle word wrap
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>
   
   

   Copy to Clipboard Toggle word wrap

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
   

   Copy to Clipboard Toggle word wrap
   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;
   }

   Copy to Clipboard Toggle word wrap
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>

   Copy to Clipboard Toggle word wrap
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");

   Copy to Clipboard Toggle word wrap
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>
           
   </smooks-resource-list>

   Copy to Clipboard Toggle word wrap
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");

   Copy to Clipboard Toggle word wrap
   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");
   

   Copy to Clipboard Toggle word wrap
   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);
   

   Copy to Clipboard Toggle word wrap
   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>
   

   Copy to Clipboard Toggle word wrap

• 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(....);
  

  Copy to Clipboard Toggle word wrap

• 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>
  

  Copy to Clipboard Toggle word wrap

• 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>
  

  Copy to Clipboard Toggle word wrap

• 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>
  

  Copy to Clipboard Toggle word wrap
  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"));
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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" />
   

   Copy to Clipboard Toggle word wrap
   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);
   
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
   • 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.
     Note
     Note that there is no e between Whit and space in the keyWhitspaceReplacement field name.
   • 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...
   

   Copy to Clipboard Toggle word wrap

Procedure 2.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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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...
   

   Copy to Clipboard Toggle word wrap

• 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>
  

  Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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");
   }
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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]
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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>
  

  Copy to Clipboard Toggle word wrap
  • 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}$
   

   Copy to Clipboard Toggle word wrap
4. Insert the product-related Regex rule in the product.properties file:

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

   Copy to Clipboard Toggle word wrap
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 LibreOffice 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}'.

   Copy to Clipboard Toggle word wrap
   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}'.

   Copy to Clipboard Toggle word wrap
   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
   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.

   Copy to Clipboard Toggle word wrap
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>

   Copy to Clipboard Toggle word wrap
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();
       }
   }

   Copy to Clipboard Toggle word wrap

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;
   }
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap
   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>
   

   Copy to Clipboard Toggle word wrap
   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>
   

   Copy to Clipboard Toggle word wrap
   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>
   

   Copy to Clipboard Toggle word wrap
   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 Red Hat JBoss Fuse, 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>
  

  Copy to Clipboard Toggle word wrap

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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap

1. The sample code below demonstrates how to persist an order with DAO. 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>
   

   Copy to Clipboard Toggle word wrap
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);
       }
   }
   

   Copy to Clipboard Toggle word wrap
   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);
       }
   }
   

   Copy to Clipboard Toggle word wrap
   When looking at this class, notice the @Lookup and @Param annotation. The @Lookup annotation declares that the ProductDao.findProductById() 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 their 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>
   

   Copy to Clipboard Toggle word wrap
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 is 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();
   

   Copy to Clipboard Toggle word wrap

Procedure 7.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>
   

   Copy to Clipboard Toggle word wrap
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>
   

   Copy to Clipboard Toggle word wrap