By Marone: July 2019 | last update: July 2020

Soap with Spring boot - Schema first

Goal

In the previous article we saw how to use Spring boot contract-first approach starting from a wsdl file. We will flow the contract-first with schema approach. Just keep in mind Spring boot is using Spring-WS under the hood

Used technologies

JDK 1.8
Maven 3.2

XSD First

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:tns="http://www.wstutorial.com/ws/TutorialService"
	targetNamespace="http://www.wstutorial.com/ws/TutorialService">
	<xs:complexType name="statusCode">
		<xs:sequence>
			<xs:element name="code" type="xs:long" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="TutorialType">
		<xs:all>
			<xs:element name="id" type="xs:long" />
			<xs:element name="name" type="xs:string" />
			<xs:element name="author" type="xs:string" />
		</xs:all>
	</xs:complexType>

	<xs:element name="updateTutorialRequest">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="tutorialType" type="tns:TutorialType" />
			</xs:sequence>
		</xs:complexType>
	</xs:element>

	<xs:element name="updateTutorialResponse">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="statusCode" type="tns:statusCode" />
			</xs:sequence>
		</xs:complexType>
	</xs:element>

	<xs:element name="deleteTutorialRequest">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="id" type="xs:long" />
			</xs:sequence>
		</xs:complexType>
	</xs:element>

	<xs:element name="deleteTutorialResponse">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="statusCode" type="tns:statusCode" />
			</xs:sequence>
		</xs:complexType>
	</xs:element>

	<xs:element name="getTutorialsRequest">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="id" type="xs:long" />
			</xs:sequence>
		</xs:complexType>
	</xs:element>

	<xs:element name="getTutorialsResponse">
		<xs:complexType>
			<xs:sequence>
				<xs:element type="tns:TutorialType" minOccurs="0"
					maxOccurs="unbounded" name="tutorials" />
			</xs:sequence>
		</xs:complexType>
	</xs:element>

	<xs:complexType name="TutorialTypes">
		<xs:sequence>
			<xs:element type="tns:TutorialType" minOccurs="0"
				maxOccurs="unbounded" name="tutorials" />
		</xs:sequence>
	</xs:complexType>

	<xs:element name="tutorialFault">
		<xs:complexType>
			<xs:sequence>
				<xs:element name="message" type="xs:string" />
			</xs:sequence>
		</xs:complexType>
	</xs:element>
</xs:schema>

Info! According to Spring WS documentation the Resquest/Response/Fault elements should be marked with suffix. We are using the default ones:
updateTutorialRequest
updateTutorialResponse
tutorialFault

Maven dependencies

<?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.wstutorial.ws</groupId>
	<artifactId>schemafirst-spring-boot</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<packaging>jar</packaging>

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

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<java.version>1.8</java.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>
		<dependency>
			<groupId>wsdl4j</groupId>
			<artifactId>wsdl4j</artifactId>
		</dependency>
	</dependencies>
	
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
			<plugin>
				<groupId>org.codehaus.mojo</groupId>
				<artifactId>jaxb2-maven-plugin</artifactId>
				<version>2.4</version>
				<executions>
					<execution>
						<id>xjc</id>
						<goals>
							<goal>xjc</goal>
						</goals>
					</execution>
				</executions>
				<configuration>
					<outputDirectory>${project.basedir}/src/main/java</outputDirectory>
					<clearOutputDir>false</clearOutputDir>
					<sources>
						<source>${project.basedir}/src/main/resources/xsd</source>
					</sources>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

The spring-boot-starter-web-services dependency includes the needed dependencies for using Spring-WS
WSDL4J The Web Services Description Language for Java Toolkit allows the creation, representation, and manipulation of WSDL documents.

In Order to use schema elements in Endpoint class we need at first to generate Java classes from the xsd file The jaxb2-maven-plugin will be used to handle the code generation.

The Plugin looks in the path defined in <source> to find any XSD file
The<outputDirectory> is the location where the java classes will be generated

Generate code

mvn clean generate-resources

The generated java classes are under /src and looks like:

xml schema

Configuration

