Developing SOAP web service with Spring Boot and Spring-WS

Udara Wijeratna Java, Microservices, SOA

In the current developer world, we speak very less about SOAP web services. This is due to the REST web services dominance in SOA world. However the need for SOAP services will never be zero.

In this document we will focus on how we can develop SOAP web services using popular Spring Boot framework and Spring-WS. When I searched the internet for tutorials I found this useful tutorial, which explain on how to develop SOAP services. There were some missing items in the tutorial and thought of adding them to have a complete steps tutorial.

Spring-WS mainly focus on document driven web services. Hence Spring-WS facilitate the contract-first SOAP web services development. Let’s see how we can develop a simple contract first web service using the following tool set.

  • Spring Boot 1.5
  • Spring-WS 2.4
  • Maven 3
  • Tomcat application server 7
  • Eclipse IDE

Final out put product would be a deployable war file which exposes a SOAP web service to its clients.

Let’s start the development

Initial Project Setup

  1. Create a maven project in eclipse

File –> New –> Other –> Maven Project –> Select “maven-archetype-webapp” –> Provide the Group Id and Artifact Id and save

  1. Create Build Path

Right click on the project –> Build Path –> Configure Build Path –> Under the “Source” tab remove the unsolved items and add the following folder to build path

  • src/main/java
  • src/test/java
  • src/test/resources

 

Creating the POM

  1. By default we have a POM file under the project structure to insert the dependencies.
  • We are using Spring Boot in our project and for testing we are using the embedded Apache Tomcat server
  • Parent POM of spring boot is used to facilitate the spring dependencies.
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.1.RELEASE</version>
</parent>
  • To facilitate the Spring-WS dependencies following dependency element included in the POM
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web-services</artifactId>
</dependency>
  • To include the testing support on Spring Boot application following dependency for included in the POM
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>
  • To create a runnable jar, which can be run on the built it Tomcat: we will add the following plugin in the build tag
