Spring Boot – SOAP Webservice Example

Learn to leverage Spring boot’s simplicity to create SOAP webservice quickly. REST and microservices are gaining popularity everyday but still SOAP has its own place in some situations. In this spring boot soap tutorial, we will focus only in the Spring boot related configurations to see how easily we can create our contract first SOAP webservice.

We will build a simple contract first SOAP web service where we will implement Student search functionality with hard coded backend for demo purpose.

Table of Contents

Technology Stack
Project Structure
Create Spring Boot Project
Create SOAP Domain and Generate Java Code
Create SOAP WS Endpoint
Add Configuration Beans
Demo
Summary

Technology Stack

• JDK 1.8, Eclipse, Maven – Development environment
• Spring-boot – Underlying application framework
• wsdl4j – for publishing WSDL for our Service
• SOAP-UI – for testing our service
• JAXB maven plugin – for code generation

Project Structure

The classes and files created for this demo are shown below.

Create Spring Boot Project

Create one spring boot project from SPRING INITIALIZR site with Web Services dependency only. After selecting the dependency and giving the proper maven GAV coordinates, download project in zipped format. Unzip and then import project in eclipse as maven project.

Add Wsdl4j Dependency

Edit pom.xml and add this dependency to your project.

<dependency>
	<groupId>wsdl4j</groupId>
	<artifactId>wsdl4j</artifactId>
</dependency>

Create SOAP Domain and Generate Java Code

As we are following the contract first approach to develop the service, we need to first create the domain (methods and parameters) for our service. For simplicity, we have kept both request and response in same XSD, but in actual enterprise use case, we will have multiple XSDs importing each other to form the final definition.

student.xsd

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="https://www.howtodoinjava.com/xml/school" 
targetNamespace="https://www.howtodoinjava.com/xml/school" elementFormDefault="qualified">

    <xs:element name="StudentDetailsRequest">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="xs:string"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:element name="StudentDetailsResponse">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="Student" type="tns:Student"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:complexType name="Student">
        <xs:sequence>
            <xs:element name="name" type="xs:string"/>
            <xs:element name="standard" type="xs:int"/>
            <xs:element name="address" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>
    
</xs:schema>

Place above file in resources folder of the project.

Add JAXB maven plugin for XSD to Java object generation

We will use jaxb2-maven-plugin to generate the domain classes efficiently. We need to now add the below maven plug in to the plugin section of project’s pom.xml file.

 
<plugin>
	<groupId>org.codehaus.mojo</groupId>
	<artifactId>jaxb2-maven-plugin</artifactId>
	<version>1.6</version>
	<executions>
		<execution>
			<id>xjc</id>
			<goals>
				<goal>xjc</goal>
			</goals>
		</execution>
	</executions>
	<configuration>
		<schemaDirectory>${project.basedir}/src/main/resources/</schemaDirectory>
		<outputDirectory>${project.basedir}/src/main/java</outputDirectory>
		<clearOutputDir>false</clearOutputDir>
	</configuration>
</plugin>

The plugin uses XJC tool as code generation engine. XJC compiles an XML schema file into fully annotated Java classes.

Now execute above maven plugin to generate java code from XSD.

Create SOAP WS Endpoint

StudentEndpoint class will handle all the incoming requests for the service and will delegate the call to the finder method of the data repository.

package com.example.howtodoinjava.springbootsoapservice;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.ws.server.endpoint.annotation.Endpoint;
import org.springframework.ws.server.endpoint.annotation.PayloadRoot;
import org.springframework.ws.server.endpoint.annotation.RequestPayload;
import org.springframework.ws.server.endpoint.annotation.ResponsePayload;
import com.howtodoinjava.xml.school.StudentDetailsRequest;
import com.howtodoinjava.xml.school.StudentDetailsResponse;

@Endpoint
public class StudentEndpoint 
{
	private static final String NAMESPACE_URI = "https://www.howtodoinjava.com/xml/school";

	private StudentRepository StudentRepository;

	@Autowired
	public StudentEndpoint(StudentRepository StudentRepository) {
		this.StudentRepository = StudentRepository;
	}

	@PayloadRoot(namespace = NAMESPACE_URI, localPart = "StudentDetailsRequest")
	@ResponsePayload
	public StudentDetailsResponse getStudent(@RequestPayload StudentDetailsRequest request) {
		StudentDetailsResponse response = new StudentDetailsResponse();
		response.setStudent(StudentRepository.findStudent(request.getName()));

		return response;
	}
}

Here few details about the annotations –

1. @Endpoint registers the class with Spring WS as a potential candidate for processing incoming SOAP messages.
2. @PayloadRoot is then used by Spring WS to pick the handler method based on the message’s namespace and localPart. Please note the Namespace URL and Request Payload root request mentioned in this annotation.
3. @RequestPayload indicates that the incoming message will be mapped to the method’s request parameter.
4. The @ResponsePayload annotation makes Spring WS map the returned value to the response payload.

Create Data Repository

As mentioned, we will use the hardcoded data as backend for this demo, let’s add one class called StudentRepository.java with Spring @Repository annotation. It will simply hold data in HashMap and will also give one finder method called findStudent().

Read More – @Repository Annotations

