Putting Spring Boot to REST with Swagger (and grab a beer in the process)

This blog post (the first in years) will be part of  a small series in which I’ll explore the world of Spring Boot (micro)services. I’ll start out by building a simple Spring Boot REST service and expose the service API via Swagger – the de facto standard for describing REST apis.

The code being built in the context of this blog post can be found on GitHub.

Hello Beer

Instead of building the obligatory HelloWorld service, I’ve decided to build a HelloBeer service instead, beer being one of the finer pleasures in life imho.

First Project

Let’s get to work! I’ll create the project with IntelliJ using the Spring Initializr and select the Web, JPA and H2 dependencies.

Screenshot from 2018-01-20 20-40-44

Screenshot from 2018-01-20 20-42-19

After clicking through to the finish line, you’ll get a working Spring Boot project with a pom file containing the dependencies you just selected, and the bootstrap class BeerAppApplication.


The model is very simple: a small Beer class and a BeerType enum. I’ll put the JSR 303 annotations @NotNull on the name to demonstrate later on that the Swagger documentation can reflect this (by displaying the name as a required attribute of a Beer).

public class Beer {

    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;
    private String name;
    private BeerType type;
    private String brewery;

    public Long getId() {
        return id;

    public void setId(Long id) {
        this.id = id;

    public String getName() {
        return name;

    public void setName(String name) {
        this.name = name;

    public BeerType getType() {
        return type;

    public void setType(BeerType type) {
        this.type = type;

    public String getBrewery() {
        return brewery;

    public void setBrewery(String brewery) {
        this.brewery = brewery;

public enum BeerType {


Adding a repository is pretty simple. Just extend the JpaRepository interface (the second typed parameter “Long” should correspond with the type of the id) and you get a lot of repository methods for free. For the fun of it, I’ve added an additional method for getting the list of beers based on the beer type.

public interface BeerRepository extends JpaRepository<Beer, Long> {

    List<Beer> findByType(BeerType beerType);

The interface (and the method we’ve added) will be magically implemented by Spring Boot.  And – because we’ve added H2 as a dependency – the beers we save, will be persisted to an H2 memory database (note: every time you restart, the database will be empty again) without writing any additional lines of code or configuration.


Now all we need to get this baby rolling, is a Restful controller. I’ve added a method for POSTing (saving) a beer and one for GETting a list of beers, optionally filtered by the beertype.

public class BeerController {

    private BeerRepository beerRepository;

    @RequestMapping(value = "/beer", method = RequestMethod.POST, produces = "application/json")
    public Beer addToBeerRepository(@RequestBody Beer beer) {

        return beerRepository.save(beer);

    @RequestMapping(value = "/beers", method = RequestMethod.GET, produces = "application/json")
    public List<Beer> getAllBeers(@RequestParam(value = "type", required = false) String beerType) {
        if (beerType == null)
            return beerRepository.findAll();
            return beerRepository.findByType(BeerType.valueOf(beerType));


The code is pretty self-explanatory. Just wire in the repository and you’re ready to persist and retrieve some wonderful beers. The endpoints will be prepended with the path /hello-beer/1.0.


After running the service we can POST a few new beers on the URL /hello-beer/1.0/beer
Screenshot from 2018-01-20 21-53-33

Getting the list of beers filtered by type for example can be done like this: /hello-beer/1.0/beers?type=OTHER
Screenshot from 2018-01-20 21-53-58

Almost to easy, isn’t it? Now let’s try to document the API of our Hello Beer service using Swagger.


To get the most out of our service we’ll be needing the following three dependencies:


The last dependency will interpret the JSR 303 annotations and put the in the API accordingly
Last piece of the puzzle is some configuration that needs to be added:

public class SwaggerConfig {
    public Docket api() {

        return new Docket(DocumentationType.SWAGGER_2)

    UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder().build();


Noteworthy is the @Import line that’s needed for the JSR 303 implications to be transferred to the Swagger documentation.

Also take note of the RequestHandlerSelectors filter. I could have picked the RequestHandlerSelectors.any() filter, but if I did that, the error-controller would have ended up in my API adding some weird models in the process. This way I’ll keep my API nice and clean, just focussing on the beers.
Spinning up the application again, you can check the API on the url /swagger-ui.html:
Screenshot from 2018-01-20 22-11-04

As you can see by the red asterisk after the Beer.name property, the JSR 303 annotation is being picked up nicely by the swagger bean validator plugin.

By tweaking the configuration some more, you can probably get the Swagger API to look just the way you like it (for one we could change the title into something more meaningful than just Api Documentation by chaining the apiInfo method to the build method of the Docket).


In this post we’ve seen how easy it is to get a small Spring Boot REST service up and running and generate and expose the corresponding Swagger API documentation. The next blog post will see me exploring the world of contract first development.

I’ll then start by documenting the Swagger API and try to generate the necessary service interface code and only then start building the actual implementation.



Grails Web Services

In this blog we’ll expose a Grails service as a SOAP service. According to good practice we’ll build the WSDL first and then write the implementation code.
First things first. Let’s create a new grails application and call it grails-soap

grails&gt; create-app grails-soap



For SOAP support we’ll be using the Grails CXF plugin. Just add the following line in the plugin section of your BuildConfig.groovy file to enable the plugin. Documentation for the plugin can be found here.

compile ':cxf:1.1.1'



We’ll start with building the WSDL for the service. The service will be called DepartmentService and will return some Department data for a given id. We’ll place the WSDL in the src/java folder.

&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;wsdl:definitions name=&quot;DepartmentService&quot;
	targetNamespace=&quot;http://devjournal/DepartmentService&quot; xmlns:wsdl=&quot;http://schemas.xmlsoap.org/wsdl/&quot;
	xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot; xmlns:soap12=&quot;http://schemas.xmlsoap.org/wsdl/soap12s/&quot;
		&lt;xsd:schema xmlns=&quot;http://www.w3.org/2001/XMLSchema&quot;&gt;
			&lt;import namespace=&quot;http://devjournal/DepartmentService&quot;
				schemaLocation=&quot;DepartmentService.xsd&quot; /&gt;
	&lt;wsdl:message name=&quot;DepartmentServiceRequestMessage&quot;&gt;
		&lt;wsdl:part name=&quot;in&quot; element=&quot;tns:DepartmentServiceRequest&quot; /&gt;
	&lt;wsdl:message name=&quot;DepartmentServiceResponseMessage&quot;&gt;
		&lt;wsdl:part name=&quot;out&quot; element=&quot;tns:DepartmentServiceResponse&quot; /&gt;
	&lt;wsdl:portType name=&quot;GetDepartmentById&quot;&gt;
		&lt;wsdl:operation name=&quot;getDepartmentById&quot;&gt;
			&lt;wsdl:input message=&quot;tns:DepartmentServiceRequestMessage&quot; /&gt;
			&lt;wsdl:output message=&quot;tns:DepartmentServiceResponseMessage&quot; /&gt;
	&lt;wsdl:binding name=&quot;GetDepartmentByIdSoap12&quot; type=&quot;tns:GetDepartmentById&quot;&gt;
		&lt;soap12:binding transport=&quot;http://schemas.xmlsoap.org/soap/http&quot;
			style=&quot;document&quot; /&gt;
		&lt;wsdl:operation name=&quot;getDepartmentById&quot;&gt;
				style=&quot;document&quot; /&gt;
				&lt;soap12:body use=&quot;literal&quot; parts=&quot;in&quot; /&gt;
				&lt;soap12:body use=&quot;literal&quot; parts=&quot;out&quot; /&gt;
	&lt;wsdl:service name=&quot;DepartmentService&quot;&gt;
		&lt;wsdl:port binding=&quot;tns:GetDepartmentByIdSoap12&quot; name=&quot;GetDepartmentByIdSoap12&quot;&gt;
			&lt;soap12:address location=&quot;http://www.example.org/&quot; /&gt;

The underlying xml schema file contains the response element. This file will also be placed in the src/java folder.

&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;schema attributeFormDefault=&quot;unqualified&quot; elementFormDefault=&quot;qualified&quot;
 &lt;element name=&quot;DepartmentServiceRequest&quot;&gt;
    &lt;element name=&quot;Id&quot; type=&quot;int&quot;/&gt;
 &lt;element name=&quot;DepartmentServiceResponse&quot;&gt;
    &lt;element name=&quot;Department&quot; type=&quot;tns:departmentType&quot; maxOccurs=&quot;1&quot;
 &lt;complexType name=&quot;departmentType&quot;&gt;
   &lt;element name=&quot;Id&quot; type=&quot;int&quot;/&gt;
   &lt;element name=&quot;Name&quot; type=&quot;string&quot;/&gt;
   &lt;element name=&quot;Location&quot; type=&quot;string&quot;/&gt;



Now that we have the WSDL it’s time to generate the Java stubs. Although the CXF plug-in comes with a wsdl-to-java command it kept giving me a “GroovyCastException” when I tried to run it. To workaround this problem, I downloaded the latest apache-cxf distribution here (2.7.11 at the time of this writing) and used its wsdl2java command to generate the stubs.

$ $CXF_HOME/apache-cxf-2.7.11/bin/wsdl2java DepartmentService.wsdl

After running this command from within the /src/java directory, the following stub classes are added to your grails application:

wsdl2java classes
wsdl2java classes



Now everything is in place, we can start implementing the service. First create a new grails service component called DepartmentService

grails&gt; create-service department

We’ll have this service implement the generated @WebService interface GetDepartmentById and override the getDepartmentById method (corresponding with the SOAP operation of the same name) For simplicity sake, we’ll just hardcode a response:

package grails.soap

import javax.jws.WebService

import org.grails.cxf.utils.EndpointType

import devjournal.departmentservice.DepartmentServiceRequest
import devjournal.departmentservice.DepartmentServiceResponse
import devjournal.departmentservice.DepartmentType
import devjournal.departmentservice.GetDepartmentById

@WebService(targetNamespace = &quot;http://devjournal/DepartmentService&quot;, name = &quot;GetDepartmentById&quot;, serviceName = 'DepartmentService',
portName = 'GetDepartmentById')
class DepartmentService implements GetDepartmentById {

	static expose = EndpointType.JAX_WS_WSDL
	static soap12 = true
	static address = 'DepartmentService'
	def serviceMethod() {

	public DepartmentServiceResponse getDepartmentById(
			DepartmentServiceRequest departmentServiceRequest) {

		DepartmentType department = new DepartmentType(id: departmentServiceRequest.id, location:'Amsterdam', name: 'Sales')
		return new DepartmentServiceResponse(department:department)

As you can see in the code above, we’ve implemented the GetDepartmentById interface and added the @WebService annotation to the service. With the serviceName and portName attributes we can influence the WSDL that’s eventually being served.
The cxf-plugin allows further configuration by means of static properties. Setting the soap12 property to “true” makes the DepartmentService adhere to the SOAP 1.2 specification. With the address property we can adjust the endpoint of the service. By default it would be the default address of the grails service, i.e. “/services/department”. In the above example the endpoint will be “/services/DepartmentService”. Refer to the cxf-plugin documentation for an overview of available properties.

Testing the web service

Now let’s fire up the application and give it a spin

grails&gt; run-app

The WSDL should be available at http://localhost:8080/services/DepartmentService?WSDL and can be tested with SoapUI. The screenshot below shows the result.

DepartmentService Test
DepartmentService Test



In this blog I’ve shown how easy it is to expose a grails service via SOAP. Although the service had been turned into a SOAP service it’s still available as a normal grail service to the rest of the application, so there’s no violation of the DRY principle and code can be reused.

Grails in the Cloud Foundry

In this blog I’ll show you how easy it is to get a small Grails app up and running on Cloud Foundry making use of a mysql service provided by Cloud Foundry. We’ll be using the Groovy & Grails Toolsuite (ggts) for this, but I’ll also show you the grails commands you can use to accomplish each individual step.


  • At the time of this blogpost I’m using ggts version 3.1.0.RELEASE based on Eclipse Juno 4.2.1, which can be downloaded right here;
  • ggts comes with a full Grails installation. To make use of command line grails commands outside of the IDE, set the following environment variables. If you’re an Ubuntu user like me, just add these two lines to your ~/.bashrc file:
    • export GRAILS_HOME=<ggts_home>/grails-2.1.1;
    • export PATH=$PATH:$GRAILS_HOME/bin;
  • Apply for a Cloud Foundry account right here. You’ll receive an email of approval which will contain your  password;
  • Enable Cloud Foundry Integration in ggts. Click the Extensions link on the Dashboard, scroll down to Cloud Foundry Integration for Eclipse and install it.
Screenshot from 2013-02-17 15:40:52
Cloud Foundry Integration for Eclipse

Building a simple Grails app

We’re gonna develop a very simple Grails app. Just enough for demonstration purposes. It’ll be an app that enables you to create notes and store them in a database. We’ll call it one-note.

Grails Project

Choose File > New > Grails Project and supply the project-name. Alternatively you could use the command line and type:

grails create-app one-note

There’s also a command line interface available in ggts itself (Navigate > Open Grails Command Prompt). All commands are available here (just ommit the grails prefix), except for the creation of an application.

Screenshot from 2013-02-24 16:54:11
Grails Command Prompt

Domain Class

Choose File > New > Domain Class and name it Note. The Note.groovy domain class will be created for you. You can also create the class via this command line:

grails create-domain-class note

Add two simple fields to the domain class, so it looks like this:

package one.note

class Note {

    String content
    Date dateCreated

    static constraints = {

The dateCreated is a standard field which will be supplied for by the Grails framework, the content field will contain the actual note.


Choose File > New > Controller and name it NoteController. The NoteController.groovy controller will be created for you. The equivalent command would be

grails create-controller note

Add scaffolding and reroute the index action to the list action. Your controller should now look like this

package one.note

class NoteController {

    def scaffold = true

    def index() {

Testdrive the application

That’s basically all we need to run the application locally and make use of an in-memory hsqldb. Select Run > Run As > Grails Command (run-app), and point your browser to http://localhost:8080/one-note and you’re good to go. Select the NoteController in the Overview page, create some notes and your application should resemble the picture below.

Screenshot from 2013-02-24 18:05:49
one-note Grails application

Alternatively you could achieve the same via the command line:

grails run-app

Publish to Cloud Foundry

Although not entirely necessary, it’s a good practice to change your production configuration in the Datasource.groovy file. Add the following lines

environments {
    production {
        dataSource {
            dbCreate = &quot;update&quot;
            driverClassName = &quot;com.mysql.jdbc.Driver&quot;

Furthermore edit the BuildConfig.groovy and add the following dependency:

dependencies {
runtime &quot;mysql:mysql-connector-java:5.1.23&quot;

Cloud Foundry Integration style

Add a new server (File > New > Other > Server) and select Cloud Foundry as the type.

Screenshot from 2013-02-24 18:33:21
New Server > Define a New Server

Fill in your Cloud Foundry account information and press Validate Account to make sure you entered everything correctly.

Screenshot from 2013-02-24 18:33:35
New Server > Cloud Foundry Account

Now go to the Applications tab and Add the one-note application from Available to Configured and click Finish.

Change Runtime to Java 7, click Next >

Screenshot from 2013-02-24 18:38:11
Application > Application Details

Note the Deployed URL and click Next >

Screenshot from 2013-02-24 18:39:22
Application > Launch deployment

Click Add Service to add a mysql service, give it a name (I choose one-note) and select MySQL database as the type and click Finish.

Screenshot from 2013-02-24 18:40:33
Add Service > Service Configuration

Make sure, the new mysql service is selected and click Finish.

Screenshot from 2013-02-24 19:14:44
Application > Services selection

Now the application will get started and you’ll get a nice overview of your application running in Cloud Foundry.

Screenshot from 2013-02-24 18:49:41
Application overview

Also take note of the Remote Systems window in ggts. Here you can for one take a look at all the log files in your Cloud Foundry environment.

Screenshot from 2013-02-24 13:17:11
Remote Systems

That’s it. You can now test your application on the following url: http://one-note.cloudfoundry.com.

Screenshot from 2013-02-24 19:00:21
one-note in the cloud

Command line style

To enable Cloud Foundry commands via the command line you have to add a plugin to the application:

grails install-plugin cloud-foundry

Next add the following two lines to the ~/.grails/settings.groovy file:
grails.plugin.cloudfoundry.username = “yourusername”
grails.plugin.cloudfoundry.password = “yourpassword”

Now you can push the one-note application to Cloud Foundry:

grails prod cf-push

Accept the default url and  choose y at “Would you like to create and bind a mysql service” and n at the same question for a postgresql service.

While building the war for deployment, you might see and Error about a missing migrations directory. This is caused by the database-migration plugin. It’s harmless, but if you want to get rid of it, just add the migrations directory in the grails-app subdirectory of the application.

That’s it. You can test the application via the same url we used before when we used Cloud Foundry Integration: http://one-note.cloudfoundry.com.

There are lots of command available in the plugin. There are for example commands for restarting and deleting a deployed app or service. You can display the list of available commands with:

grails cf-help


In this blogpost we’ve built a simple Grails application and pushed it to Cloud Foundry, making use of a mysql database service. We’ve shown how to do it via the command line as well as via the Groovy/Grails Tool Suite with the Cloud Foundry Integration plugin. Whichever way you prefer, both ways are very powerful very easy to use. I myself often use a hybrid approach. For the creation of components and pushing the application to the cloud, I use the command line approach . And for managing the deployed applications, I make use of the nice overview interface that the Cloud Foundry Integration Plugin provides.


Mule – Building a webservice proxy

In this blogpost we’ll develop a simple webservice proxy using the latest Mule Studio Community Edition (currently version 1.3.1 which uses Mule ESB v.3.3), which can be downloaded here. The proxy will do some basic routing. No transformation will be done. That area will be explored in a future blogpost.

webservice proxy
mule proxy service

The webservice which will be used for proxying is a simple jax-ws webservice for retrieving employee data based on their department id. The webservice will be exposed via the following url: http://localhost:8083/HR/hrManagerService?wsdl. See this blogpost for building a simple jax-ws webservice on your own.

Creating a new Mule project

First we’ll create a new Mule project based on Maven. This can be done in 3 simple steps. First select File > New > Mule Project. Give the project a Name and a Description and click Next >.

Screenshot from 2013-01-03 12:35:35
New Mule Project – Step 1 of 3

Now, create a flow for the project. Give it a Name, File name and a Description and click Next >.

Screenshot from 2013-01-03 12:35:55
New Mule Project – Step 2 of 3

Finally select the option for creating the Maven pom.xml file and fill in a Group Id and Artifact Id and click Finish.

Screenshot from 2013-01-03 12:39:13
New Mule Project – Step 3 of 3

That’s all. We’ve created the skeleton for our web service proxy and are now ready to implement the flow.

Building the flow

Open the mule-proxy.mflow file and drag a Flow Scope into it. Give it an appropriate name, like MuleProxyFlow.


Now let’s build the flow for the proxy service back to front. We’ll begin with adding a HTTP Endpoint to the flow which will resemble the webservice we’re gonna proxy. Right click the Endpoint and select Convert to an outbound endpoint. Next select Properties, clear the Host and Port values and fill in the endpoint of the webservice in the Address field.

Screenshot from 2013-01-03 14:34:20
HTTP Outbound Endpoint Properties – General
Screenshot from 2013-01-03 14:41:01
HTTP Outbound Endpoint Properties – Advanced

Next, we’ll create a client for the web service. Select a SOAP Component and drag it to the left of the HTTP Endpoint. Change the Operation field to Proxy client.

Screenshot from 2013-01-03 14:54:31
SOAP Component – Proxy client

Now for the actual proxy service. Select another SOAP Component and drag it to the left of the Proxy client SOAP Component. Change the Operation to Proxy service. Fill in the Namespace and Service as well. They have to match the targetNamespace and name of the webservice as defined in the wsdl we’re gonna use for the proxy. Make sure that the Payload of the Proxy service and Proxy client match (in this example I choose to only exchange the SOAP body).

Screenshot from 2013-01-03 15:12:52
SOAP Component – Proxy service – General

In the Advanced section we’ll fill in the WSDL Location of the actual wsdl, which will serve as the wsdl for the proxy service. In this simple example, the wsdl of the proxy will match the wsdl of the actual webservice. I’ve raken the liberty to copy the wsdl and xsd files to the src/main/resources/wsdl and src/main/resources/xsd directories of the project. But for the sake of simplicity, you could also pick up the wsdl from it’s actual location, i.e. http://localhost:8083/HR/hrManagerService?wsdl and use that as the WSDL Location in the case of this example.

Screenshot from 2013-01-03 17:57:42
SOAP Component – Proxy service – Advanced

Finally, we’ll need to add the HTTP inbound endpoint. Again, clear the Host and Port fields and add the Address you’d like to use for the proxy, in this example it will be http://localhost:8081/hrManagerServiceProxy.

Screenshot from 2013-01-03 15:27:38
HTTP Inbound Endpoint Properties – General
Screenshot from 2013-01-03 15:27:50
HTTP Inbound Endpoint Properties – Advanced

That’s it. If you followed these steps correctly, your flow should resemble the flow below.


The xml configuration (src/main/app/mule-proxy.xml) should look like the code below.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:cxf="http://www.mulesoft.org/schema/mule/cxf" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" version="CE-3.3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/cxf http://www.mulesoft.org/schema/mule/cxf/current/mule-cxf.xsd
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd ">
  <flow name="MuleProxyFlow" doc:name="MuleProxyFlow">
    <http:inbound-endpoint exchange-pattern="request-response" address="http://localhost:8081/hrManagerServiceProxy" doc:name="HTTP"/>
    <cxf:proxy-service namespace="http://service.hrmanager.hr.whitehorses.nl/" service="HRManagerServiceImplService" payload="body" doc:name="SOAP" enableMuleSoapHeaders="false" wsdlLocation="wsdl/hrManagerService.wsdl"/>
    <cxf:proxy-client doc:name="SOAP" payload="body"/>
    <http:outbound-endpoint exchange-pattern="request-response" address="http://localhost:8083/HR/hrManagerService" doc:name="HTTP"/>

Testing the proxy

Mule Studio

Now, let’s run the Mule proxy. You can do this directly inside Mule Studio by choosing Run As > Mule Application.


You can also use maven via the command line:

mvn clean install

There’s a small issue with the generated pom.xml file in this version of the Community Edition. If you use it as is, you’ll get an error concerning missing dependencies. To fix this, open the pom.xml file and search for the following snippet:

<!-- Xml configuration -->

Replace it with this one:

<!-- Xml configuration -->

Also you need to have a mule server running for this to work. See this blogpost for details. The install goal will deploy the mule project to the $MULE_HOME/apps directory of the mule server installation and if the server is running, it wil startup the project automatically.


Regardless of the way you’re running the mule project, be it via Maven or via Mule Studio, you should be able to test the proxy now with soapUI. Create a New Project, point it to the wsdl of the proxy, i,e. http://localhost:8081/hrManagerServieProxy?wsdl, and add a default TestSuite. Now you can run a TestCase against the proxy and it should yield the same result as it would when you’d call the webservice behind it directly.

Screenshot from 2013-01-03 21:26:50
soapUI – Testing the proxy


In this blogpost we’ve created a simple webservice proxy which does some basic routing without any kind of transformation. In the next post we’ll add some transformation and basic logging to the mix.

Getting started with Mule

I intend to write a few blogs about Mule, probably the most-used open source Enterprise Service Bus out there. This blog will cover the basics to get Mule up and running.

Installing Mule

Installation of Mule is pretty straightforward:

  • Download the latest Mule ESB Community Edition here;
  • Extract the downloaded archive to a directory of your choice;
  • If you plan to use Maven, set the MULE_HOME environment variable, eg. in your .bashrc file for Ubuntu:
    export MULE_HOME=~/Applications/mule-standalone-3.1.2
  • You can now run the server via the following command (on Ubuntu):

Hello World!

To build a simple Hello World example directly in Eclipse follow this tutorial on the Mule website. It also shows you how to install and use the mule plugin for eclipse.

Using Maven

If you’re like me and like to use Maven, there’s a maven plugin available to quickly create a basic mule standalone project.
The basic command for creating a mule project with the plugin is

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

To quickly setup a basic project check out this site. If you follow the example a simple maven project is created.
You can “eclipsify” this project via the following maven command:

mvn eclipse:eclipse

Now, you can import the project in Eclipse.

The generated project

The generated project contains a simple mule configuration:

  &lt;flow name=&quot;main&quot;&gt;
        &lt;vm:inbound-endpoint path=&quot;in&quot; exchange-pattern=&quot;request-response&quot;/&gt;
        &lt;vm:outbound-endpoint path=&quot;out&quot;/&gt;

As you can see, the example is very simple. It contains two in-memory queues. You can send some text in the vm://in queue and it gets echoed out into the vm://out queue.

Fixing the testcase

Before you can run the example, there’s an error in the generated test case, that needs to be solved first (or you can skip the test when running maven of course).
The configuration for the test case, called artifactId-functional-test-config.xml is similar to the main configuration:

    &lt;flow name=&quot;main&quot;&gt;
        &lt;vm:inbound-endpoint path=&quot;in&quot; exchange-pattern=&quot;request-response&quot;/&gt;
        &lt;test:component appendString=&quot; Received&quot;/&gt;
        &lt;vm:outbound-endpoint path=&quot;out&quot;/&gt;

As an extra bonus it appends ” Received” to the input string before it is sent to the vm://out queue.
The unit test contains the following code:

    public void testHelloMule() throws Exception
        MuleClient client = new MuleClient(muleContext);
        MuleMessage result = client.send(&quot;vm://in&quot;, &quot;some data&quot;, null);
        assertFalse(result.getPayload() instanceof NullPayload);
        assertEquals(&quot;some data Received&quot;, result.getPayloadAsString());

If you run the test goal, this test case will fail on line 7. The problem is that the input string is sent to the vm://out queue, hence the synchronous result is an empty mule message. To fix this, you can either change the configuration, so that the input is not passed to the vm://out queue, like this:

    &lt;flow name=&quot;main&quot;&gt;
        &lt;vm:inbound-endpoint path=&quot;in&quot; exchange-pattern=&quot;request-response&quot;/&gt;
        &lt;test:component appendString=&quot; Received&quot;/&gt;

The other option is to adjust the test case, so that the result is read from the vm://out queue:

    public void testHelloMule() throws Exception
        MuleClient client = new MuleClient(muleContext);
        client.send(&quot;vm://in&quot;, &quot;some data&quot;, null);
        MuleMessage result = client.request(&quot;vm://out&quot;, 5000);
        assertFalse(result.getPayload() instanceof NullPayload);
        assertEquals(&quot;some data Received&quot;, result.getPayloadAsString());

Installing the mule project

After you fixed the bug in the testcase, you can install the application.

mvn clean install

This will package the project into a zip file and copy this file to the $MULE_HOME/apps directory. Here Mule will pick it up and deploy the file.

For now it doesn’t do much besides creating the 2 in-memory queues. In the next blog, I’ll dive a little deeper into Mule and show some basic configurations.


As a small reference, there’s a DZone refcard available containing an overview of Mule 3 commands.

Developing a contract-first JAX-WS webservice

In this blog i’ll develop a simple webservice using JAX-WS. I’ll first start with the contract (wsdl and xsd’s). The contract will be used for generating the necessary JAXB artifacts. Getting the webservice up and running will be a piece of cake after that all thanks to Maven and JAX-WS.
First things first, let’s create a new Maven project. I’m using Netbeans as IDE for this.

New Maven Web Application

First Create a new Maven Web Application

and call it hello_person for example

The Contract

The webservice will accept a Person graph with a first and last name and will return a concatenated “Hello first name last name!”. Not very original but good enough for the example.
First we’ll define the xsd called helloPersonService.xsd for the request and response. The request will contain a Person object with a first and last name, the response will contain a Greetings string. We’ll store it in src/main/resources/xsd.

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    <xsd:element name="HelloPersonServiceRequest" type="HelloPersonServiceRequestType"/>
    <xsd:element name="HelloPersonServiceResponse" type="HelloPersonServiceResponseType"/>

    <xsd:complexType name="HelloPersonServiceRequestType">
        <xsd:element name="Person" type="PersonType"/>
    <xsd:complexType name="HelloPersonServiceResponseType">
        <xsd:element name="Greetings" type="xsd:string"/>

    <xsd:complexType name="PersonType">
            <xsd:element name="FirstName" type="xsd:string"/>
            <xsd:element name="LastName" type="xsd:string"/>

Now we’ll define a wsdl called helloPersonService.wsdl and we’ll store it in src/main/resources/wsdl

<?xml version="1.0" encoding="UTF-8"?>
        <xsd:schema targetNamespace="http://example.nl/hellopersonservice/1.0">
            <xsd:import schemaLocation="../xsd/helloPersonService.xsd"
    <wsdl:message name="HelloPersonServiceRequest">
        <wsdl:part name="HelloPersonServiceRequest" element="tns:HelloPersonServiceRequest"/>
    <wsdl:message name="HelloPersonServiceResponse">
        <wsdl:part name="HelloPersonServiceResponse" element="tns:HelloPersonServiceResponse"/>
    <wsdl:portType name="HelloPersonServicePortType">
        <wsdl:operation name="greetPerson">
            <wsdl:input name="HelloPersonServiceRequest" message="tns:HelloPersonServiceRequest"/>
            <wsdl:output name="HelloPersonServiceResponse" message="tns:HelloPersonServiceResponse"/>
    <wsdl:binding name="HelloPersonServiceBinding" type="tns:HelloPersonServicePortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="greetPerson">
            <soap:operation style="document" soapAction="http://example.nl/HelloPersonService/greetPerson"/>
            <wsdl:input name="HelloPersonServiceRequest">
                <soap:body use="literal"/>
            <wsdl:output name="HelloPersonServiceResponse">
                <soap:body use="literal"/>
    <wsdl:service name="HelloPersonService">
        <wsdl:port name="HelloPersonServicePort" binding="tns:HelloPersonServiceBinding">
            <soap:address location="/service/helloPersonService" />

Getting the pom right

Next up is adding the necessary component to the pom file. We need the jax-ws runtime libraries, the jetty plugin as we use jetty as the servlet container, and the jaxws-maven-plugin for generating the java code from the contract. I’ve highlighted these dependencies in the pom file below.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <name>hello_person Java EE 6 Webapp</name>
            <name>Repository hosting the jee6 artifacts</name>
            <name>Repository hosting the jee6 artifacts</name>





                        <connector implementation="org.eclipse.jetty.nio.SelectChannelConnector">



Writing the implementation

First, let’s do a Clean and Build in NetBeans. This will generate the JAXB/JAX-WS artifacts from the contract.
Notice that the jaxws-maven-plugin has generated an interface called nl.example.hello_person.service.generated.HelloPersonServicePortType for the PortType in the wsdl. This is the interface we have to implement. The code for the implementation is pretty straightforward. I’ve added it below for convenience. Notice that the implementation class is called nl.example.hello_person.service.HelloPersonServiceImpl. We’ll need this in one of the next steps. Also notice the necessary @WebService annotation. The endpointInterface atribute points of course to the generated interface.

package nl.example.hello_person.service;

import javax.jws.WebService;
import nl.example.hello_person.service.generated.HelloPersonServiceRequestType;
import nl.example.hello_person.service.generated.HelloPersonServiceResponseType;

public class HelloPersonServiceImpl implements nl.example.hello_person.service.generated.HelloPersonServicePortType {

    public HelloPersonServiceResponseType greetPerson(HelloPersonServiceRequestType helloPersonServiceRequest) {
        HelloPersonServiceResponseType helloPersonServiceResponse = new HelloPersonServiceResponseType();
        helloPersonServiceResponse.setGreetings("Hello " + helloPersonServiceRequest.getPerson().getFirstName() + " " + helloPersonServiceRequest.getPerson().getLastName() + "!");
        return helloPersonServiceResponse;


The web.xml file

Now, add a web.xml file to the project (you can do this via New File > Web > Standard Deployment Descriptor (web.xml)) and add the proper configuration for the jax-ws servlet to it:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
        <description>JAX-WS endpoint</description>
        <display-name>The JAX-WS servlet</display-name>

The sun-jaxws.xml file

The last step is adding the sun-jaxws.xml file to the WEB-INF directory of the project. This is the content of the file:

<?xml version="1.0" encoding="UTF-8"?>
        url-pattern='/helloPersonService' />

Notice that the implementation attribute is pointing to our implementation class.

Running the service

Add jetty:run as custom action (via Run > Set Project Configuration > Customize > Actions) and run it.
Now open a browser and check the following url http://localhost:8083/hello_person/helloPersonService. If you see the following screen, the webservice is up and running!

Testing the service

For testing I’m using the soapUI plugin for Netbeans.
After you’ve installed the plugin, you can create a new Web Service Testing Project (New Project > SOA > Web Service Testing Project)

Point the initial WSDL property to the url you’ve seen on the Web Services page: http://localhost:8083/hello_person/helloPersonService?wsdl.

The testsuite now contains a greetPerson Test Step. You can now test if the service works. If all goes well, you should see something similar to the picture below.

Cloning a VirtualBox openSUSE image

I recently tried to clone an openSUSE VirtualBox image. I thought it would be as simple as just copying the virtual disk image (vdi) file and create a new virtual machine based on it. So that’s what i did. But when i tried to couple the new hard disk file to the virtual machine VirtualBox gave me the following error:

Apparently a new virtual disk image in VirtualBox needs a unique identifier key. So after some research i found out it’s possible to make a clone of a hard disk that has a different unique identifier. But unfortunately that’s not all of the story. You have to make some additional changes to the clone to make it all work. So here are the steps you need to follow to make a successful clone.

1. Clone the hard disk

To clone the hard disk open a terminal window and issue the following command:

VBoxManage clonevdi <original>.vdi <clone>.vdi

2. Create a new Virtual Machine

Now create a new virtual machine with basically the same settings as the original virtual machine and couple it to the new cloned virtual disk image. As this image has been given a new unique identifier, you should have no problem registering it now.

3. Alter the hard disk identifiers

Having cloned the virtual disk image, i thought i was ready to roll. But on startup i encountered the following problem:

Apparently part of the UUID of the virtual disk image is used to identify the hard disk on startup. We have to change these references to their appropriate new ids.

3a. Startup in rescue mode

To startup the openSUSE vm in rescue mode insert the iso file you used for installation in the CD Drive of the vm. Upon startup select the Rescue System option from the menu.

3b. Mount the hard disk

Login as root and mount the hard disk (on my system this was /dev/sda2, this could be different on your system) via the following command:

mount /dev/sda2 /mnt

3c. Alter the identifiers

Now first find out what the new identifier of the hard disks should be. Issue the following command

hdparm -i /dev/sda

Note the identifier called SerialNo. This is the one you need. On my system it was VBa79c17fb-f28bb7c1.
Now there are 2 files you need to alter. First edit the file /mnt/etc/fstab and alter all the identifiers between /dev/disk/by-id/ata-VBOX_HARDDISK_ and -partx with the new identifier.
Next make corresponding changes to the file /mnt/boot/grub/menu.lst.
After this you can reboot the system

shutdown now -r

4. Repair your network settings

If you made no typos, openSUSE should start up with no problems. There’s one piece of configuration to do though. The clone has messed up the network configuration. This can be easily repaired via the YaST GUI tool. Open it and select Network Devices > Network Settings. You should see 2 Ethernet Controllers. One of them is not configured. Configure this controller with default settings and delete the other one. Now your clone is ready for use.