Chapter 3. Basics

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>