package com.example.howtodoinjava.springbootsoapservice;

import java.util.HashMap;
import java.util.Map;
import javax.annotation.PostConstruct;
import org.springframework.stereotype.Component;
import org.springframework.util.Assert;
import com.howtodoinjava.xml.school.Student;

@Component
public class StudentRepository {
	private static final Map<String, Student> students = new HashMap<>();

	@PostConstruct
	public void initData() {
		
		Student student = new Student();
		student.setName("Sajal");
		student.setStandard(5);
		student.setAddress("Pune");
		students.put(student.getName(), student);
		
		student = new Student();
		student.setName("Kajal");
		student.setStandard(5);
		student.setAddress("Chicago");
		students.put(student.getName(), student);
		
		student = new Student();
		student.setName("Lokesh");
		student.setStandard(6);
		student.setAddress("Delhi");
		students.put(student.getName(), student);
		
		student = new Student();
		student.setName("Sukesh");
		student.setStandard(7);
		student.setAddress("Noida");
		students.put(student.getName(), student);
	}

	public Student findStudent(String name) {
		Assert.notNull(name, "The Student's name must not be null");
		return students.get(name);
	}
}

Add Configuration Beans

Create a class with @Configuration annotation to hold bean definitions.

package com.example.howtodoinjava.springbootsoapservice;

import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.ws.config.annotation.EnableWs;
import org.springframework.ws.config.annotation.WsConfigurerAdapter;
import org.springframework.ws.transport.http.MessageDispatcherServlet;
import org.springframework.ws.wsdl.wsdl11.DefaultWsdl11Definition;
import org.springframework.xml.xsd.SimpleXsdSchema;
import org.springframework.xml.xsd.XsdSchema;

@EnableWs
@Configuration
public class Config extends WsConfigurerAdapter 
{
	@Bean
	public ServletRegistrationBean messageDispatcherServlet(ApplicationContext applicationContext) 
	{
		MessageDispatcherServlet servlet = new MessageDispatcherServlet();
		servlet.setApplicationContext(applicationContext);
		servlet.setTransformWsdlLocations(true);
		return new ServletRegistrationBean(servlet, "/service/*");
	}

	@Bean(name = "studentDetailsWsdl")
	public DefaultWsdl11Definition defaultWsdl11Definition(XsdSchema countriesSchema) 
	{
		DefaultWsdl11Definition wsdl11Definition = new DefaultWsdl11Definition();
		wsdl11Definition.setPortTypeName("StudentDetailsPort");
		wsdl11Definition.setLocationUri("/service/student-details");
		wsdl11Definition.setTargetNamespace("https://www.howtodoinjava.com/xml/school");
		wsdl11Definition.setSchema(countriesSchema);
		return wsdl11Definition;
	}

	@Bean
	public XsdSchema countriesSchema() 
	{
		return new SimpleXsdSchema(new ClassPathResource("school.xsd"));
	}
}

• Config class extends WsConfigurerAdapter which configures annotation driven Spring-WS programming model.
• MessageDispatcherServlet – Spring-WS uses it for handling SOAP requests. We need to inject ApplicationContext to this servlet so that Spring-WS find other beans. It also declares the URL mapping for the requests.
• DefaultWsdl11Definition exposes a standard WSDL 1.1 using XsdSchema. The bean name studentDetailsWsdl will be the wsdl name that will be exposed. It will be available under http://localhost:8080/service/studentDetailsWsdl.wsdl. This is the simplest approach to expose the contract first wsdl in spring.

  This configuration also uses the WSDL location servlet transformation servlet.setTransformWsdlLocations( true ) internally. If we see the exported WSDL, the soap:address will have the localhost address. Similarly, if we instead visit the WSDL from the public facing IP address assigned to the deployed machine, we will see that address instead of localhost. So the endpoint URL is dynamic based on the deployment environment.

Demo

Do maven build using mvn clean install and start the application using java -jar target\spring-boot-soap-service-0.0.1-SNAPSHOT.jar command. This will bring up one tomcat server in default port 8080 and application will be deployed in it.

1) Now go to http://localhost:8080/service/studentDetailsWsdl.wsdl to see if the WSDL is coming properly.

2) Once we have the successful WSDL generated, we can use that WSDL to create a project in SOAP ui and test the application. Sample Request and response is given below.

Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="https://www.howtodoinjava.com/xml/school">
   <soapenv:Header/>
   <soapenv:Body>
      <sch:StudentDetailsRequest>
         <sch:name>Sajal</sch:name>
      </sch:StudentDetailsRequest>
   </soapenv:Body>
</soapenv:Envelope>

Response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <ns2:StudentDetailsResponse xmlns:ns2="https://www.howtodoinjava.com/xml/school">
         <ns2:Student>
            <ns2:name>Sajal</ns2:name>
            <ns2:standard>5</ns2:standard>
            <ns2:address>Pune</ns2:address>
         </ns2:Student>
      </ns2:StudentDetailsResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Summary

In above example, we learned to create SOAP WS using Spring Boot project. We also learned to generate java code from WSDL. We learned about beans which are needed to process the SOAP requests.

Feel free to drop a comment if you face any difficulty in running above project.

Happy Learning !!