package com.wstutorial.ws;

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 AppConfig extends WsConfigurerAdapter {
	
	@Bean
	public XsdSchema tutorialsSchema() {
		return new SimpleXsdSchema(new ClassPathResource("xsd/tutorialService.xsd"));
	}
	
	@Bean(name = "tutorials")
	public DefaultWsdl11Definition defaultWsdl11Definition(XsdSchema tutorialsSchema) {
		DefaultWsdl11Definition wsdl11Definition = new DefaultWsdl11Definition();
		wsdl11Definition.setPortTypeName("TutorialsPort");
		wsdl11Definition.setLocationUri("/ws");
		wsdl11Definition.setTargetNamespace("http://www.wstutorial.com/was/TutorialService");
		wsdl11Definition.setSchema(tutorialsSchema);
		return wsdl11Definition;
	}
	
	@SuppressWarnings({ "rawtypes", "unchecked" })
	@Bean
	public ServletRegistrationBean messageDispatcherServlet(ApplicationContext applicationContext) {
		MessageDispatcherServlet servlet = new MessageDispatcherServlet();
		servlet.setApplicationContext(applicationContext);
		servlet.setTransformWsdlLocations(true);
		return new ServletRegistrationBean(servlet, "/ws/*");
	}
    
}

Notes:

@EnableWs: Provides spring web service configuration
In lines (19-22) we define the xml schema.
We define DefaultWsdl11Definition with @Bean(name = "tutorials") as name, this name will be the name of the WSDL in the URL
- wsdl11Definition.setSchema(tutorialsSchema), use the schema we define above
- wsdl11Definition.setPortTypeName("TutorialsPort"), set the port type name
- wsdl11Definition.setLocationUri("/ws"), The path in URL for the exposed WSDL
MessageDispatcherServlet will be used to handle the http requests
- Setting *ApplicationContext* is required
- The ServletRegistrationBean maps all the incoming requests with URI /ws/* to the servlet
The url of the wsdl will look like: scheme://host:port/(servlet mapping uri)/(DefaultWsdl11Definition bean name).wsdl, which is equivalent to http://localhost:8090/ws/tutorials.wsdl

Implementing the Endpoint

After expsoing the wsdl now we need some implementation to handle incoming XML messages, in order to do that we need a class with one or more handling methods. In this tutorial we will implement only two methods

package com.wstutorial.ws;

import org.springframework.ws.server.endpoint.annotation.*;

import com.wstutorial.ws.tutorialservice.*;

@Endpoint
public class TutorialsEndpoint {

	private static final String NAMESPACE_URI = "http://www.wstutorial.com/ws/TutorialService";

	@PayloadRoot(namespace = NAMESPACE_URI, localPart = "getTutorialsRequest")
	@ResponsePayload
	public GetTutorialsResponse getTutorials(
			@RequestPayload GetTutorialsRequest request) {
		System.out.println("Id: " + request.getId());
		GetTutorialsResponse response = new GetTutorialsResponse();

		TutorialType tutorial = new TutorialType();
		tutorial.setId(1);
		tutorial.setAuthor("John Doe");
		tutorial.setName("Python Basics");
		response.getTutorials().add(tutorial);

		return response;
	}

	@PayloadRoot(namespace = NAMESPACE_URI, localPart = "deleteTutorialRequest")
	@ResponsePayload
	public DeleteTutorialResponse deleteTutorial(@RequestPayload DeleteTutorialRequest request) {
		System.out.println("Id: " + request.getId());
		DeleteTutorialResponse response = new DeleteTutorialResponse();
		StatusCode okay = new StatusCode();
		okay.setCode(200);
		response.setStatusCode(okay);

		return response;
	}

}

Details:
@Endpoint, this class becomes web service Endpoint
The method annotated with @PayloadRoot becomes an Endpoint method. Depending on the attributes namespace and localPart Spring-WS will forward the incoming request to a appropriate method
@RequestPayload and @ResponsePayload are for mapping request and response values

Run the SOAP Web Service

package com.wstutorial.ws;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SchemaFirstApp {
    public static void main(String[] args) {
        SpringApplication.run(SchemaFirstApp.class, args);
    }
}

Big picture

Test with soapUI

According to application.properties the application is running on port 8090
The WSDL is now located at http://localhost:8090/ws/tutorials.wsdl and the endpoint URL is http://localhost:8090/ws soapUI

References

spring boot