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.

As I wrote before it is quite easy to set up a web service proxy with Mule3. in this example I take it a step further and I describe how you can add WS-Security implementation to it. Although in the end this also is quite easy you have to make the correct configuration choices to get everything to work.

The first thing I had to do in my Mule config was to drop the pattern prefix. This took me a while to discover because I think this isn’t very clear in the documentation. Anyway, after that change it is fairly straight forward.

Here is the Mule config I ended up with:

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

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:cxf="http://www.mulesoft.org/schema/mule/cxf"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:http="http://www.mulesoft.org/schema/mule/http"
      xsi:schemaLocation="
        http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.2/mule.xsd
        http://www.mulesoft.org/schema/mule/cxf http://www.mulesoft.org/schema/mule/cxf/3.2/mule-cxf.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/3.2/mule-http.xsd">
 
    <flow name="create-client">
        <http:inbound-endpoint address="http://localhost:8080/create-client">
            <cxf:proxy-service/> 
        </http:inbound-endpoint>
        <http:outbound-endpoint address="http://localhost:8081/create-client">
            <cxf:proxy-client>
                <cxf:outInterceptors>
                    <spring:bean class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor">
                        <spring:constructor-arg>
                            <spring:map>
                                <spring:entry key="action" value="Timestamp Signature" />
                                <spring:entry key="user" value="${signature.user}" />
                                <spring:entry key="signaturePropFile" value="ws-security.properties" />
                                <spring:entry key="passwordCallbackClass" value="nl.redstream.adapter.MyKeystorePasswordCallback"/>
                            </spring:map>
                        </spring:constructor-arg>
                    </spring:bean>
                    <spring:bean class="org.apache.cxf.interceptor.LoggingOutInterceptor" />
                </cxf:outInterceptors>
            </cxf:proxy-client>
        </http:outbound-endpoint>    
    </flow>
    <flow name="get-client-status">
        <http:inbound-endpoint address="http://localhost:8081/get-status">
            <cxf:proxy-service>
                <cxf:inInterceptors>
                    <spring:bean class="org.apache.cxf.interceptor.LoggingInInterceptor" />
                    <spring:bean class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor">
                        <spring:constructor-arg>
                            <spring:map>
                                <spring:entry key="action" value="Signature" /> 
                                <spring:entry key="signaturePropFile" value="ws-security.properties" />
                            </spring:map>
                        </spring:constructor-arg>
                    </spring:bean>
                </cxf:inInterceptors>
            </cxf:proxy-service>
        </http:inbound-endpoint>
        <http:outbound-endpoint address="http://localhost:8080/get-status">
            <cxf:proxy-client />
        </http:outbound-endpoint>    
    </flow>
</mule>

As you can see I have added two flows. The first flow is ‘create-client’. I receive the incoming call from my own ‘inside’-application and add a signature and timestamp to it before I forward it to the ‘outside’ service.
The second flow works the other way around: I receive a signed message from the ‘outside’ client app and I need to validate this before I pas the message to my ‘inside’ application. To create the signature I need the password for to make use of my private key in the keystore. To supply this password I simply implemented the PasswordCallbackHandler that returns the corresponding password by looking it up in a property file. For more info about configuring the WS-security with CFX see here and also I found this entry about Apache WSS4J quite handy.
The security property file that is referred to in my Mule config file contains the following:

1
2
3
4

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=JKS
org.apache.ws.security.crypto.merlin.file=/KeyStores/redstreamKeystore.jks
org.apache.ws.security.crypto.merlin.keystore.password=myPassword

For both flows I added the logging interceptor which is quite handy during testing and developing to see what is received and sent out. In the next post I will show how to generate the keystores and configure SoapUI to test the proxy manually.

In this post I show you how I setup a little test to see if and how easy I could manage to route the traffic to and from a web service through Mule ESB. The business case for this is an issue that one of our customers ran into when using web services. In a program hundreds of calls are done in a relative short period. Most of the time this isn’t a problem but sometimes vague issues occur. To get a better insight in this issue I want to put Mule in the middle so I can log the request and response and hopefully get a better idea about what is sent across the line. This is called the Web Service Proxy pattern and is commonly used to validate and audit the web service calls. For more background info about this pattern see this article.

