Although I am not always happy with the online documentation of the Mule ESB I found this article quite good. I have set up our configuration of Mule ESB implementation on several projects this way and it has proved to be working nicely. Although last time I got into the following issue. To use a datasource in my Mule3 project I had configured it like this in my Mule config file:

1
2
3
4
5
6
7

<jdbc:oracle-data-source 
          name="jdbcDataSource" 
          user="${db.username}" 
          password="${db.password}" 
          host="${db.host}" 
          port="${db.port}" 
          sid="{db.sid}" />

However, when I deployed the application on my Mule instance I got the following XML parse exception:

org.xml.sax.SAXParseException: cvc-datatype-valid.1.2.1: ‘${db.port}’ is not a valid value for ‘integer’.

This is caused by the fact that the XML is validated against its XSD before the parameters are resolved. Although I found threads in several forums that described a solution for this issue I chose the following (pragmatic) solution. I decided to configure the datasource like this:

1
2
3
4
5

<jdbc:oracle-data-source 
         name="jdbcDataSource" 
         user="${db.username}" 
         password="${db.password}" 
         url="jdbc:oracle:thin:@//${db.host}:${db.port}/${db.sid}" />

This way the XML validates fine against its XSD and during runtime the parameters are resolved.

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

Some time ago I was asked to review existing web services for a customer. The main thing I noticed was that they were using Microsoft’s diffgram elements and attributes in their input and output messages. I was not familiar with this format but found out that it has been created by Microsoft to make synchronizing datasets in .Net easier. In this case the web services were implemented with Spring-WS, so there was no real reason to use this format on the server side. Besides, it only makes the web service less useful on the client side since it leads to complications if you want to use a XML-Object mapper like JAXB (see this for example). One of the issues with Diffgram is that, besides the XML containing the Diffgram element, also the XSD is included. This XSD describes the content of the Diffram Dataset, however, the XSD and the resulting Dataset do not match because extra attributes are added (this is described in more detail here).
I decided to create a new web service that would accept incoming messages without this diffgram and ms-data elements and attributes (and would have a similar response). To make this work, I made use of an XSL transformation in combination with the interceptors in Spring-WS (the assumption is that only the content of the DataInstance part of the DiffGram are interesting).
For example this is the original request the web service is expecting:

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

<?xml version="1.0" encoding="UTF-8"?>
<diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
	<CustomerDataSet>
		<Customers diffgr:id="Customers1" msdata:rowOrder="0" diffgr:hasChanges="inserted">
			<CustomerID>ALFKI</CustomerID>
			<CompanyName>New Company</CompanyName>
		</Customers>
		<Customers diffgr:id="Customers2" msdata:rowOrder="1"  diffgr:hasChanges="inserted">
			<CustomerID>ANATR</CustomerID>
			<CompanyName>Ana Trujillo Emparedados y Helados</CompanyName>
		</Customers>
		<Customers diffgr:id="Customers3" msdata:rowOrder="2"  diffgr:hasChanges="inserted">
			<CustomerID>ANTON</CustomerID>
			<CompanyName>Antonio Moreno Taquera</CompanyName>
		</Customers>
		<Customers diffgr:id="Customers4" msdata:rowOrder="3"  diffgr:hasChanges="inserted">
			<CustomerID>AROUT</CustomerID>
			<CompanyName>Around the Horn</CompanyName>
		</Customers>
	</CustomerDataSet>
</diffgr:diffgram>

I created a new web service endpoint to which I added the XSLT interceptors. The new endpoint would expect this as a request:

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

<?xml version="1.0" encoding="UTF-8"?>
<CustomerDataSet>
	<Customers>
		<CustomerID>ALFKI</CustomerID>
		<CompanyName>New Company</CompanyName>
	</Customers>
	<Customers>
		<CustomerID>ANATR</CustomerID>
		<CompanyName>Ana Trujillo Emparedados y Helados</CompanyName>
	</Customers>
	<Customers>
		<CustomerID>ANTON</CustomerID>
		<CompanyName>Antonio Moreno Taquera</CompanyName>
	</Customers>
	<Customers>
		<CustomerID>AROUT</CustomerID>
		<CompanyName>Around the Horn</CompanyName>
	</Customers>
</CustomerDataSet>

