149 lines
6.6 KiB
Plaintext
149 lines
6.6 KiB
Plaintext
---
|
|
tags: [SOAP]
|
|
projects: [spring-ws]
|
|
---
|
|
:spring_version: current
|
|
:toc:
|
|
:project_id: gs-consuming-web-service
|
|
:spring_version: current
|
|
:spring_boot_version: 1.5.8.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 quote service at http://www.webservicex.com/stockquote.asmx?op=GetQuote.
|
|
|
|
The service provides stock market quotes. You will be able to use your own ticker symbol.
|
|
|
|
|
|
== 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 quote service can be found at http://www.webservicex.com/stockquote.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/QuoteClient.java`
|
|
[source,java]
|
|
----
|
|
include::complete/src/main/java/hello/QuoteClient.java[]
|
|
----
|
|
|
|
The client contains one method: `getQuote` which does the actual SOAP exchange.
|
|
|
|
In this method, both the `GetQuote` and the `GetQuoteResponse` classes are derived from the WSDL and were generated in the JAXB generation process described in the previous step.
|
|
It creates the `GetQuote` request object and sets it up with the `ticker` parameter.
|
|
After printing out the ticker 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 `GetQuote` 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 `GetQuoteResponse` 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/QuoteConfiguration.java`
|
|
[source,java]
|
|
----
|
|
include::complete/src/main/java/hello/QuoteConfiguration.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 `quoteClient` 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 `QuoteConfiguration.class` as an argument to its `run()` method. This tells Spring to read the annotation metadata from `QuoteConfiguration` 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 quote for MSFT
|
|
|
|
<StockQuotes><Stock><Symbol>MSFT</Symbol><Last>62.70</Last>...</StockQuotes>
|
|
```
|
|
|
|
You can plug in a different ticker by typing `java -jar build/libs/gs-consuming-web-service-0.1.0.jar ORCL`
|
|
|
|
```
|
|
Requesting quote for ORCL
|
|
|
|
<StockQuotes><Stock><Symbol>ORCL</Symbol><Last>39.26</Last>...</StockQuotes>
|
|
|
|
```
|
|
|
|
== 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[]
|