160 lines
6.9 KiB
Plaintext
160 lines
6.9 KiB
Plaintext
---
|
|
tags: [SOAP]
|
|
projects: [spring-ws]
|
|
---
|
|
:spring_version: current
|
|
:toc:
|
|
:project_id: gs-consuming-web-service
|
|
:spring_version: current
|
|
:spring_boot_version: 1.4.0.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 weather data from a remote, WSDL-based web service using http://en.wikipedia.org/wiki/SOAP[SOAP].
|
|
You can find out more about the weather service at http://wiki.cdyne.com/index.php/CDYNE_Weather
|
|
|
|
The service provides weather forecasts based on a zipcode. You will be able to use your own zip code.
|
|
|
|
|
|
== 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.
|
|
|
|
|
|
[[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 weather service can be found at http://wsf.cdyne.com/WeatherWS/Weather.asmx?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 weather 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/WeatherClient.java`
|
|
[source,java]
|
|
----
|
|
include::complete/src/main/java/hello/WeatherClient.java[]
|
|
----
|
|
|
|
The client contains two methods: `getCityForecastByZip` which does the actual SOAP exchange, and `printResponse` which prints the received response. We will focus on the former method.
|
|
|
|
In this method, both the `GetCityForecastByZIP` and the `GetCityForecastByZIPResponse` classes are derived from the WSDL and were generated in the JAXB generation process described in the previous step.
|
|
It creates the `GetCityForecastByZIP` request object and set it with the `zipCode` parameter.
|
|
After printing out the zip code, 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 `GetCityForecastByZIP` 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 `GetCityForecastByZIPResponse` 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/WeatherConfiguration.java`
|
|
[source,java]
|
|
----
|
|
include::complete/src/main/java/hello/WeatherConfiguration.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 `weatherClient` is created and configured with the URI of the weather 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 a single weather forecast for a given zip code.
|
|
|
|
`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 `WeatherConfiguration.class` as an argument to its `run()` method. This tells Spring to read the annotation metadata from `WeatherConfiguration` 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 zip code 94304, Palo Alto, CA. Towards the end of this guide, you'll see how to plug in a different zip code 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 forecast for 94304
|
|
|
|
Forecast for Palo Alto, CA
|
|
2013-01-03 Partly Cloudy °-57°
|
|
2013-01-04 Partly Cloudy 41°-58°
|
|
2013-01-05 Partly Cloudy 41°-59°
|
|
2013-01-06 Partly Cloudy 44°-56°
|
|
2013-01-07 Partly Cloudy 41°-60°
|
|
2013-01-08 Partly Cloudy 42°-60°
|
|
2013-01-09 Partly Cloudy 43°-58°
|
|
```
|
|
|
|
You can plug in a different zip code by typing `java -jar build/libs/gs-consuming-web-service-0.1.0.jar 34769`
|
|
|
|
```
|
|
Requesting forecast for 34769
|
|
|
|
Forecast for Saint Cloud, FL
|
|
2014-02-18 Sunny 51°-79°
|
|
2014-02-19 Sunny 55°-81°
|
|
2014-02-20 Sunny 59°-84°
|
|
2014-02-21 Partly Cloudy 63°-85°
|
|
2014-02-22 Partly Cloudy 63°-84°
|
|
2014-02-23 Partly Cloudy 63°-82°
|
|
2014-02-24 Partly Cloudy 62°-80°
|
|
```
|
|
|
|
== Summary
|
|
|
|
Congratulations! You've just developed a client to consume a SOAP-based web service with Spring.
|
|
|
|
|
|
|
|
|
|
|
|
include::https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/footer.adoc[]
|
|
|