To get started I downloaded the Mule Standalone edition here and installed it. That isn’t very hard, just untar the thing and set the MULE_HOME property. Go to the bin directory and give ‘./mule’ and off you go (except for a warning when running on MacOS 64-bit, but it doesn’t seem to harm so far…):

To create a test web service I setup a MockService in SoapUI. Like this:

All you need is a WSDL available. I just picked one from a previous project for testing purposes. With this MockService started you can fire your SOAP requests and will receive a (predefined) response from the MockService:

Next step is create a new Mule project (I still favor Maven above the Mule Studio):

• create new Maven project with

mvn mule-project-archetype:create -DartifactId=WSProxy -DmuleVersion=3.1.2

• Set up the WS Proxy

To create WS Proxy I followed the description here
Note: to make use of the pre-defined ‘pattern’ you must add the following dependency to the pom:

1 2 3 4 5 6

<dependency> <groupId>org.mule.patterns</groupId> <artifactId>mule-patterns-all</artifactId> <version>${mule.version}</version> <scope>provided</scope> </dependency>

My Mule config file looks like this:

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

<?xml version="1.0" encoding="UTF-8"?> <mule xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:pattern="http://www.mulesoft.org/schema/mule/pattern" xsi:schemaLocation=" http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.1/mule.xsd http://www.mulesoft.org/schema/mule/pattern http://www.mulesoft.org/schema/mule/pattern/3.1/mule-pattern.xsd"> <description> Proxies a Web Service </description> <custom-transformer name="my-transformer" class="nl.redstream.proxy.wsproxy.MyTransformer" /> <object-to-string-transformer name="ObjectToStringTransformer" />   <pattern:web-service-proxy name="my-order-ws-proxy" inboundAddress="http://Pascal-Almas-MacBook-Pro.local:8090/my-order" responseTransformer-refs="ObjectToStringTransformer my-transformer" outboundAddress="http://Pascal-Almas-MacBook-Pro.local:8088/mockDataServiceSoapBinding" /> </mule>

• Fire up the proxy

To run the Mule application just make sure your Mule installation is running and in your project execute the command ‘mvn clean install’
You should see a message in your Mule console like this:

Now we can put the proxy at work by redirecting the SoapUI request to the url: http://Pascal-Almas-MacBook-Pro.local:8090/my-order. It should the be forwarded to the original url and the translator I put in between should output the content to the Mule console:

However if you try this for the first time big chance you will run into this issue (at least I did). To get around this issue modify the soapUI settings like this:

I got triggered by my previous post to create a process with which I could keep two instances of WordPress in sync. I wanted to see if I could do this with Mule. I came up with the following solution:

• Receive the RSS feed of a new post in Mule flow
• Use the content of the RSS feed to post to the other wordpress instance by using XML-RPC
• Have it running on Mule iON so I don’t have to setup my own Muleserver

So lets start a new Mule iON project. Since I am a big fan of Netbeans I use the Maven based approach (I must admit I have tried to use MuleStudio for this but it didn’t bring me the productivityboost I hoped for).
I created the Mule project with:

mvn org.mule.tools:mule-project-archetype:create -DartifactId=wordpress-copy-service -DgroupId=nl.redstream.mule-ion -Dinteractive=false -Dmodules=rss -DmuleVersion=3.1.1


The Mule config looks like:

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"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:http="http://www.mulesoft.org/schema/mule/http"
      xmlns:rss="http://www.mulesoft.org/schema/mule/rss"
      xmlns:spring="http://www.springframework.org/schema/beans"
    xsi:schemaLocation="
        http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.1/mule.xsd
        http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/3.1/mule-http.xsd
        http://www.mulesoft.org/schema/mule/rss http://www.mulesoft.org/schema/mule/rss/3.1/mule-rss.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">
    <spring:bean name="xmlRpcHelper" class="nl.redstream.rss.XmlRpcHelper">
        <spring:constructor-arg value="http://www.pragmatic-integrators.com/xmlrpc.php" type="java.lang.String"/>
        <spring:constructor-arg value="UserName" type="java.lang.String"/>
        <spring:constructor-arg value="Password" type="java.lang.String"/>
    </spring:bean>
    <spring:bean name="entryReceiver" class="nl.redstream.rss.EntryReceiver">
        <spring:constructor-arg ref="xmlRpcHelper"/>
    </spring:bean>
    <flow name="poll-and-post">
        <poll frequency="36000000">
            <http:outbound-endpoint address="http://www.redstream.nl/feed/" />
        </poll>
        <rss:feed-splitter />
        <component>
            <spring-object bean="entryReceiver"/>
        </component>
    </flow>