<build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.jvnet.jaxb2.maven2</groupId>
                <artifactId>maven-jaxb2-plugin</artifactId>
                <version>${maven-jaxb2-plugin.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <schemaDirectory>                      ${project.basedir}/src/main/resources/wsdl</schemaDirectory>
                    <schemaIncludes>
                        <include>*.wsdl</include>
                    </schemaIncludes>
                </configuration>
            </plugin>
        </plugins>
</build>

 

  • Full POM files as follows
<?xml version="1.0" encoding="UTF-8"?>
<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/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.codenotfound</groupId>
    <artifactId>spring-ws-helloworld-example</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>spring-ws-helloworld-example</name>
    <description>Spring WS - SOAP Web Service Consumer &amp; Provider WSDL Example</description>
    <url>https://www.codenotfound.com/2016/10/spring-ws-soap-web-service-consumer-provider-wsdl-example.html</url>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.1.RELEASE</version>
    </parent>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>

        <maven-jaxb2-plugin.version>0.13.1</maven-jaxb2-plugin.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web-services</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.jvnet.jaxb2.maven2</groupId>
                <artifactId>maven-jaxb2-plugin</artifactId>
                <version>${maven-jaxb2-plugin.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <schemaDirectory>${project.basedir}/src/main/resources/wsdl</schemaDirectory>
                    <schemaIncludes>
                        <include>*.wsdl</include>
                    </schemaIncludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>
  • Now to ensure all works accordingly, let’s build the application. Locate the directory location where your POM file reside and run the below command
mvn install

 

Creating the Contract (WSDL)

  1. Spring web services supports contract first approach only in web services development. So let’s start the with the WSDL (contract)
  • In a WSDL there are key elements
    • <types>
    • <message>
    • <portType>
    • <binding>
  • In our contract we have the following
    • XSD Schema which has two elements
      • “Person” : Request Object
      • “Greeting” : Response Object
    • Message elements
      • “SayHelloInput” : mapping of the XSD object to the message element
      • “SayHelloOutput” : mapping of the XSD object to the message element
    • PortType element
      • Binding the input/output messages to SOAP function “sayHello”
    • Binding element
      • Define the SOAP action and configuring the SOAP body for input/output
    • Service element
      • Defines the SOAP function and the message formats for the service which we are exposing
    • Detail WSDL as follows
<?xml version="1.0"?>
<wsdl:definitions name="HelloWorld"
    targetNamespace="http://codenotfound.com/services/helloworld"
    xmlns:tns="http://codenotfound.com/services/helloworld" xmlns:types="http://codenotfound.com/types/helloworld"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

    <wsdl:types>
        <xsd:schema targetNamespace="http://codenotfound.com/types/helloworld"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            elementFormDefault="qualified" attributeFormDefault="unqualified"
            version="1.0">

            <xsd:element name="person">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="firstName" type="xsd:string" />
                        <xsd:element name="lastName" type="xsd:string" />
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>

            <xsd:element name="greeting">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="greeting" type="xsd:string" />
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:schema>
    </wsdl:types>

    <wsdl:message name="SayHelloInput">
        <wsdl:part name="person" element="types:person" />
    </wsdl:message>

    <wsdl:message name="SayHelloOutput">
        <wsdl:part name="greeting" element="types:greeting" />
    </wsdl:message>

    <wsdl:portType name="HelloWorld_PortType">
        <wsdl:operation name="sayHello">
            <wsdl:input message="tns:SayHelloInput" />
            <wsdl:output message="tns:SayHelloOutput" />
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="HelloWorld_SoapBinding" type="tns:HelloWorld_PortType">
        <soap:binding style="document"
            transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="sayHello">
            <soap:operation
                soapAction="http://codenotfound.com/services/helloworld/sayHello" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="HelloWorld_Service">
        <wsdl:documentation>Hello World service</wsdl:documentation>
        <wsdl:port name="HelloWorld_Port" binding="tns:HelloWorld_SoapBinding">
            <soap:address
                location="http://localhost:9090/codenotfound/ws/helloworld" />
        </wsdl:port>
    </wsdl:service>

</wsdl:definitions>

 

Java Code Implementation

  1. Now our contract is ready. And we have some element defined which we use in SOAP request / response objects. Using JAXB we can easily generate the Java classes associated with those elements
  • Create a folder under “/src/main/resources/” called “wsdl” and copy the created wsdl file to the new directory created
  • In the POM under <plugins> element we have configured a “maven-jaxb2-plugin” to facilitate this class creation
  • The generated java classes will be located in the “target” directory
  • To generate the those classes run the following command
mvn generate-sources

 

  1. The generated java classes will be in the “target” folder and we need add the folder to build path
  • Locate the following directory “/target/generated-sources/xjc”
  • Right Click on the folder –> Build Path –> Use as Source Folder

 

Now the initial setup is completed for the project. Let’s create the necessary packages and start implementing the code. As I mentioned earlier will continue on the post which was publish in www.codenotfound.com.  You can start with the Java code implementation of the link, which is creating the “SpringWsApplication ” class. Also in the tutorial you can download source code.

 

Generate a “WAR” file to deploy in Tomcat

If you want to generate a “WAR” file which can deploy in tomcat, please follow the below steps:

Change in the SpringBootApplication Class

package com.codenotfound;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.support.SpringBootServletInitializer;

@SpringBootApplication
public class SpringWsApplication extends SpringBootServletInitializer {

  @Override
  protected SpringApplicationBuilder configure(
      SpringApplicationBuilder application) {
    return application.sources(SpringWsApplication.class);
  }

  public static void main(String[] args) throws Exception {
    SpringApplication.run(SpringWsApplication.class, args);
  }
}

 

Changes in the POM.xml

  • Add the below dependencies
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

<!-- marked the embedded servlet container as provided -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-tomcat</artifactId>
  <scope>provided</scope>
</dependency>

 

  • Update the <packaging> element from jar to war
<packaging>war</packaging>

 

  • Rerun the mvn command
mvn clean install

 

Udara Wijeratna

Person who is exploring different technology stacks. Always love to learn and take feedback.

Leave a Reply

Your email address will not be published. Required fields are marked *