Table of Contents

• What You Will build
• What You Need
• Starting with Spring Initializr
• Add WSDL runtime dependency
• Create an XML Schema to Define the Domain
• Generate Domain Classes Based on an XML Schema
• Create Country Repository
• Create Country Service Endpoint
• Expose the web service
• Test the Application
• Summary
• See Also

This guide walks you through the process of creating a SOAP-based web service server with Spring.

What You Will build

You will build a server that exposes data from various European countries by using a WSDL-based SOAP web service.

Note	To simplify the example, you will use hardcoded data for the United Kingdom, Spain, and Poland.

What You Need

https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/prereq_editor_jdk_buildtools.adoc

https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/how_to_complete_this_guide.adoc

Starting with Spring Initializr

You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.

To manually initialize the project:

1. Navigate to https://start.spring.io. This service pulls in all the dependencies you need for an application and does most of the setup for you.

2. Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.

3. Click Dependencies and select Spring Web Services.

4. Click Generate.

5. Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.

Note	If your IDE has the Spring Initializr integration, you can complete this process from your IDE.

Add WSDL runtime dependency

Our service will require the wsdl4j dependency at runtime, let’s add it to our Gradle build:

link:complete/build.gradle[role=include]

Or our POM file:

link:complete/pom.xml[role=include]

Create an XML Schema to Define the Domain

The web service domain is defined in an XML schema file (XSD) that Spring-WS will automatically export as a WSDL.

Create an XSD file with operations to return a country’s name, population, capital, and currency. The following listing (from src/main/resources/META-INF/schemas/countriesWs.xsd) shows the necessary XSD file:

link:complete/src/main/resources/META-INF/schemas/countriesWs.xsd[role=include]

Generate Domain Classes Based on an XML Schema

The next step is to generate Java classes from the XSD file. The right approach is to do this automatically during build time by using a Maven or Gradle plugin.

The following listing shows the necessary plugin configuration for Maven:

link:complete/pom.xml[role=include]

Generated classes are placed in the target/generated-sources/jaxb/ directory.

To do the same with Gradle, you can declare a new plugin in the plugin section :

link:complete/build.gradle[role=include]

And then configure it to point to the XSD files location:

link:complete/build.gradle[role=include]

In both cases, the JAXB domain object generation process has been wired into the build tool’s lifecycle, so there are no extra steps to run.

Create Country Repository

In order to provide data to the web service, create a country repository. In this guide, you create a dummy country repository implementation with hardcoded data. The following listing (from src/main/java/com/example/producingwebservice/CountryRepository.java) shows how to do so:

link:complete/src/main/java/com/example/producingwebservice/CountryRepository.java[role=include]

Create Country Service Endpoint

To create a service endpoint, you need only a POJO with a few Spring WS annotations to handle the incoming SOAP requests. The following listing (from src/main/java/com/example/producingwebservice/CountryEndpoint.java) shows such a class:

link:complete/src/main/java/com/example/producingwebservice/CountryEndpoint.java[role=include]

The @Endpoint annotation registers the class with Spring WS as a potential candidate for processing incoming SOAP messages.

The @PayloadRoot annotation is then used by Spring WS to pick the handler method, based on the message’s namespace and localPart.

The @RequestPayload annotation indicates that the incoming message will be mapped to the method’s request parameter.

The @ResponsePayload annotation makes Spring WS map the returned value to the response payload.

Note	In all of these chunks of code, the io.spring.guides classes will report compile-time errors in your IDE unless you have run the task to generate the domain classes based on the WSDL.

Expose the web service

Now we need to expose the service so that clients can fetch the WSDL definition. Spring Boot will scan all ".xsd" and ".wsdl" files in the configured location. So first, we’ll need to declare the location of our schema files by editing src/main/resources/application.properties:

link:complete/src/main/resources/application.properties[role=include]

Spring Boot will create SimpleXsdSchema or DefaultWsdl11Definition beans with their names matching file names. Here, we can expect a SimpleXsdSchema bean named countriesWs and we can use it to create a WSDL bean for exposing it. For that, let’s create a new src/main/java/com/example/producingwebservice/WebServiceConfig.java file with the following content:

link:complete/src/main/java/com/example/producingwebservice/WebServiceConfig.java[role=include]

The DefaultWsdl11Definition exposes a standard WSDL 1.1 by using the configured XsdSchema.

Important

The bean name for DefaultWsdl11Definition determines the URL under which the generated WSDL file is available. In this case, the WSDL will be available under http://<host>:<port>/services/countries.wsdl.

By default, they will be exposed on the "/services" HTTP endpoint, but this can be customized with the spring.webservices.path property.

Test the Application

Now that the application is running, you can test it. Create a file called request.xml that contains the following SOAP request:

link:complete/request.xml[role=include]

The are a few options when it comes to testing the SOAP interface. You can use something similar to SoapUI or use command-line tools if you are on a *nix/Mac system. The following example uses curl from the command line:

# Use data from file
$ curl --header "Content-Type: text/xml" -d @request.xml http://localhost:8080/services | xmllint --format

As a result, you should see the following response:

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ns2:getCountryResponse xmlns:ns2="https://spring.io/guides/gs-producing-web-service">
      <ns2:country>
        <ns2:name>Spain</ns2:name>
        <ns2:population>46704314</ns2:population>
        <ns2:capital>Madrid</ns2:capital>
        <ns2:currency>EUR</ns2:currency>
      </ns2:country>
    </ns2:getCountryResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Summary

Congratulations! You have developed a SOAP-based service with Spring Web Services.

See Also

The following guides may also be helpful:

• Consuming a SOAP web service

• Building an Application with Spring Boot

https://raw.githubusercontent.com/spring-guides/getting-started-macros/main/footer.adoc