As you can see this last example is quite simple and easy to use in combination with JAXB for example.
To create the original request out of the new one I made use of the following XSLT:

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

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:fn="http://www.w3.org/2005/xpath-functions" exclude-result-prefixes="xs fn fo">
	<xsl:output method="xml" encoding="UTF-8" indent="yes"/>
	<xsl:template match="/">
		<diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
			<xsl:copy>
				<!-- copy the attributes (if any) of the root element -->
				<xsl:copy-of select="@*"/>
				<xsl:apply-templates/>
			</xsl:copy>
		</diffgr:diffgram>
	</xsl:template>
	<!-- match any other element and copy it with the attributes -->
	<xsl:template match="*">
		<xsl:copy>
			<xsl:copy-of select="@*"/>
			<xsl:apply-templates/>
		</xsl:copy>
	</xsl:template>
	<xsl:template match="/CustomerDataSet/Customers">
		<Customers>
			<xsl:attribute name="id" namespace="urn:schemas-microsoft-com:xml-diffgram-v1">Customers<xsl:value-of select="position()"/></xsl:attribute>
			<xsl:attribute name="rowOrder" namespace="urn:schemas-microsoft-com:xml-msdata"><xsl:value-of select="position()-1"/></xsl:attribute>
			<xsl:attribute name="hasChanges" namespace="urn:schemas-microsoft-com:xml-diffgram-v1">inserted</xsl:attribute>
			<xsl:apply-templates/>
		</Customers>
	</xsl:template>
</xsl:stylesheet>

And for the response the opposite transformation is performed. The original response is used as input and the XSLT will filter out all diffgram and ms-data elements and attributes.
Here is an example XSL that takes the original CustomerDataSet as input and tranforms it the the more ‘simple’ format:

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

<?xml version="1.0" encoding="UTF-8"?>
<?altova_samplexml example-original.xml?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1" xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:fn="http://www.w3.org/2005/xpath-functions" exclude-result-prefixes="xs fn fo ">
	<xsl:output method="xml" encoding="UTF-8" indent="yes"/>
	<xsl:template match="/">
		<xsl:copy>
			<!-- copy the attributes (if any) of the root element -->
			<xsl:copy-of select="@*"/>
			<xsl:apply-templates/>
		</xsl:copy>
	</xsl:template>
	<!-- match any other element and copy it with the attributes. Use local-name to get rid of the diffgr and ms-data namespaces -->
	<xsl:template match="*">
		<xsl:element name="{local-name()}">
			<xsl:copy-of select="@*"/>
			<xsl:apply-templates/>
		</xsl:element>
	</xsl:template>
	<!-- do not copy the attributes for  element'Customers' "/> -->
	<xsl:template match="/diffgr:diffgram/CustomerDataSet/Customers">
		<xsl:element name="{local-name()}">
			<xsl:apply-templates/>
		</xsl:element>
	</xsl:template>
	<!-- Remove the tag for the diffgram -->
	<xsl:template match="/diffgr:diffgram">
		<xsl:apply-templates/>
	</xsl:template>
</xsl:stylesheet>

With this post I have shown how you can use a simple XSLT to get rid of the Diffgram elements and attributes, of course with some assumptions that should be taken into account.

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

Some of our Mule ESB applications make use of content-based routing when processing a message. To implement this in Mule we use a filtering-router with a jaxen-filter. The most simple example looks like this:

1
2
3
4
5
6
7
8

...
<outbound>
  <filtering-router>
    <vm:outbound-endpoint ref="out-queue" />
     <xm:jaxen-filter pattern="//firstname" expectedValue="Pascal"/>
  </filtering-router>
</outbound>
...

You can also use a XPath function in your jaxen-filter like this (if you want to check a certain element is in an XML message regardless the value of the element):

1
2
3
4
5
6
7
8

...
<outbound>
  <filtering-router>
    <vm:outbound-endpoint ref="out-queue" />
    <xm:jaxen-filter pattern="local-name(//Relations)" expectedValue="Relations"/>
  </filtering-router>
</outbound>
...

The problem starts if you have to declare namespaces in your XPath expression. You can use namespaces in your XPath expression by declaring a namespace-manager in your mule-config, like this:

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

...
 <xm:namespace-manager includeConfigNamespaces="false">
   <xm:namespace prefix="ns1" uri="http://www.redstream.nl/relations/v1_1"/>
 </xm:namespace-manager>
...
   <outbound>
     <filtering-router>
       <vm:outbound-endpoint ref="out-queue" />
       <xm:jaxen-filter pattern="local-name(//ns1:Relations)" expectedValue="Relations"/>
     </filtering-router>
   </outbound>
...

But if you run this example you will get the following exception:

