Contract first SOAP CXF webservice in Mule

Hello Coder,

Ever wondered how to create and publish a SOAP service using an ESB like Mule ? In this tutorial we will learn to create and publish a SOAP service in Mule ESB using a WSDL which is also referred as Contract-First webservice. Before we proceed ahead there are some assumptions made for the reader of this tutorial:

1) You have basic knowledge about SOAP webservices.

2) You have basic knowledge about Mule ESB and what is a flow in Mule.

3) Installed Anypoint studio. I had used Anypoint version 5.0.0 used in this tutorial.

4) Have a WSDL for SOAP webservice which we are going to create and publish.

Lets proceed to a step by step procedure for writing a SOAP webservice in Mule.

Step 1. Create a new Mule project in AnyPoint studio.

Anypoint studio is the tool made by mulesoft specially for designing the Mule flows via drag an drop interface. It is very simple to use because it was built on the top of Eclipse. It provides a list of available Connectors, Transformers, Scopes, Filters, Flow Control and Error Handling components of Mule ESB. Since Anypoint Studio is built on the top of Eclipse hence the flow for creating a project is same as creating it in any Eclipse. If you haven't installed the studio yet then you can download it from here and extract the zip at your favorite location in your system. Start the Anypoint studio by giving any workspace to it. Once its started properly go to File -> New -> Mule Project. See the below snapshot for creating a new project :

Create Mule project in Anypoint

Step 2. Select the Mule runtime version

Now give a project name for your Mule application under "Project Name" box and select the Mule version as 3.6.0 EE. See the snapshot below for reference:

Select Mule runtime

Step 3. Finish creating project

Click the next button at the bottom of the dialog box and finish the flow for creating Mule project. After completion of this step Anypoint studio will create a default Mule project. It will also add a default flow xml in the project with same name as the project name. You can easily change its name if you need to do so. Mule will also add 2 properties file along with the flow xml.

1) mule-app.properties - Mule automatically provides feature to externalize the properties which can be used in any of the Mule flows. You can add any project specific property in this flow and mule will load it using Spring Property Configurer and make them ready for use in the flows.

2) mule-deploy.properties - This is the property file which Mule uses uses to keep deployment information for standalone application which runs on Anypoint studio. We need not to change it because it is automatically updated every time on each run from Anypoint studio.

Anypoint studio provides a drag and drop interface on flow files where we can drag and drop components on the flow pane. Mule will automatically generate the xml code in behind for these dropped components. You can see the generated xml by clicking 'Configuration Xml' tab from the flow pane.

Step 4. Create HTTP endpoint for incoming requests.

Since we are creating a SOAP webservice which will serve client requests and give response back to the caller hence we need an http endpoint in this flow which can listen at some url to client requests.

Mule provides a HTTP connector for incoming requests over HTTP/HTTPS protocols. So, from the right pane search the HTTP component and drop it to the flow pane. Once its dropped on the flow pane you can see that Mule generates 2 HTTP boxes (Blue and Black). The former HTTP box accepts the requests on a particular url and the latter box sends the response back to the caller hence completing the full request-response cycle. See the snapshot below for reference.

HTTP request connector

Now if you click on the "Configuration XML" tab below then you can see XML which gets generated by this connector:

This HTTP listener connector will serve as the entry point to any requests sent by clients. This will act an endpoint who will listen for all the requests on the path specified in the connector. We need to configure this HTTP connector to properly listen for requests at a particular url.

Step 5. Configure HTTP listener component

Now we will configure the connector component by giving the path on which we want our SOAP service to listen. Click on the HTTP component -> At bottom you will see a property box for HTTP component as below

HTTP Connector Properties

Step 6. Add a Connector Configuration

Click on "+" button of the Connector Configuration box. It will open a new window where you need to provide the details of the HTTP endpoint. Here we will give the hostname for our service, the port on which our SOAP server will run and the base path of all the requests. There are many other configurations available for this HTTP connector which are out of scope of this tutorial. See the image below for reference:

