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!

We use a fair lot of XSLT transformations in our projects. Since making XSLT stylesheets is a tedious and error-prone job, we use Altova MapForce to do the job. MapForce is very versatile, but can not always cope with the requirements our customers come up with. This time, the customer asked us to implement some sort of maintainable translation mechanism. This mechanism should be able to translate incoming values using a user maintainable collection of values. This way, the transformation process does not need to be changed if a translation is added or updated.

Adding a (hardcoded) parameterized XSLT template is not an option, because this is not maintainable without changing the stylesheet. The answer? XSLT Java extensions!

In this blog I’ll show you a simple example on how to use Java extensions in a XSLT 2.0 stylesheet.

We’ll start with a very simple “Hello World!”-isch example. I’ve created the following Java class which we will be using in our stylesheet:

Our custom Java class

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

package nl.redstream.utils;
 
import java.io.IOException;
import java.util.Properties;
 
public class XsltUtils {
 
    /**
     * Your default Hello World! method.
     */
    public static String greeting(String name) {
        return "Hello, " + name + " !";
    }
 
}

Notice that the greeting method is public static (not really needed, but makes things easier) .

I packaged the project into a single jar (let’s assume it is called: redstream-xslt-demo-1.0-SNAPSHOT.jar) using mvn clean package.

The XSL stylesheet

Next up, creating our stylesheet ! (We will be dealing with the jar later) Use the following stylesheet:

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

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0" 
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    xmlns:fn="http://www.w3.org/2005/xpath-functions"
    xmlns:demo="java:nl.redstream.utils.XsltUtils" 
    exclude-result-prefixes="fn demo">
  <xsl:output method="xml" encoding="UTF-8" indent="yes"/>
  <xsl:template match="/">
    <dataset>
      <xsl:for-each select="dataset">
        <row>
          <xsl:for-each select="row/column">
            <column>
              <xsl:attribute name="name" select="@name"/>
              <xsl:attribute name="value" select="demo:greeting(fn:string(@value))"/>
            </column>
          </xsl:for-each>
        </row>
      </xsl:for-each>
    </dataset>
</xsl:template>
</xsl:stylesheet>

Notice two things:
- Line 5 contains a declaration of our custom namespace. Just java: and the FQN of your custom Java class. The prerequisite is that the class (optionally packaged in a jar) is on the classpath.
- Line 15 contains a reference to our Java function. Notice that you can use an Xpath expression which will be resolved at runtime and passed as an argument to the greeting method.

Disclaimer

Remember the declaration of the namespace? This is dependent of the used XSLT engine. When using Saxon, you have to use the java:FQN declaration. When you are using Xalan, for example, you use xalan://FQN. Please check the documentation of your selected XSLT engine, before you declare the namespace.

XMLSpy

We could perform the XSL transformation using the command line, but we are using Altova XMLSpy for this. By default, XMLSpy uses a built-in XSLT engine, but this can be changed to a custom one. Goto: “Tools -> Options: External XSL transformation program” and copy-paste the following: java -cp C:\develop\redstream-xslt-demo-1.0-SNAPSHOT.jar;C:\develop\saxon8.jar net.sf.saxon.Transform -o %2 %1 %3.

We will be using Saxon as XSLT engine, because the endresult will be packaged in a Mule ESB application … and Mule uses Saxon (so, that’s why). Should you want to use another XSLT engine, customize the ‘External XSL transformation program’ in XMLSpy accordingly. Notice that all necessary jar’s are copied to the c:\develop directory and included in the classpath (including our custom jar).

Assign the following XML to the XSL using XSL/XQuery -> Assign sample XML file:

1
2
3
4
5
6
7

<?xml version="1.0" encoding="UTF-8"?>
<dataset>
  <row>
    <column name="greeting" value="foo"/>
    <column name="another" value="bar"/>
  </row>
</dataset>

After pressing F10 the following output should be the result of the transformation:

1
2
3
4
5
6
7

<?xml version="1.0" encoding="UTF-8"?>
<dataset>
   <row>
      <column name="greeting" value="Hello, foo !"/>
      <column name="another" value="Hello, bar !"/>
   </row>
</dataset>

What’s happened is that values foo and bar were passed to the Java greeting method and returned the displayed string. Of course this is a simplified example, but you’ll catch the drift. This opens up possibilites: you now can breakout of the XSLT 2.0 barriers and use Java where needed. Use your imagination to create your own custom Java class.

That’s it … we’ve shown that you can use custom Java classes in your XSLT 2.0 transformation. In my next post, I’ll show you how to extend Altova MapForce and make this reusable (read: drag-and-drop the Java methods graphically to auto generate the XSLT 2.0 stylesheet).

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.

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.