In this post, we will describe how to create a SOAP webservice from our existing Spring Boot REST API. In the last few posts, we have covered the following
- Spring Boot REST CRUD API – Part I
- Swagger Documentation for Spring Boot REST API – Part II
- Error Handling and logging in Spring Boot REST API – Part III
- Consuming RESTful Webservice – Part IV
This SOAP webservice will provide us user data from the database which is we have connected through Spring-data in Spring REST API.
1. Requirements
- Eclipse Mars2
- Maven 3.1 and above
- Spring 1.4 and above
- Java 7
- Tomcat 8
2. SOAP Web Service
We will use our existing Spring Boot REST API to build an application that will act as a SOAP web service to provide users data. For a given user id, web service will return user data.
Let’s create a schema file in src/main/resources directory and maven will create java classes based on this schema file.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="https://betterjavacode.com/benefits/soap" targetNamespace="https://betterjavacode.com/benefits/soap" elementFormDefault="qualified">
<xs:element name="getUserRequest">
<xs:complexType>
<xs:sequence>
<xs:element name="id" type="xs:int"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="getUserResponse">
<xs:complexType>
<xs:sequence>
<xs:element name="user" type="tns:user"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name="user">
<xs:sequence>
<xs:element name="id" type="xs:int"/>
<xs:element name="firstname" type="xs:string"/>
<xs:element name="middlename" type="xs:string"/>
<xs:element name="lastname" type="xs:string"/>
<xs:element name="username" type="xs:string"/>
<xs:element name="createdate" type="xs:date"/>
<xs:element name="jobtitle" type="xs:string"/>
<xs:element name="email" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
3. Update Maven dependencies
Now to generate classes from schema, we have to make sure we have all the right dependencies in our pom.xml. We will also add spring boot service dependency to create a SOAP web service.
<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">
<modelVersion>4.0.0</modelVersion>
<groupId>com.betterjavacode</groupId>
<artifactId>Benefits</artifactId>
<packaging>war</packaging>
<version>0.0.1-SNAPSHOT</version>
<name>Benefits Maven Webapp</name>
<url>http://maven.apache.org</url>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.2.RELEASE</version>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey2-jaxrs</artifactId>
<version>1.5.12</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-api</artifactId>
</dependency>
<dependency>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web-services</artifactId>
</dependency>
<dependency>
<groupId>wsdl4j</groupId>
<artifactId>wsdl4j</artifactId>
</dependency>
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
<version>2.1</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.3</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>2.6</version>
<configuration>
<warSourceDirectory>WebContent</warSourceDirectory>
<failOnMissingWebXml>false</failOnMissingWebXml>
</configuration>
</plugin>
<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>
<schemaLanguage>WSDL</schemaLanguage>
<generatePackage>com.betterjavacode.benefits.soap</generatePackage>
<forceRegenerate>true</forceRegenerate>
<scehmas>
<schema>
<url>http://localhost:8080/benefits/endpoints/users.wsdl</url>
</schema>
</scehmas>
</configuration>
</plugin>
</plugins>
<finalName>Benefits</finalName>
</build>
</project>
If we run the project with maven build now, the plugin jaxb2-maven-plugin will generate classes under com.betterjavacode.benefits.soap directory. It will also enable our wsdl SOAP url for users. This will generate following java objects
GetUserRequestGetUserResponseObjectFactorypackage-infoUser
4. Defining the service
Next, we will define an interface for our service. This will look like below
package com.betterjavacode.benefits.services;
public interface UserAccountService
{
public com.betterjavacode.benefits.soap.user.getUserDetails(int id);
}
Implementation of this service will be mapping out entity class User to generated class for soap service User. Using the id as a key to get user data from repository, we will map to soap service user. For post purposes, we will not show the implementation of this interface.
5. Creating the Service Endpoint
What is a service endpoint? When a SOAP request for defined URL is handled by Spring servlet, Spring servlet redirects that request to service endpoint. Service endpoint then processes that request to create a response. Our spring-boot-starter-web-services dependency will bring all the necessary classes for annotation purposes.
package com.betterjavacode.benefits.services.endpoints;
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.betterjavacode.benefits.services.UserAccountService;
import com.betterjavacode.benefits.soap.GetUserRequest;
import com.betterjavacode.benefits.soap.GetUserResponse;
import com.betterjavacode.benefits.soap.User;
@Endpoint
public class UserAccountServiceEndpoint
{
// private static final String TARGET_NAMESPACE ="http://com/betterjavacode/benefits/webservices/useraccountservice";
private static final String TARGET_NAMESPACE = "https://betterjavacode.com/benefits/soap";
@Autowired private UserAccountService userAccountService;
@PayloadRoot(localPart = "getUserRequest", namespace = TARGET_NAMESPACE)
public @ResponsePayload GetUserResponse getUserRequest(@RequestPayload GetUserRequest request)
{
GetUserResponse response = new GetUserResponse();
User user = userAccountService.getUserDetails(request.getId());
response.setUser(user);
return response;
}
}
@Endpoint annotation allows the class to be defined as service endpoint and included in @Component annotation for scanning. Make sure the namespace defined in this class matches with XSD schema definition. Otherwise, you can run into error for “No Endpoint defined for“.
6. Configuration
Next, we will configure our configuration class to generate wsdl endpoint. This configuration class will be annotated by @EnableWs to provide web service configuration.
package com.betterjavacode.benefits;
import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
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;
@Configuration
@EnableWs
@ComponentScan("com.betterjavacode")
public class AppConfig extends WsConfigurerAdapter
{
@Bean
public ServletRegistrationBean messageDispatcherServlet(ApplicationContext applicationContext)
{
MessageDispatcherServlet servlet = new MessageDispatcherServlet();
servlet.setApplicationContext(applicationContext);
return new ServletRegistrationBean(servlet,"/benefits/endpoints/*");
}
@Bean(name="users")
public DefaultWsdl11Definition defaultWsdl11Definition(XsdSchema usersSchema)
{
DefaultWsdl11Definition wsdl11definition = new DefaultWsdl11Definition();
wsdl11definition.setPortTypeName("UserAccountService");
wsdl11definition.setLocationUri("/endpoints");
wsdl11definition.setTargetNamespace("http://com/betterjavacode/benefits/webservices/useraccountservice");
wsdl11definition.setSchema(usersSchema);
return wsdl11definition;
}
@Bean
public XsdSchema usersSchema()
{
return new SimpleXsdSchema(new ClassPathResource("employees.xsd"));
}
}
Few important points about this configuration class are
- MessageDispatcherServlet is a required servlet to dispatch web service messages. We set this servlet with a bean to handle the URL from which request will be coming.
- DefaultWsdl11Definition creates SOAP for the given XSD schema
- XsdSchema provides an abstraction for our users XSD schema
7. Running the SOAP Webservice
Now build our project with maven. Run the spring boot application through eclipse to start the embedded tomcat server. Once the tomcat server starts, if we access url http://localhost:8080/benefits/endpoints/users.wsdl
Output in the browser will be as below
Here we showed how to create a simple SOAP webservice which we have combined with Spring Boot REST API service. We can also test this SOAP webservice using Soap UI, as shown in below screenshot
8. Consuming the SOAP web service
In previous steps, we showed how to produce a SOAP web service, now we will show how to consume this SOAP web service programmatically.
8.1 Create a client class
Under package com.betterjavacode.benefits.views, define a class UserClient which will extend a WebServiceGatewaySupport class. WebServiceGatewaySupport class provides web service methods.
package com.betterjavacode.benefits.views;
import org.springframework.ws.client.core.support.WebServiceGatewaySupport;
import org.springframework.ws.soap.client.core.SoapActionCallback;
import com.betterjavacode.benefits.soap.GetUserRequest;
import com.betterjavacode.benefits.soap.GetUserResponse;
public class UserClient extends WebServiceGatewaySupport
{
public GetUserResponse getUserById(int userid)
{
GetUserRequest userrequest = new GetUserRequest(); userrequest.setId(userid);
GetUserResponse response = (GetUserResponse) getWebServiceTemplate().marshalSendAndReceive(userrequest, new SoapActionCallback("http://localhost:8080/benefits/endpoints/getUserResponse"));
return response;
}
}
8.2 Configure the client for Spring Bean support
We will configure Jaxb2Marshaller to support JAXB to set context path. This will help us marshal and unmarshal our xml request and response through.
package com.betterjavacode.benefits.views;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;
@Configuration
public class ClientAppConfig
{
@Bean
public Jaxb2Marshaller marshaller()
{
Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
marshaller.setContextPath("com.betterjavacode.benefits.soap");
return marshaller;
}
@Bean
public UserClient userClient(Jaxb2Marshaller marshaller)
{
// WSDL URL - http://localhost:8080/benefits/endpoints/users.wsdl
UserClient uc = new UserClient();
uc.setDefaultUri("http://localhost:8080/benefits/endpoints/users.wsdl");
uc.setMarshaller(marshaller);
uc.setUnmarshaller(marshaller);
return uc;
}
}
8.3 Run the SOAP web service client
We will define a class with the main method to pass an argument of user id. Our client will call the web service with a passed argument to return the data if that user id exists in the database.
9. Conclusion
In this article, we showed how to create a SOAP web service and how to build a client to consume the same SOAP web service using Spring Boot. The code for this is available at github
10. References
- Spring Web services tutorial
- SOAP Web service producer and consumer
- Consuming a web service in java and SOAP UI