</mule>

As you can see I poll the website ‘www.redstream.nl’ once each 10 hours. The RSS feed I receive is split and sent to my custom made component ‘entryReceiver’. It would be nice to use a XML-RPC endpoint here but this isn’t created yet (and actually I don’t feel like it neither).

The EntryReceiver looks like:

Disclaimer: just wanted to see if it worked, I did not try to build a robust solution that had to work for every WordPress site, so you are warned!

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

package nl.redstream.rss;
 
import org.mule.api.annotations.param.Payload;
import com.sun.syndication.feed.synd.SyndEntry;
 
public class EntryReceiver {
 
    XmlRpcHelper xmlRpcHelper = null;
 
    public EntryReceiver(XmlRpcHelper helper) {
        xmlRpcHelper = helper;
    }
    public void readEntry(@Payload SyndEntry entry) throws Exception {
 
        // Get the title
        String title = entry.getTitle();
 
        // Check if title exist in current blogs on the new blogsite
       if (!xmlRpcHelper.titleExists(title)) {
            xmlRpcHelper.post(entry);
 
        } else {
            // Skip this post
        }
    }
}

And the bean where the dirty work is done:

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
80
81
82
83
84
85
86
87
88

package nl.redstream.rss;
 
import java.net.MalformedURLException;
import java.net.URL;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
 
import org.apache.xmlrpc.XmlRpcException;
import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
 
import com.sun.syndication.feed.synd.SyndContentImpl;
import com.sun.syndication.feed.synd.SyndEntry;
 
public class XmlRpcHelper {
 
    private String url;
    private String userName;
    private String password;
    XmlRpcClient client = new XmlRpcClient();
 
