In a previous post, I mentioned that you could extend the function library in Altova MapForce and add your own functions. In this post I’ll show you (briefly) how to do this using the Java methods from the previous post.

The MapForce documentation only contains a little information on how to add your own custom functions.

The base directory in which you installed MapForce contains a directory called MapForceLibraries. Here, you will find a number of, so called, mff files, which stands for MapForce Functions. Inside, the definition is stored of the functions you are able to select from the library when working on a mapping. We will be using this principle to add an extension of our own. The only thing we need to do, is create such a mff file.

As I already said, the MapForce documentation does not contain a lot of information on this subject. But … what it does include is the XML Schema for the mff file. It is called mff.xsd and it is also located in the MapForceLibraries directory. Open the XML Schema in XMLSpy (or any other XML editor) and select element mapping to get an overview of the library structure. Notice that the XML Schema is well-documented (at least better than the actual MapForce documentation).

We will, briefly, walk through the most important elements. First, element mapping: the root element.

First, element implementations. This element refers to the possible implementations of your extension (e.g. Java, XSLT, C#, etc).

Functions can be grouped, hence the group element. The component element inside describes how your extension should be called. The target describe your input parameters (if any) and output describes your output.

Here’s what an example XML could look like. We used an xslt2 implementation that points to a xslt stylesheet.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<?xml version="1.0" encoding="UTF-8"?>
<mapping xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="file:///C:/Program%20Files/Altova/MapForce2011/MapForceLibraries/mff.xsd" version="8" library="redstream" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:mf="http://www.altova.com/MapForce/2010/standard">
	<implementations>
		<implementation language="xslt2">
			<setting name="xsltfilename" value="xlst-redstream-library.xsl"/>
		</implementation>
	</implementations>
	<group name="demo functions">
		<component name="greeting">
			<sources>
				<datapoint name="name" type="xs:string"/>
			</sources>
			<targets>
				<datapoint name="result" type="xs:string"/>
			</targets>
			<implementations>
				<implementation language="xslt2">
					<function name="rs:greeting" namespace="java:nl.redstream.XsltUtils"/>
				</implementation>
			</implementations>
			<description>
				<short>result = 'Hello ' + name + ' !'</short>
				<long>Returns friendly message.</long>
			</description>
		</component>
	</group>
</mapping>

The related XSLT file looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0" 
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
   xmlns:xs="http://www.w3.org/2001/XMLSchema" 
   xmlns:fn="http://www.w3.org/2005/xpath-functions" 
   xmlns:rs="java:nl.redstream.utils.XsltUtils">
 
   <xsl:function as="xs:string" name="rs:greeting">
      <xsl:param as="xs:string" name="name"/>
      <xsl:value-of select="rs:greeting($name)"/>
   </xsl:function>
 
</xsl:stylesheet>

Once, you’ve created your mff and xslt file, copy them into MapForceLibraries directory (make sure MapForce is not running, otherwise you will not be able to write in that directory). Start Altova MapForce, create a new mapping (implemenation xslt2 and behold … your extension will show up in the Library.

Now, you can drag-and-drop the function onto your mapping.

The resulting XSLT will look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<?xml version="1.0" encoding="UTF-8"?>
<!--
This file was generated by Altova MapForce 2011sp1
 
YOU SHOULD NOT MODIFY THIS FILE, BECAUSE IT WILL BE
OVERWRITTEN WHEN YOU RE-RUN CODE GENERATION.
 
Refer to the Altova MapForce Documentation for further details.
http://www.altova.com/mapforce
-->
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
                                              xmlns:xs="http://www.w3.org/2001/XMLSchema" 
                                              xmlns:fn="http://www.w3.org/2005/xpath-functions" 
                                              xmlns:rs="java:nl.redstream.XsltUtils" exclude-result-prefixes="xs fn rs">
   <xsl:output method="xml" encoding="UTF-8" indent="yes"/>
   <xsl:template match="/">
      <dataset>
         <row>
            <column>
               <xsl:for-each select="dataset/row/column">
                  <xsl:attribute name="name" select="rs:greeting(fn:string(@name))"/>
               </xsl:for-each>
            </column>
         </row>
      </dataset>
   </xsl:template>
</xsl:stylesheet>

Unfortunately, you cannot display the results of the customized mapping in MapForce (#featurerequest). Instead, you could use XMLSpy and use the settings from the previous post.

That’s it … enjoy!

Recently I got into a situation where I had to put ‘metadata’ values (which were part of the Mule Message) into the XML result of an XSLT transformer. Let me explain the situation with an example. Imagine you have an ‘order’ xml that needs to be translated into an ‘invoice’ xml. Here is a simple ‘order.xsd’:

Here is the ‘invoice.xsd’:

The mapping for the transformation looks like this in MapForce:

Now the invoice number that is used in the invoice should be the MuleMessage correlationID…. (I know, weird situation, but it is only an example). The first thing that came to mind was to create a new transformer that would run after the XSLT transformer. This new transformer would add the element ‘invoicenr’ with the correlationID as value to the payload of the MuleMessage. But it can be done much easier! Here is the modified mapping that I created with MapForce:

In MapForce you can add extra input parameters for the XSL mapping as shown above. Now generate the XSLT and use that as basis for your Mule XSLT Transformer. In the Mule config you add the context-property to your XSL Transformer configuration to tell Mule with which value the parameter in the XSLT file should be filled:

1
2
3
4
5
6
7
8
9
10
11
12
13

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
     xmlns:xm="http://www.mulesource.org/schema/mule/xml/2.2"
     ...
     xsi:schemaLocation="
      http://www.mulesource.org/schema/mule/xml/2.2 http://www.mulesource.org/schema/mule/xml/2.2/mule-xml.xsd
     ...
     ">
    <xm:xslt-transformer name="orderToInvoiceTransformer" xsl-file="xsl/order-to-invoice.xsl" outputEncoding="UTF-8">
        <xm:context-property key="invoiceNr" value="#[message:correlationId]"/>
    </ship:xslt-transformer>
    ...
</mule>

This makes it a very clean and powerful way to add metadata to your payload might you ever need this.

One of the main functions of a Mule ESB application (besides transporting messages) is transforming messages to another format. Nowadays a lot of messages are XML based so a lot of transformations are done by using XSLT, or in Mule terminology, an XSLT Transformer. In our current project this is no different.

As I posted before we happily using Altova Mapforce for this. But this also means that a lot of changes and issues during the development are being solved by modifying the XSLT. In our Mule ESB setup we have deployed our Mule applications as a WAR in Tomcat. So this means to take our modified XSLT into account we have to redeploy the WAR or at least, stop and start the WAR in Tomcat. And as we found out, if the Mule application is inside a JAR inside the WAR we had to stop and start the complete Tomcat instance for our changes to be picked up.

To solve this issue we have created our own instance of the Xslt Transformer in Mule. Our implementation checks for the timestamp of the XSLT file and reloads it if there is found a newer XSLT file. This way we don’t have to restart our Tomcat if a newer version is in place. In a production environment you might want to discard this functionality to avoid unexpected behaviour of the running applications but I leave that up to you. In this post I will show you how our implementation of the XSLT Transformer works.
The example I use in this pots is the same as I had in the previous post. I have an XSD that describes an Order and I transform it with a XSL file to an Invoice. The schema for the Order looks like this:

The schema for the Invoice looks like this:

The mapping in MapForce looks like this:

Now for the real thing. Here you can find the complete code of our version of the XSL Transformer. Next I show just the important parts that we have changed

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

package nl.redstream.transformer;
 
import …
 
/**
* This class is mainly a copy of the XsltTransformer supplied by Mule.
* Checks are added for the XSLT file timestamp, so if the XSLT file is changed
* , the pool will be reloaded, so the new version of the XSLT is used.
*
* @author Redstream
*/
public class XsltTransformer extends AbstractXmlTransformer implements MuleContextAware
{
...
  /* added by Redstream */
  private long lastModified;
 
...
  @Override
  public void initialise() throws InitialisationException
  {
    try
    {
      // Set XSLT timestamp
      java.net.URL url = IOUtils.getResourceAsUrl(xslFile, getClass());
      File file = null;
 
      try
      {
        file = new File(url.toURI());
      }
      catch (URISyntaxException e)
      {
        file = new File(url.getPath());
      }
      if (file != null)
      {
        this.lastModified = file.lastModified();
      }
      transformerPool.addObject();
    }
    catch (Throwable te)
    {
      throw new InitialisationException(te, this);
    }
  }
...
  protected void doTransform(String encoding, Source sourceDoc, Result result)
    throws Exception
  {
    DefaultErrorListener errorListener = new DefaultErrorListener(this);
    javax.xml.transform.Transformer transformer = null;
 
    // Check XSLT timestamp and reload
    java.net.URL url = IOUtils.getResourceAsUrl(xslFile, getClass());
    File file = null;
    try
    {
      file = new File(url.toURI());
    }
    catch (URISyntaxException e)
    {
      file = new File(url.getPath());
    }
    if (file != null && file.lastModified() > this.lastModified)
    {
      if (logger.isDebugEnabled())
      {
        logger.debug("Reloading " + file.getAbsolutePath());
      }
      this.transformerPool.clear();
      this.transformerPool.addObject();
 
      this.lastModified = file.lastModified();
    }
    ...
  }
...
}

As promised in our previous blog about Altova Mapforce we will show in this post how to combine the result of the generated code of Altova Mapforce with a Mule application. As we have shown before, the Java code that is generated by MapForce is divided in two parts:

• one is Altova generic, so will be reused for each mapping
• one is mapping specific so is the actual part that changes with the mapping (this package name is configurable)

We first jarred the Altova generic code and added it to our Maven repository (Artifactory) so we can include this in our Mule project as dependency. We removed the generated mapping-specific Java code and used the included Ant build script to create the jar file. Here is a screenshot of how it looks in Artifactory:

Now if we want to use Mapforce generated code, we add the following dependency to the pom:

1
2
3
4
5

<dependency>
  <groupId>com.altova</groupId>
  <artifactId>mapforce-core</artifactId>
  <version>2010R2</version>
</dependency>

The next step is to add the generated mapping-specific code to the project. We do this by copying the generated mapping specific code to our Mule project (in MapForce you can configure the package name to be used for the generated code so that makes it easier fitting in
with the rest of the code). Here is a screenshot of the code to copy in this case:

Then we created a Transformer class in the Mule project that calls the generated mapping code and returns the result.
Here is an example of a Transformer which uses the generated code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

package nl.redstream.transformers;
 
import com.altova.io.StreamInput;
import com.altova.io.StringInput;
import com.altova.io.StringOutput;
import java.io.InputStream;
import nl.redstream.mapping.MappingMapTocustomer2;
import org.mule.api.transformer.TransformerException;
import org.mule.transformer.AbstractTransformer;
 
/**
 *
 * @author pascal
 */
public class CustomerCsvToXmlTransformer extends AbstractTransformer {
 
    public CustomerCsvToXmlTransformer() {
        registerSourceType(InputStream.class);
        registerSourceType(String.class);
        setReturnClass(String.class);
    }
 
    @Override
    protected Object doTransform(Object payload, String encoding)
            throws TransformerException {
 
        MappingMapTocustomer2 mappingToXml = new MappingMapTocustomer2();
        StringOutput output = new StringOutput();
 
        if (payload instanceof String) {
            StringInput input = new StringInput((String) payload);
            try {
                mappingToXml.run(input, output);
            } catch (Exception ex) {
                throw new TransformerException(this, ex);
            }
 
        } else if (payload instanceof InputStream) {
            StreamInput sInput = new StreamInput((InputStream) payload);
            try {
                mappingToXml.run(sInput, output);
            } catch (Exception ex) {
                throw new TransformerException(this, ex);
            }
 
        }
        return output.getString().toString();
    }
}

That’s it! Define the transformer as a ‘custom-transformer’ in your Mule config and your done. You can now create and maintain all your mappings visually with MapForce.
We are now looking into the capabilities that SPL (Spy Programming Language) offer, because it looks like we can generate the Mule Transformer straight from MapForce, that would even boost the producivity more!

Although we see many advantages in using (free) open source tools or frameworks we keep our eyes open to check whether the chosen open source solution is best for our customer.

We recently had a situation where we preferred a commercial solution over an open source one.
For a specific interface, we had to map a CSV file to an XML file and this transformation should be processed by the Mule ESB. At first we looked at Smooks to tackle this issue, as I described here. It resulted in a workable solution, but as you can read in post, the transformation had to take place in two steps: first from CSV to simple XML format and secondly, a transformation from the simple XML to a more advanced XML schema. For this second transformation we made use of an XSL stylesheet. We created the XSL file used for the transformation by making use of Altova MapForce.
However, MapForce can do a lot more then this simple XML to XML mapping. One of the things it can do is map CSV directly to (advanced) XML. This can’t be done with just a XSL translation anymore, but MapForce can generate Java code to perform the transformation at runtime. In this post I will show how you can use MapForce to generate the code. In a next post I will show you how to combine this generated code with the Mule ESB as a transformer.

The CSV file for this example looks like:

firstname|lastname|city|country
Steve|Jobs|Cupertino|USA
Bill|Gates|Washington|USA
Pascal|Alma|Papendrecht|Netherlands

As you can see a pipe-separated file with labels at the first row. When we add it to MapForce as an input source we configure it like:

The XSD to which the CSV file has to be mapped looks like:

In MapForce this target is configured like this:

The mapping in MapForce is quite simple and looks like this:

The output of the mapping can be viewed in MapForce (by pressing the “Output” tab) and looks like this (for this particular input file):

To perform this transformation in a Java environment we’ll generate Java code, after setting the package name that is generated by MapForce:

The code that is generated by MapForce looks like this:

As you can see, two packages are generated:

• com.altova

The ‘com.altova’ package contains ‘generic’ code that is necessary for each MapForce mapping in Java. It contains global types, functions and so on.

• nl.redstream

The ‘nl.redstream’ package is the package name we configured. This one contains the code that is specific for our mapping.

Beside these packages a Eclipse project file is generated and a Ant build script. To build this Java code you can run Ant with the following command:

To run the code after you build it you can use the following command:
java nl.redstream.CustomerMappingApplication

You will get a Frame like this:

Unfortunately by using the generated Main classes, the transformation can only be done on the files that where used as input for the mapping in this code. In the next post I will show how to use this generated code and use it as a Transformer in our Mule application.

For a lot more info about the Java generation possiblities of MapForce look here.