org.jaxen.UnresolvableException: No Such Function {http://www.mulesource.org/schema/mule/core/2.2}:local-name
at org.jaxen.SimpleFunctionContext.getFunction(SimpleFunctionContext.java:127)
at org.jaxen.ContextSupport.getFunction(ContextSupport.java:242)
at org.jaxen.Context.getFunction(Context.java:216)
at org.jaxen.expr.DefaultFunctionCallExpr.evaluate(DefaultFunctionCallExpr.java:172)
at org.jaxen.expr.DefaultXPathExpr.asList(DefaultXPathExpr.java:102)
at org.jaxen.BaseXPath.selectNodesForContext(BaseXPath.java:674)
at org.jaxen.BaseXPath.selectSingleNodeForContext(BaseXPath.java:698)
at org.jaxen.BaseXPath.stringValueOf(BaseXPath.java:279)
at org.jaxen.BaseXPath.valueOf(BaseXPath.java:254)
at org.mule.module.xml.filters.JaxenFilter.accept(JaxenFilter.java:184)
at org.mule.module.xml.filters.JaxenFilter.accept(JaxenFilter.java:118)
at org.mule.routing.outbound.FilteringOutboundRouter.isMatch(FilteringOutboundRouter.java:119)
at org.mule.routing.outbound.DefaultOutboundRouterCollection. route(DefaultOutboundRouterCollection.java:72)
at org.mule.service.AbstractService.dispatchToOutboundRouter(AbstractService.java:867)
at org.mule.model.seda.SedaService.dispatchToOutboundRouter(SedaService.java:561)
at org.mule.model.seda.SedaService$ComponentStageWorker.doRun(SedaService.java:583)
at org.mule.work.AbstractMuleEventWork.run(AbstractMuleEventWork.java:41)
at org.mule.work.WorkerContext.run(WorkerContext.java:310)
at edu.emory.mathcs.backport.java.util.concurrent.ThreadPoolExecutor. runWorker(ThreadPoolExecutor.java:1061)
at edu.emory.mathcs.backport.java.util.concurrent.ThreadPoolExecutor$Worker. run(ThreadPoolExecutor.java:575)
at java.lang.Thread.run(Thread.java:637)

Although it is logged as warning it makes the filter to return no matching values and the XML message is discarded (although I use the jaxen-filter here this also goes for the jxpath-filter and the xpath-filter).

The solution for this is quite simple: just give the XPath function a unique prefix (one that is not mapped to a namespace). So if you modify the last example and make the jaxen-filter like:
<xm:jaxen-filter pattern="fn:local-name(//ns1:Relations)" expectedValue="Relations"/>
or
<xm:jaxen-filter pattern="abc:local-name(//ns1:Relations)" expectedValue="Relations"/>
it will work.
You just have to make sure the prefix you use isn’t used in the declared namespace-manager because then the function is looked up (and not found) in the supplied XML document.

Mule ESB is a versatile service bus that contains numerous usable components out-of-the-box. In this blog I’ll show you how to process an incoming XML document, break it up into multiple parts and insert them into the database without using any custom Java classes.

In this example we will be using this (simple) XML document as source input. The document contains a collection of Customers.

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

<?xml version="1.0" encoding="UTF-8"?>
<customers>
   <customer>
      <firstName>Steve</firstName>
      <lastName>Jobs</lastName>
      <address>
         <street>1 Infinite Loop</street>
         <city>Cupertino</city>
         <country>USA</country>
      </address>
   </customer>
   <customer>
      <firstName>Bill</firstName>
      <lastName>Gates</lastName>
      <address>
         <street>1 Microsoft Way</street>
         <city>Washington</city>
         <country>USA</country>
      </address>
   </customer>
</customers>

After breaking the XML up into multiple Customer entities, we will insert them into the following database structure:

1
2
3
4
5
6
7

create table CUSTOMERS (
   first_name VARCHAR2(32)
,  last_name VARCHAR2(64)
,  street VARCHAR2(128)
,  city VARCHAR2(128)
,  country VARCHAR2(3)
);

To split the XML document into multiple Customer entities, we’ll use an outbound splitting router like this one:

1
2
3

<expression-splitter-router evaluator="xpath" expression="//Customer">
   <stdio:outbound-enpdoint system="OUT"/>
</expression-splitter-router>

The xpath evaluator mentioned in the expression-splitter-router excepts both Dom and String objects. This means we can just use plain XML files (no need to create a w3c.dom.Document first. It’ll be parsed on-the-fly.

Once the message has been split, we want each Customer to be inserted into a database. The trick here is to use the JDBC transport. We’ll need to configure a connector in which
“named queries” can be configured. A “named query” is a PODS (~Plain Old Dml Statement) identified by a key.

1
2
3
4

    <jdbc:connector name="jdbcConnector" dataSource-ref="jdbcDataSource">
        <jdbc:query key="insertIntoFoobar"
                    value="insert into FOOBAR (id, code, description) VALUES (#[map-payload:ID], #[map-payload:CODE], #[map-payload:DESCRIPTION])"/>
    </jdbc:connector>

In this example, a Map payload is expected from which the values are derived. When using XML, an XPATH expression evaluator seems more appropriate (see final solution).

PS: It might be nice to know that unnamed queries are also supported.

I’ve introduced the basics, now let’s have a look at the complete Mule configuration:

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

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:vm="http://www.mulesource.org/schema/mule/vm/2.2"
      xmlns:xm="http://www.mulesource.org/schema/mule/xml/2.2"
      xmlns:jdbc="http://www.mulesource.org/schema/mule/jdbc/2.2"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:context="http://www.springframework.org/schema/context"
      xsi:schemaLocation="
      http://www.mulesource.org/schema/mule/core/2.2 http://www.mulesource.org/schema/mule/core/2.2/mule.xsd
      http://www.mulesource.org/schema/mule/vm/2.2 http://www.mulesource.org/schema/mule/vm/2.2/mule-vm.xsd
      http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
      http://www.mulesource.org/schema/mule/xml/2.2 http://www.mulesource.org/schema/mule/xml/2.2/mule-xml.xsd
      http://www.mulesource.org/schema/mule/jdbc/2.2 http://www.mulesource.org/schema/mule/jdbc/2.2/mule-jdbc.xsd
      http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd">
 
    <context:property-placeholder location="classpath:my.properties"/>
 
    <spring:bean id="jdbcDataSource" class="org.enhydra.jdbc.standard.StandardDataSource" destroy-method="shutdown">
        <spring:property name="driverName" value="${db.driverName}"/>
        <spring:property name="url" value="${db.url}"/>
    </spring:bean>
 
    <jdbc:connector name="jdbcConnector" dataSource-ref="jdbcDataSource">
        <jdbc:query key="insertCustomer"
                    value="insert into CUSTOMERS (first_name, last_name, street, city, country) VALUES (#[xpath://Customer/FirstName],#[xpath://Customer/LastName],#[xpath://Customer/Address/Street],#[xpath://Customer/Address/City],#[xpath://Customer/Address/Country])"/>
    </jdbc:connector>
 
    <xm:namespace-manager includeConfigNamespaces="true">
        <xm:namespace prefix="cus" uri="http://www.redstream.nl/schema/customer/1.0"/>
    </xm:namespace-manager>
 
    <model>
 
        <service name="processCustomers">
            <inbound>
                <vm:inbound-endpoint path="processCustomersService"/>
            </inbound>
 
            <outbound>
                <expression-splitter-router evaluator="xpath" expression="//Customer">
                    <jdbc:outbound-endpoint queryKey="insertCustomer"/>
                </expression-splitter-router>
            </outbound>
        </service>
 
    </model>
 
</mule>

Et voila … using the above configuration, you will be able to process incoming XML and insert the contents in a database.

Some final notes:

• Use a property-placeholder to configure the database credentials.
• When incoming XML contains namespaces, they could globally be configured using a namespace-manager
• Notice that the jdbc:outbound-endpoint refers to the named query by key
• The named query will be “injected” with a single Customer entity, accessible by the XPATH expression evaluator

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.

XML is quite common nowadays, especially in the application integration business that I am involved in. However, I still see companies making big mistakes when they decide to start using XML (for example as the exchange format with their business partners). This series of posts is about mistakes (or at least clumsiness) in using XML that I noticed during several projects.

No use of versions in namespaces

In the previous post I already explained the usefulness of using namespaces in your XML schemas. The next improvement would be to make a version number be part of the namespace. Imagine if you don’t do that and you have to modify your schema. And with modifying I mean a serious change like adding a mandatory element to your schema. If you make this change then all systems and clients using your schema for their interaction will fail to do so as long as they haven’t changed their side of the interface. So actually you are forcing others to make modifications to their system. If I were a client of such a supplier I would definitely be unhappy with this kind of actions.
A nice way to avoid this situation is when you add a version number in the namespace of your schema. In that case you can create a new schema with a new namespace.
For example, the old situation:

xmlns:tns=”http://www.redstream.nl/message

becomes

xmlns:tns=”http://www.redstream.nl/message/v01_0

Now you can let the users of your schema decide when they are going to use the newer version. Of course you can provide a roadmap about when which version will become deprecated or even unusable.
This post concludes the series about using XML in real life projects. There are a lot more issues to discuss but I thought these were the most relevant to share. The final thing I want to mention is that you should use XML as meaning to get at your goal, it should not be the goal itself.

XML is quite common nowadays, especially in the application integration business that I am involved in. However, I still see companies making big mistakes when they decide to start using XML (for example as the exchange format with their business partners). This series of posts is about mistakes (or at least clumsiness) in using XML that I noticed during several projects.

Not making (useful) use of namespaces

As blogged before I had situations where I received XML files to describe the interface file without a schema (XSD). In this situation I did receive a schema, actually several schemas. Unfortunately, they forgot (?) to make use of XML namespaces. In each different XSD they added a description of the same xml type ‘OrderType’. You can imagine the rework you have if you have to change this ‘OrderType’; they have to modify all XSD’s and we had to regenerate all our JAXB objects. It would be much better if they supplied a separate XSD for the order element, gave it a namespace and import that in the other schemas. Another big advantage of using namespace is the possibility to distinct different versions of the same schema. I will clarify this issue in the next post.