HTTP Connector Configuration

Step 7. Set HTTP url

We had configured the HTTP Connector Configuration by providing the hostname, port and base url. Now we need to give the path to our SOAP server. This path is the relative path. In the HTTP properties box, give the path for the HTTP url as specified in the below snapshot.

HTTP request url

At this point we want to see what have been added in flow XML by Anypoint. Here is the xml which is generated by adding and configuring this connector to mule flow:

Step 8. Add CXF connector

Now we need a connector which receive the request in SOAP format which was sent at HTTP endpoint configured above. For HTTP endpoint all the incoming requests are same, it just accepts the request and passes ahead. In our case the request will be a SOAP request hence we need something which can understand this request as a SOAP request.
Mule provides a Apache CXF backed SOAP connector which is able to understand the SOAP request. This CXF connector will automatically invoke the service method according to the incoming request. So, from the right pane search for CXF and drag-drop the SOAP connector near the HTTP connector. Anypoint will automatically join these two connectors in request-response manner. See the image below for reference:

Mule CXF Connector

Step 9. Configure CXF connector

Now we need to configure CXF connector properties to invoke the proper service class on incoming request. Click on the SOAP connector from flow pane and a properties box for SOAP CXF connector will open. Give the operation as JAX-WS service because we are creating a server. Now in inbound attributes we need to provide the Service class and the optional service name for your wsdl. I had referred the sample wsdl from here.

Configure CXF Connector

Download and put this wsdl file or your own wsdl file under src/main/resources folder of your project. Now click on "Generate from WSDL" button. A new window will be opened which will ask for wsdl path and a package name where we want to keep the generated java files. Select the radio button "Use WSDF from a file in the current project" and give the full file path from the src/main/resources folder. Under package name enter a valid package name of your choice. Click OK. See the image below for reference:

Generate JAXB Classes

This step will generate the necessary Java classes and the Service Interface for our service. You can either create a Implementation class for the service interface to provide your service logic for your method or you can keep it as it is and this connector will directly pass the JAXB request to next available component. Here is the xml generated for the cxf connector

Here the serviceclass is the interface generated for this service and wsdllocation (optional) is the location of wsdl for the clients to serve. If wsdllocation is not specified then the wsdl will be generated on the fly using the service interface. The service (value here DoubleIt.svc) is also optional and is used to distinguish among multiple hosted services.

Step 10. Create service implementation

Now create an implementation class for your service interface where we can write custom logic by processing the soap request. In this implementation class we need to provide implementation of all the abstract methods from the service interface. In our example we need to override doubleIt() and return the doubled number as a response from it.

Step 11. Add Component to process request

Now we have our implementation class also so we need to ask Mule to invoke our overridden method to process the request. For this we need to add a Java component in this flow.
Search Java from the search box in Anypoint and drop the Java icon (from the Components tab) just after the CXF connector. Click on this Java component and go to its properties view. Give the fully qualified implementation class name under the Class Name section of this component. Now for incoming SOAP requests the CXF connector will call the corresponding implemented method from this implementation class.

And we have completed the full flow for a SOAP service in Mule.

Step 12. Test the flow

Now its time to test our flow inside Anypoint studio. In the studio right click on project, go to "Run As" then "Mule Application". Anypoint will start Mule internally and Mule will register our flow so that it will listen all the requests on port 8090 as specified on HTTP connector. At this point if you open the mule-deploy.properties you will see our flow file name under the property config.resources. Once the application is properly started you will see the DEPLOYED message as shown in the snapshot below.

Deployment success

Now you can use SOAPUI tool to send the SOAP request at http://localhost:8090/mulesvc/sample/soapws/DoubleIt.svc. You can also start the Mule application in debug mode an put breakpoints on flow components to see the incoming and outgoing message from each component.

Here is the full mule flow xml file by anypoint studio.

Full flow image

Below is the full xml for this flow

And here is the input xml which can be used to test this SOAP webservice:

   
   
      
         2
      
   

Hope this helps.