147 lines
7.1 KiB
Plaintext
147 lines
7.1 KiB
Plaintext
:spring_version: current
|
|
:toc:
|
|
:project_id: gs-consuming-web-service
|
|
:spring_version: current
|
|
:spring_boot_version: 2.0.5.RELEASE
|
|
:icons: font
|
|
:source-highlighter: prettify
|
|
|
|
This guide walks you through the process of consuming a link:/understanding/SOAP[SOAP-based web service] with Spring.
|
|
|
|
== What you'll build
|
|
|
|
You will build a client that fetches country data data from a remote, WSDL-based web service using http://en.wikipedia.org/wiki/SOAP[SOAP].
|
|
You can find out more about the country service, and run the service yourself by following https://spring.io/guides/gs/producing-web-service/[this guide].
|
|
|
|
The service provides country data. You will be able to query data about a country based on its name.
|
|
|
|
|
|
== What you'll need
|
|
|
|
:java_version: 1.8
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/prereq_editor_jdk_buildtools.adoc[]
|
|
|
|
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/how_to_complete_this_guide.adoc[]
|
|
|
|
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/hide-show-gradle.adoc[]
|
|
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/hide-show-maven.adoc[]
|
|
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/hide-show-sts.adoc[]
|
|
|
|
|
|
NOTE: If you read link:/guides/gs/producing-web-service[Producing a SOAP web service], you might be wondering why this guide doesn't use *spring-boot-starter-ws*? That Spring Boot starter is
|
|
only for server-side web services. That starter brings on board things like embedded Tomcat, which isn't need to make a web call.
|
|
|
|
== Run the target web service locally
|
|
|
|
Follow the steps in the https://spring.io/guides/gs/producing-web-service/[companion guide], or just clone the https://github.com/spring-guides/gs-producing-web-service[repository] and run the service (e.g. using `mvn spring-boot:run`) from its `complete` directory. You can verify that is working by visiting http://localhost:8080/ws/countries.wsdl in your browser.
|
|
|
|
[[initial]]
|
|
== Generate domain objects based on a WSDL
|
|
|
|
The interface to a SOAP web service is captured in a http://en.wikipedia.org/wiki/Web_Services_Description_Language[WSDL]. JAXB provides an easy means to generate Java classes from a WSDL (or rather: the XSD contained in the `<Types/>` section of the WSDL).
|
|
The WSDL for the country service can be found at http://localhost:8080/ws/countries.wsdl.
|
|
|
|
To generate Java classes from the WSDL in maven, you need the following plugin setup:
|
|
|
|
[source,xml,indent=0]
|
|
----
|
|
include::complete/pom.xml[tags=wsdl]
|
|
----
|
|
|
|
This setup will generate classes for the WSDL found at the specified URL, putting those classes in the `hello.wsdl` package.
|
|
|
|
To do the same with gradle, you will need the following in your build file:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
include::complete/build.gradle[tags=wsdl]
|
|
----
|
|
|
|
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.
|
|
|
|
== Create a country service client
|
|
|
|
To create a web service client, you simply have to extend the http://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/client/core/support/WebServiceGatewaySupport.html[WebServiceGatewaySupport] class and code your operations:
|
|
|
|
`src/main/java/hello/CountryClient.java`
|
|
[source,java]
|
|
----
|
|
include::complete/src/main/java/hello/CountryClient.java[]
|
|
----
|
|
|
|
The client contains one method: `getCountry` which does the actual SOAP exchange.
|
|
|
|
In this method, both the `GetCountryRequest` and the `GetCountryResponse` classes are derived from the WSDL and were generated in the JAXB generation process described in the previous step.
|
|
It creates the `GetCountryRequest` request object and sets it up with the `country` parameter (the name of the country).
|
|
After printing out the country name, it uses the http://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/client/core/WebServiceTemplate.html[WebServiceTemplate] supplied by the `WebServiceGatewaySupport` base class to do the actual SOAP exchange.
|
|
It passes the `GetCountryRequest` request object, as well as a `SoapActionCallback` to pass on a http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383528[SOAPAction] header with the request, as the WSDL described that it needed this header in the `<soap:operation/>` elements.
|
|
It casts the response into a `GetCountryResponse` object, which is then returned.
|
|
|
|
== Configuring web service components
|
|
|
|
Spring WS uses Spring Framework's OXM module which has the `Jaxb2Marshaller` to serialize and deserialize XML requests.
|
|
|
|
`src/main/java/hello/CountryConfiguration.java`
|
|
[source,java]
|
|
----
|
|
include::complete/src/main/java/hello/CountryConfiguration.java[]
|
|
----
|
|
|
|
The `marshaller` is pointed at the collection of generated domain objects and will use them to both serialize and deserialize between XML and link:/understanding/POJO[POJOs].
|
|
|
|
The `countryClient` is created and configured with the URI of the country service shown up above. It is also configured to use the JAXB marshaller.
|
|
|
|
== Make the application executable
|
|
|
|
This application is packaged up to run from the console and retrieve the data for a given country name:
|
|
|
|
`src/main/java/hello/Application.java`
|
|
[source,java]
|
|
----
|
|
include::complete/src/main/java/hello/Application.java[]
|
|
----
|
|
|
|
The `main()` method defers to the http://docs.spring.io/spring-boot/docs/{spring_boot_version}/api/org/springframework/boot/SpringApplication.html[`SpringApplication`] helper class, providing `CountryConfiguration.class` as an argument to its `run()` method. This tells Spring to read the annotation metadata from `CountryConfiguration` and to manage it as a component in the link:/understanding/application-context[Spring application context].
|
|
|
|
NOTE: This application is hard coded to look up symbol 'MSFT' which correspond to Microsoft Corporation. Towards the end of this guide, you'll see how to plug in a different symbol without editing the code.
|
|
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/build_an_executable_jar_subhead.adoc[]
|
|
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/build_an_executable_jar_with_both.adoc[]
|
|
|
|
|
|
Logging output is displayed. The service should be up and running within a few seconds.
|
|
|
|
```
|
|
Requesting country data for Spain
|
|
|
|
<getCountryRequest><name>Spain</name>...</getCountryRequest>
|
|
```
|
|
|
|
You can plug in a different country by typing `java -jar build/libs/gs-consuming-web-service-0.1.0.jar Poland`
|
|
|
|
```
|
|
Requesting location for Poland
|
|
|
|
<getCountryRequest><name>Poland</name>...</getCountryRequest>
|
|
```
|
|
|
|
== Summary
|
|
|
|
Congratulations! You've just developed a client to consume a SOAP-based web service with Spring.
|
|
|
|
== See Also
|
|
|
|
The following guides may also be helpful:
|
|
|
|
* https://spring.io/guides/gs/producing-web-service/[Producing a SOAP web service]
|
|
* https://spring.io/guides/gs/spring-boot/[Building an Application with Spring Boot]
|
|
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/footer.adoc[]
|