| tags | projects | ||
|---|---|---|---|
|
|
This guide walks you through the process of creating a SOAP-based web service server with Spring.
You will build a server that exposes data from various European countries using a WSDL-based SOAP web service.
|
Note
|
To simplify the example, you will use hardcoded data for the United Kingdom, Spain and Poland. |
The project you create needs to include spring-ws-core as a dependency in your build file as well as wsdl4j.
For maven:
link:complete/pom.xml[role=include]For gradle:
link:complete/build.gradle[role=include]The web service domain is defined in an XML schema file (XSD) that Spring-WS will export automatically as a WSDL.
Create an XSD file with operations to return a country’s name, population, capital and currency:
src/main/resources/countries.xsd
link:complete/src/main/resources/countries.xsd[role=include]The next step is to generate Java classes from the XSD file. The right approach is do this automatically during build time using a maven or gradle plugin.
Plugin configuration for maven:
link:complete/pom.xml[role=include]Generated classes are placed in target/generated-sources/jaxb/ directory.
To do the same with gradle, first you need to configure JAXB in your build file:
link:complete/build.gradle[role=include]|
Note
|
The build file above has tag and end comments. This is to make it easier to extract bits of it into this guide for more detailed explanation. These comments aren’t needed in your own build file.
|
Next step is to add task genJaxb used by gradle to generate Java classes:
link:complete/build.gradle[role=include]As gradle does not have a JAXB plugin (yet), it involves an ant task, which makes it a bit more complex than in maven.
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.
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.
link:complete/src/main/java/hello/CountryRepository.java[role=include]To create a service endpoint, you only need a POJO with a few Spring WS annotations to handle the incoming SOAP requests.
link:complete/src/main/java/hello/CountryEndpoint.java[role=include]@Endpoint registers the class with Spring WS as a potential candidate for processing incoming SOAP messages.
@PayloadRoot is then used by Spring WS to pick the handler method based on the message’s namespace and localPart.
@RequestPayload 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.
|
Create a new class with Spring WS related beans configuration:
link:complete/src/main/java/hello/WebServiceConfig.java[role=include]-
Spring WS uses a different servlet type for handling SOAP messages:
MessageDispatcherServlet. It is important to inject and setApplicationContexttoMessageDispatcherServlet. Without that, Spring WS will not detect Spring beans automatically. -
By naming this bean
dispatcherServlet, it replaces Spring Boot’s defaultDispatcherServletbean. -
DefaultMethodEndpointAdapterconfigures annotation driven Spring WS programming model. This makes it possible to use the various annotations like@Endpointmentioned earlier. -
DefaultWsdl11Definitionexposes a standard WSDL 1.1 usingXsdSchema
It’s important to notice that you need to specify bean names for MessageDispatcherServlet and DefaultWsdl11Definition. Bean names determine the URL under which web service and the generated WSDL file is available. In this case, the WSDL will be available under http://<host>:<port>/ws/countries.wsdl.
This configuration also uses the WSDL location servlet transformation servlet.setTransformWsdlLocations(true). If you visit http://localhost:8080/ws/countries.wsdl, the soap:address will have the proper address. If you instead
visit the WSDL from the public facing IP address assigned to your machine, you will see that address instead.
Although it is possible to package this service as a traditional WAR file for deployment to an external application server, the simpler approach demonstrated below creates a standalone application. You package everything in a single, executable JAR file, driven by a good old Java main() method. Along the way, you use Spring’s support for embedding the Tomcat servlet container as the HTTP runtime, instead of deploying to an external instance.
src/main/java/hello/Application.java
link:complete/src/main/java/hello/Application.java[role=include]The main() method defers to the SpringApplication helper class, providing Application.class as an argument to its run() method. This tells Spring to read the annotation metadata from Application and to manage it as a component in the Spring application context.
The @ComponentScan annotation tells Spring to search recursively through the hello package and its children for classes marked directly or indirectly with Spring’s @Component annotation. This directive ensures that Spring finds and registers the CountryRepository and CountriesEndpoint, because they are marked marked with @Component and @Endpoint, which in turn is a kind of @Component annotation.
The @EnableAutoConfiguration annotation switches on reasonable default behaviors based on the content of your classpath. For example, because the application depends on the embeddable version of Tomcat (tomcat-embed-core.jar), a Tomcat server is set up and configured with reasonable defaults on your behalf. And because the application also depends on Spring MVC (spring-webmvc.jar), a Spring MVC DispatcherServlet is configured and registered for you — no web.xml necessary! Auto-configuration is a powerful, flexible mechanism. See the API documentation for further details.
Logging output is displayed. The service should be up and running within a few seconds.
Now that the application is running, you can test it. Create a file request.xml containing 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 like SoapUI or just use command line tools if you are on a *nix/Mac system as shown below.
$ curl --header "content-type: text/xml" -d @request.xml http://localhost:8080/wsAs a result you should see this 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="http://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>|
Note
|
Odds are that the output will be a compact XML document instead of the nicely formatted one shown above. If you have xmllib2 installed on your system, you can curl <args above> > output.xml | xmllint --format output.xml
see the results formatted nicely.
|