    public XmlRpcHelper(String url, String u, String p) {
        this.url = url;
        this.userName = u;
        this.password = p;
 
        XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
        try {
            config.setServerURL(new URL(url));
        } catch (MalformedURLException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
        client.setConfig(config);
    }
 
    public boolean titleExists(String title) {
        return getRecentTitles().contains(title);
    }
 
    public void post(SyndEntry entry) {
        StringBuilder content = new StringBuilder("<content><title>").append(entry.getTitle()).append("</title>");
        List<SyndContentImpl> contents = entry.getContents();
 
        for (SyndContentImpl syndContent : contents) {
            content.append(syndContent.getValue());
        }
        content.append("</content>");
        try {
            client.execute("blogger.newPost", new Object[]{"bla", 1,
                        userName, password, content.toString(), true});
        } catch (XmlRpcException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
    }
 
    private List<String> getRecentTitles() {
        List<String> titles = new ArrayList<String>();
        try {
            Object token = client.execute("blogger.getRecentPosts", new Object[]{"bla", 1,
                        userName, password, 10});
 
            Object[] result = (Object[]) token;
            for (int i = 0; i < result.length; i++) {
                titles.add(getTitle((HashMap<String, Object>) result[i]));
            }
        } catch (XmlRpcException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
            // return null;
        }
        return titles;
    }
 
    private static String getTitle(Map response) {
        String title = null;
        String content = (String) response.get("content");
 
        if (content != null) {
            title = content.substring(content.indexOf("<title>") + 7,
                    content.indexOf("</title>"));
        }
        return title;
    }
}

One thing that kept me busy for a while was that the first String in the Object array that is supplied with the XmlRpc call may contain anything as long as it contains something. An emptry String “” is ignored in the call and will lead to an invalid Username/Password message.

If all this is in place you can build the project with: ‘mvn clean install’. This will create a zip file in the target directory. This zip file can then be uploaded with your dashboard to your Mule iON instance:

And that’s it! As you can see the two sites ‘www.redstream.nl’ and ‘www.pragmatic-integrators.com’ are know kept in sync (with a max. gap of 10 hrs). Of course the copied post is not an exact clone of the original (I am loosing info about the Author, Categories, etc. and images are referred to at the original location) but it shows that the main idea works!

Last week I migrated our site and blog to the Cloud. I got triggered by this article. That in the combination with the free account at Amazon’s EC2 was enough for me give it a try.
Now, if you came here via ‘www.redstream.nl’ you are looking at the version hosted at our own server. But if you got here via ‘www.pragmatic-integrators.com‘ you are looking at the version hosted in the Cloud.
After I migrated the site I realized how easy it is to use a server in the cloud and made me wonder why you should ever want your own physical ‘web’server. For the time being I will keep both instances alive so I can compare both solutions.
Now I have to find a way to keep these two instances in sync… That would be a nice use case using Mule iON to stay in the Clouds… I’ll post the solution here as soon as I have worked it out ;-)

Like I posted before Mulesoft has released a new platform: iPAAS. I just went through the starters guide and I am pretty impressed. Of course the use case in the tutorial is very simple but the whole idea of just putting your Mule config into the cloud and it runs sounds good. And I have seen it working (you can check for yourself by submitting text to this url.
Here is a snapshot of the dashboard you get with you Mule iON account:

Although it looks pretty nice at first sight it does raise questions and some topics for further investigation: what about security and in what use cases will this be the best solution? Mulesoft already has answers to those questions (security and use cases) but I am going to find out myself and let you know my opinion. Stay tuned!

Mulesoft recently released some new products, totally different from each other but both very welcome.
The first one is MuleStudio. Mule Studio is an Eclipse-based developer tool, that allows to graphically create and test Mule ESB Flows. It is currently in beta but I think it might be a good reason to go back to Eclipse. Last few years I have been using Netbeans for my Mule/Java development because I liked the combination between Netbeans and Maven better.

The other ‘product’ that is released is Mule iON. I think a graphical development tool is nice to have but this iON thing is something that can really become big. It makes you use the cloud as the platform for your integration software. They call it the iPAAS (Integration Platform as a Service).

The coming days I will have a look at both and posts my findings here so stay tuned!

As promised I’m going to show a test case for which I have used Citrus to implement it. The case is like this:
In a predefined folder on a machine a character-separated file is placed. This file is picked up by our Mule ESB application. The content is transformed to XML and this XML document is posted to another application over HTTP. This application responds with XML document telling the document was processed correctly.
To test this interface with Citrus we have to perform the following steps:

1. Copy the input test-file to the predefined folder so it is picked up by the test instance of our Mule ESB

Our Mule ESB will poll a directory each second to check if there is placed a new file to process. Our test case starts by having Citrus putting a test file in the directory .

2. Have Citrus listen on a predefined HTTP port to receive the XML message over HTTP

Inside our Mule ESB the file is transformed to XML message and posted on a HTTP port to be processed by the ‘ORDER’ system. We have configured Citrus to listen on this specific HTTP port to pick up the XML message.

3. Reply to the received message with a predefined XML message

This steps mimics the ‘ORDER’ system as it would normally process the incoming XML message and respond with another XML message. In this case Citrus will send back a predefined XML message as response.

The citrus-config.xml for this test case can be found here. I will explain the content of the config file next:

1
2
3
4
5
6

<bean id="citrusJMSConnectionFactory"
         class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="vm://localhost:61616" />
        <property name="userName" value="user"/>
        <property name="password" value="password"/>
</bean>

This part defines a ‘in-memory’ JMS provider to be used by Citrus. We will see later how we use it to check the incoming HTTP request (as described here in the Citrus reference guide).

1
2
3
4
5
6
7

<bean id="namespaceContextBuilder" class="com.consol.citrus.xml.namespace.NamespaceContextBuilder">
        <property name="namespaceMappings">
            <props>
                <prop key="ns1">http://www.redstream.nl/invoice</prop>
            </props>
        </property>
</bean>

Here we define the namespaces that are used in the xml messages in our test. We will use this namespace in the test to check values of certain XML elements.

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

<bean name="redstreamIntegrationTests"
         class="com.consol.citrus.TestSuite">
        <property name="tasksBefore">
            <list>
                <bean class="com.consol.citrus.actions.ExecuteSQLAction">
                    <property name="dataSource" ref="rsDataSource"/>
                    <property name="statements">
                        <list>
                            <value>DELETE FROM RS_LOGS</value>
                        </list>
                    </property>
                </bean>
            </list>
        </property>
</bean>

With this part I have Citrus clean up my log table in the database of my Mule ESB. We log all incoming and outgoing messages in our ESB to the database.

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

<!-- manadatory if XML files are used in a test -->
<bean id="xmlMessageValidator" class="com.consol.citrus.validation.xml.DomXmlMessageValidator"/>
    <bean id="schemaRepository"
           class="com.consol.citrus.xml.XsdSchemaRepository">
        <property name="schemas">
            <list>
                <bean class="org.springframework.xml.xsd.SimpleXsdSchema">
                    <property name="xsd"
                               value="classpath:schemas/rs_invoice_0.3.xsd"/>
                </bean>
            </list>
        </property>
</bean>

When you want to work with XML messages in your test (and that is very likely nowadays) you will need to define an ‘xmlMessageValidator’. And to be able to validate the message against an XML schema you will need to define the schemas in the ‘schemaRepository’ as I have done here.

1
2
3
4
5
6
7

<bean id="rsDataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
        <property name="url" value="jdbc:oracle:thin:@test-vm:1521:XE"/>
        <property name="username" value="user"/>
        <property name="password" value="password"/>
        <property name="driverClassName" value="oracle.jdbc.xa.client.OracleXADataSource"/>
        <property name="removeAbandoned" value="true"/>
</bean>

This is the datasource that Citrus can use to access the database that is used by our Mule ESB application. We use this datasource to clean up the logtable and can use it to perform validations after messages have been processed.

1
2
3
4
5

 <citrus:message-channel-sender id="invoiceFileSender" channel="fileOutboundChannel"/>
<file:outbound-channel-adapter id="invoice-files-out" channel="fileOutboundChannel"
        directory="file://Volumes/staging/invoice" filename-generator="test-filename-generator" />
<bean id="test-filename-generator" class="nl.redstream.citrus.TestFileNameGenerator" />
<si:channel id="fileOutboundChannel" />

This is a mix of Citrus with spring-integration configuration. With this configuration I am able to send files to my test VM with Citrus. It also shows how easy it is to mix Citrus with spring-integration.

1
2
3
4
5
6
7

<!-- receive Invoice HTTP request -->
<citrus-http:server id="orderHttpServer"
               port="8060"
               uri="/services/post-invoice"
               deamon="false"
               message-handler="jmsForwardingMessageHandler"
               auto-start="true"/>

Definition of the HTTP Server in Citrus which listens on port 8060 for a request of our Mule ESB.

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

 <bean id="jmsForwardingMessageHandler"
         class="com.consol.citrus.adapter.handler.JmsConnectingMessageHandler">
        <property name="destinationName" value="Citrus.order-response"/>
        <property name="connectionFactory" ref="citrusJMSConnectionFactory" />
        <property name="replyTimeout" value="6000"/>
    </bean>
 
    <!-- Process all received requests -->
    <citrus:jms-sync-message-receiver id="orderRequestReceiver"
                            destination-name="Citrus.order-response"
                            connection-factory="citrusJMSConnectionFactory" />
    <citrus:jms-reply-message-sender id="orderResponseSender"
                            reply-destination-holder="orderRequestReceiver"
                            connection-factory="citrusJMSConnectionFactory" />

THis part forwards the incoming HTTP request to a JMS endpoint. In our test we can perform tests on this incoming JMS message and check if it is valid.

Next thing I want to explain is the test-config.xml itself. I think it is quite self-explainatory:

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

<?xml version="1.0" encoding="UTF-8"?>
<spring:beans xmlns="http://www.citrusframework.org/schema/testcase"
              xmlns:ws="http://www.citrusframework.org/schema/ws/testcase"
              xmlns:spring="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://www.springframework.org/schema/beans
              http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
                  http://www.citrusframework.org/schema/ws/testcase
                  http://www.citrusframework.org/schema/ws/testcase/citrus-ws-testcase.xsd
                  http://www.citrusframework.org/schema/testcase
                  http://www.citrusframework.org/schema/testcase/citrus-testcase.xsd">
 
    <testcase name="Testcase001Test">
        <meta-info>
            <author>Redstream Development Team</author>
            <creationdate>2011-04-24</creationdate>
            <status>DRAFT</status>
        </meta-info>
 
        <description>Tests Testcase001</description>
 
        <actions>
            <send with="invoiceFileSender">
                <message>
                    <resource file="classpath:data/testcase001.txt"/>
                </message>
            </send>
            <receive with="orderRequestReceiver">
 
                <message schema-validation="true">
                    <validate path="//ns1:post-invoice/ns1:CompanyCode" value="1"/>
                    <validate path="string:count(//ns1:post-invoice/ns1:InvoiceLine/ns1:DocID)" value="3"/>
                </message>
                <header>
                    <element name="rs_address" value="order-purchase-invoice-queue" />
                </header>
                <extract>
                    <message path="count(//ns1:post-invoice/ns1:InvoiceLine/ns1:DocID)" variable="${nrOfInvoiceLines}"/>
                </extract>
            </receive>
 
            <echo>
                <message>${nrOfInvoiceLines}</message>
            </echo>
            <send with="orderResponseSender">
                <message>
                    <resource file="classpath:data/response-testcase001.xml"/>
                </message>
            </send>
        </actions>
    </testcase>
</spring:beans>

The first action that is done is sending a file to my Mule ESB. The next step is that I wait for the response from my ESB. When I received that I check the contents of XML message at some points and check if it is valid against the schema.
Then after echoing the number of invoice lines I have Citrus return the HTTP request with a fixed XML response so the Mule ESB ends this action successfully.
That completes this example of how to use Citrus to test your ESB implemention. I hope it is more clear now how you can use Citrus for your (automated) integration tests with this real life example.

Recently, I ran into an open-source test framework called Citrus. Citrus supports you in testing message interfaces in enterprise applications. Manual testing effort as well as coding mocks and simulators are not necessary. Instead Citrus enables integration testing in an automated way with out-of-the-box simulation of various message transports. We’ll use it to test our Mule based ESB.

Mule, of course, offers great possibility to unit test your application. And we also have a test setup which ‘talks’ to other applications. What we didn’t have was a testing environment which we could use to test the ESB as a blackbox without being dependent on other (external) applications. And this is exactly where Citrus comes in. Citrus makes it possible to test the complete lifecycle of a message flow without being dependent of other systems, actually with Citrus you proxy these dependencies.
In this post I will provide details and tips on how to setup and use Citrus. Although the documentation that is available is easy to read, it is not complete. It took me quite some effort to get it all running but like I said before the benefits of this framework are huge.

In the reference guide of Citrus there is a chapter about how to use Citrus with Maven. I use that guide as base and add some info that was missing in my case but is essential to get things working. I use the 1.2-SNAPSHOT edition of Citrus.

I took the following steps to get it running:

1. Add repositories to your settings.xml

To have access to the Citrus jars you need to tell Maven where to get them. You can do this by adding the following repositories to your settings.xml (or even better to Artifactory or similar repository manager):

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

<repositories> [...] <repository> <id>consol-labs-release</id> <url>http://labs.consol.de/maven/repository/</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </repository> <repository> <id>consol-labs-snapshots</id> <url>http://labs.consol.de/maven/snapshots-repository/</url> <snapshots> <enabled>true</enabled> <!-- Policy: always, daily, interval:xxx (xxx=#minutes, 60*24*7=10080), never --> <updatePolicy>10080</updatePolicy> </snapshots> <releases> <enabled>false</enabled> </releases> </repository> [...] </repositories>

2. Add necessary dependencies to your project’s pom

Add the following dependencies to the pom of your project (at least the citrus-core, the others are depending on the tests you want to perform).

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

<dependency> <groupId>com.consol.citrus</groupId> <artifactId>citrus-core</artifactId> <version>1.2-SNAPSHOT</version> <scope>test</scope> </dependency> <dependency> <groupId>com.consol.citrus</groupId> <artifactId>citrus-http</artifactId> <version>1.2-SNAPSHOT</version> <scope>test</scope> </dependency> <dependency> <groupId>com.consol.citrus</groupId> <artifactId>citrus-adapter</artifactId> <version>1.2-SNAPSHOT</version> <scope>test</scope> </dependency>

3. Add necessary plugins to your project’s pom

To generate and execute the Citrus test cases you need to add the Citrus plugins (and extra source path) to your project. This is done by adding the following to your project’s pom:

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

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>2.0.2</version> <configuration> <source>1.5</source> <target>1.5</target> <encoding>${project.build.sourceEncoding}</encoding> </configuration> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-resources-plugin</artifactId> <version>2.2</version> <configuration> <encoding>${project.build.sourceEncoding}</encoding> </configuration> </plugin> <plugin> <groupId>com.consol.citrus.mvn</groupId> <artifactId>citrus-maven-plugin</artifactId> <version>1.1</version> <configuration> <author>Redstream Team</author> <targetPackage>nl.redstream.test</targetPackage> </configuration> </plugin> <plugin> <artifactId>maven-surefire-plugin</artifactId> <configuration> <skip>true</skip> </configuration> <executions> <execution> <id>citrus-tests</id> <phase>integration-test</phase> <goals> <goal>test</goal> </goals> <configuration> <skip>false</skip> </configuration> </execution> </executions> </plugin> </plugins>   <testSourceDirectory>src/citrus/java</testSourceDirectory> <testResources> <testResource> <directory>src/citrus/java</directory> <includes> <include>**</include> </includes> <excludes> <exclude>*.java</exclude> </excludes> </testResource> <testResource> <directory>src/citrus/tests</directory> <includes> <include>**/*</include> </includes> <excludes> </excludes> </testResource> <testResource> <directory>src/citrus/resources</directory> <includes> <include>**/*</include> </includes> <excludes> </excludes> </testResource> </testResources> </build>

4. Create a Citrus Test Case

Next step is to use the Maven plugin to create a new Test Case. Run the command

mvn citrus:create-test

and answer the questions.
Note 1: the name of the testcase is going to be the Java class name so only use the valid characters for a Java class name
Note 2: Make sure the name of the testcase ends with ‘Test’ otherwise the test isn’t found when trying to run it (at least in case you generate a JUnit4 type of test).

5. Add a ‘citrus-context.xml’ to the classpath

This isn’t mentioned in the guide but is a mandatory step: you need to have a ‘citrus-context.xml’ file on the classpath for Citrus to run your tests. Here is a snippet from the config file that can be found in the examples that are delivered with Citrus:

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

<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:citrus="http://www.citrusframework.org/schema/config" xmlns:citrus-ws="http://www.citrusframework.org/schema/ws/config" xmlns:citrus-http="http://www.citrusframework.org/schema/http/config" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd http://www.citrusframework.org/schema/config http://www.citrusframework.org/schema/config/citrus-config.xsd">   ... <!-- Message Validators --> <bean id="xmlMessageValidator" class="com.consol.citrus.validation.xml.DomXmlMessageValidator"/>   <bean id="connectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory"> <property name="brokerURL" value="${jms.server.url}" /> </bean>   <bean class="com.consol.citrus.variable.GlobalVariables"> <property name="variables"> <map> <entry key="project.name" value="Citrus Greeting sample"/> </map> </property> </bean>   ...   <!-- TestSuite definition --> <bean name="citrus-samples-greeting" class="com.consol.citrus.TestSuite"/> </beans>

When all this is done you can run your test with the command:

mvn clean integration-test -Dtest=YourTestNameTest

In the next posts I will go into more detail about certain Test Scenarios and how to test these with Citrus.

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