I’m going to show you EXACTLY how to create a Spring WSHello World SOAP web service that uses Spring Boot and Maven.
(Step-by-step)
So if you’re a Spring WS beginner, you’ll love this guide.
Let’s dive right in…
If you want to learn more about Spring WS – head on over to the Spring WS tutorials page.
1. What is Spring WS?
Spring Web Services (Spring-WS) is framework that focusses on creating document-driven Web services.
Spring-WS facilitates contract-first SOAP service development, allowing for a number of ways to manipulate XML payloads.
In this tutorial, we will create a Hello World web service. We start from a WSDL and build both consumer and provider using Spring WS, Spring Boot, and Maven.
The code is organized in such a way that you can choose to only run the client (consumer) or endpoint (provider) part.
2. Building a Contract First SOAP Web Service
Spring WS is contract-first only. This means that you need to start from a contract definition (XSD or WSDL).
In this example we start from a helloworld.wsdl WSDL file. It defines a Hello World service that takes as input a person’s first and last name and returns a greeting.
2. General Project Overview
We will use the following tools/frameworks:
Spring-WS 3.0
Spring Boot 2.1
Maven 3.5
Our project has the following directory structure:
Let’s use Spring Initializr to generate our Maven project. Make sure to select Web Services as a dependency.
Click Generate Project to generate and download the Spring Boot project template. At the root of the project, you’ll find a pom.xml file which is the XML representation of the Maven project.
To avoid having to manage the version compatibility of the different Spring dependencies, we will inherit the defaults from the spring-boot-starter-parent parent POM.
The generated project contains Spring Boot Starters that manage the different Spring dependencies.
The spring-boot-starter-web-services dependency includes the needed dependencies for using Spring Web Services.
The spring-boot-starter-test includes the dependencies for testing Spring Boot applications with libraries that include JUnit, Hamcrest and Mockito.
In the plugins section, you’ll find the Spring Boot Maven Plugin. spring-boot-maven-plugin allows us to build a single, runnable “uber-jar”. This is a convenient way to execute and transport code.
Also, the plugin allows you to start the example via a Maven command.
We want to be able to directly use the person and greeting elements (defined in the types section of the above Hello World WSDL) in our Java code. To achieve this we will use JAXB to generate the corresponding Java classes.
The maven-jaxb2-plugin, configured in above POM file, will handle the generation.
The plugin looks into the defined <schemaDirectory> in order to find any WSDL files for which it needs to generate the Java classes.
Make sure that the helloworld.wsdl file is available under /src/main/resources.
Execute the following Maven command to trigger the code generation:
This results in a number of generated Java classes under /target/generated-sources/xjc. You should find Person and Greeting. We will use these classes when we implement the client and provider of the SOAP service.
4. Spring Boot Setup
Spring Boot is used in order to make a Spring WS example application that you can “just run”.
We start by creating a SpringWsApplication which contains the main() method that uses Spring Boot’s SpringApplication.run() method to launch the application.
The @SpringBootApplication annotation is a convenience annotation that adds: @Configuration, @EnableAutoConfiguration and @ComponentScan.
The server-side of Spring-WS is designed around a central class called MessageDispatcher that dispatches incoming XML messages to endpoints. For more detailed information check out the reference documentation on the MessageDispatcher.
Spring Web Services supports multiple transport protocols. The most common is the HTTP transport, for which a custom MessageDispatcherServlet servlet is supplied. This is a standard Servlet which extends from the standard Spring Web DispatcherServlet (=central dispatcher for HTTP request handlers/controllers), and wraps a MessageDispatcher.
In other words: the MessageDispatcherServlet combines the attributes of the MessageDispatcher and DispatcherServlet and as a result allows the handling of XML messages over HTTP.
In the below WebServiceConfig configuration class we use a ServletRegistrationBean to register the MessageDispatcherServlet.
Note that it is important to inject and set the ApplicationContext to the MessageDispatcherServlet, otherwise it will not automatically detect other Spring Web Services related beans (such as the lower Wsdl11Definition).
The servlet mapping URI pattern on the ServletRegistrationBean is set to “/codenotfound/ws/*”. The web container will use this path to map incoming HTTP requests to the servlet.
The DefaultWsdl11Definition exposes a standard WSDL 1.1 using the specified Hello World WSDL file. The URL location at which this WSDL is available is determined by it’s Bean name in combination with the URI mapping of the MessageDispatcherServlet.
For the example below this is: [host]=”http://localhost:8080”+[servlet mapping uri]=”/codenotfound/ws/”+[WsdlDefinition bean name]=”helloworld”+[WSDL postfix]=”.wsdl”.
To enable the support for the @Endpoint annotation that we will use in the next section we need to annotate our configuration class with @EnableWs.
Now that our MessageDispatcherServlet is defined it will try to match incoming XML messages on the defined URI with one of the available handling methods. So all we need to do is set up an Endpoint that contains a handling method that matches the incoming request. This service endpoint can be a simple POJO with a number of Spring WS annotations as shown below.
The HelloWorldEndpoint POJO is annotated with the @Endpoint annotation which registers the class with Spring WS as a potential candidate for processing incoming SOAP messages. It contains a sayHello() method that receives a Person and returns a Greeting. Note that these are the Java classes that we generated earlier using JAXB (both are annotated with @XmlRoolElement).
To indicate what sort of messages a method can handle, it is annotated with the @PayloadRoot annotation that specifies a qualified name that is defined by a namespace and a local name (=localPart). Whenever a message comes in which has this qualified name for the payload root element, the method will be invoked.
The @ResponsePayload annotation makes Spring WS map the returned value to the response payload which in our example is the JAXB Greeting object.
The @RequestPayload annotation on the sayHello() method parameter indicates that the incoming message will be mapped to the method’s request parameter. In our case, this is the JAXB Person object.
The implementation of the sayHello service simply logs the name of the received Person and then uses this name to construct a Greeting that is also logged and then returned.
6. Creating the Client (Consumer)
Create a ClientConfig class and annotate it with @Configuration. This indicates that the class can be used by the Spring IoC container as a source of bean definitions.
The WebServiceTemplate is the core class for client-side Web service access in Spring-WS. It contains methods for sending requests and receiving response messages. Additionally, it can marshal objects to XML before sending them across a transport, and unmarshal any response XML into an object again.
As we will use JAXB to marshal our Person to a request XML and in turn unmarshal the response XML to our Greeting we need an instance of Spring’s Jaxb2Marshaller. This class requires a context path to operate, which you can set using the contextPath property. The context path is a list of colon (:) separated Java package names that contain schema derived classes.
In our example this is the package name of the generated Person and Greeting classes which is: com.codenotfound.types.helloworld.
The below ClientConfig configuration class specifies the WebServiceTemplate bean that uses the above Jaxb2Marshaller for marshaling and unmarshalling. We also set the default service URI to the service endpoint.
Note that the helloworld at the end of the default-uri can actually be omitted as previously we had specified “/codenotfound/ws/*” as URI of our endpoint servlet.
The client code is specified in the HelloWorldClient class. The sayHello() method creates a Person object based on the firstname and lastname input parameters.
The auto-wired WebServiceTemplate is used to marshal and send a person XML request towards the Hello World service. The result is unmarshalled to a Greeting object which is logged.
The @Component annotation will cause Spring to automatically import this bean into the container if automatic component scanning is enabled (adding the @SpringBootApplication annotation to the main SpringWsApplication class is equivalent to using @ComponentScan).
7. Testing the Web Service
Let’s create a basic unit test case in which the above client is used to send a request to the Hello World web service endpoint. We then verify if the response is equal to the expected greeting.
The @RunWith and @SpringBootTest testing annotations, that were introduced with Spring Boot 1.4, are used to tell JUnit to run using Spring’s testing support and bootstrap with Spring Boot’s support.
By setting the DEFINED_PORT web environment variable, a HTTP server is started on the port in the defined application properties. As we did not define a custom port the default value of 8080 is used.
To run above test, open a command prompt in the project root directory and execute following Maven command:
The result should be a successful build during which the embedded Tomcat is started and a call is made to the Hello World service:
If you just want to start Spring Boot so that the endpoint is up and running, execute following Maven command.
As mentioned earlier, the service WSDL is exposed on the following endpoint: