epubjs
Version:
Render ePub documents in the browser, across many devices
127 lines (125 loc) • 14.6 kB
HTML
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Web Services</title><link rel="stylesheet" href="core.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/></head><body><div class="sect1" title="Web Services"><div class="titlepage"><div><div><h1 class="title"><a id="learnjava3-CHP-14-SECT-4"/>Web Services</h1></div></div></div><p>Web services is a big, fast-moving topic and the subject of many
other fine O’Reilly books. However, because we have already covered so
many of the basic networking concepts (and we’ll cover XML in detail in
<a class="xref" href="ch24.html" title="Chapter 24. XML">Chapter 24</a>), we would be shirking our duties if
we didn’t provide an introduction to this important area of application
development. We conclude this chapter on client-side web communications
with a small example of invoking a web service.</p><p>In contrast to regular web applications intended to be visited by
web browsers, web services are application-level APIs intended to be
invoked by other application components. The primary distinction from
other types of interapplication communications mechanisms is that they use
web standards and XML to maximize cross-platform interoperability. We will
leave the analysis of when exactly this is important and the cost versus
benefits tradeoffs out of our discussion here. But the value in this idea
should be evident from the explosion of web-based business applications in
the past few years. Web services allow web-based applications to provide
well-defined, cross-platform interfaces for other web-based
applications.</p><div class="sect2" title="XML-RPC"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-14-SECT-4.1"/>XML-RPC</h2></div></div></div><p><a id="idx10840" class="indexterm"/> <a id="idx10843" class="indexterm"/>The term<span class="emphasis"><em> web services</em></span> means different
things to different people and has spawned many (too many) new standards
in recent years. In fact, there are so many web service standards named
with the prefix “WS” now that they are collectively known as “WS-*”
(affectionately referred to as WS
“splat” or WS “death star”). However, the original concept is simple:
web services take the ubiquitous, universally understood, and easily
implemented HTTP transaction and marry it with XML to define a standard
for invoking application services over the Web. The process is a type of
<span class="emphasis"><em>remote procedure call</em></span> in which HTTP plays its
traditional role as the basic communication provider and XML adds a
“business envelope” in which structured data is passed. This RPC-style
web service interaction defines both the basic structure of an
invocation request and also a set of XML encodings for marshaling the
primitive data types, allowing data parameters and results to be
exchanged in a truly cross-platform way. In contrast, another form of
web services—termed “document style”—places more emphasis on the
exchange of application-specific XML documents than on RPC-style data
marshaling and unmarshaling. We will concentrate on RPC-style web
services because they currently provide the tightest coupling to
Java.</p></div><div class="sect2" title="WSDL"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-14-SECT-4.2"/>WSDL</h2></div></div></div><p><a id="idx10839" class="indexterm"/> <a id="I_indexterm14_id775480" class="indexterm"/>A key component of web services technology is the Web
Services Description Language (WSDL). Using this standard, a structured
XML document describes a web service, the individual functions (methods)
it offers, and the XML data types for their respective arguments and
return values. WSDL is a type of interface definition language (IDL) and
plays that role for web services. However, a WSDL document can also
specify the service location and other features that are not
traditionally part of the service definitely.</p><p>For the client-side web services developer, the WSDL document
describing a service contains all of the information needed to generate
the client-side code used to invoke the service from Java or any other
language. As we’ll see in our example, it is not even necessary to have
an understanding of WSDL to use the service. One can simply generate the
client-side interfaces and use them from a Java language viewpoint.
We’ll see in <a class="xref" href="ch15.html" title="Chapter 15. Web Applications and Web Services">Chapter 15</a> that we can generate
the WSDL document for a new service directly from our own Java code as
well.<a id="I_indexterm14_id775509" class="indexterm"/></p></div><div class="sect2" title="The Tools"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-14-SECT-4.3"/>The Tools</h2></div></div></div><p><a id="idx10837" class="indexterm"/> <a id="idx10841" class="indexterm"/>The Java JAX-WS Java API for XML Web Services comes
bundled with Java 6 and later and contains all of the tools necessary to
use, create, and work with web services in Java. It’s even possible to
deploy web services for testing in simple scenarios using out-of-the-box
tools. As you might imagine, Java web services make extensive use of the
JAXP APIs for working with XML. JAX-WS adds the classes necessary for
remote calls, as well as the development-time <a id="I_indexterm14_id775558" class="indexterm"/><span class="emphasis"><em>wsimport</em></span> and <a id="I_indexterm14_id775567" class="indexterm"/><span class="emphasis"><em>wsgen</em></span> tools. The
<span class="emphasis"><em>wsimport</em></span> tool reads a WSDL description file and
generates the required Java interface and implementation classes to
invoke it. The <span class="emphasis"><em>wsgen</em></span> tool reads Java code
containing web service annotations and can generate WSDL and other
deployment-related files.</p><p>There are many application servers that provide their own
mechanisms for deploying web services and generating client-side code.
The Apache CXF project is another popular Java web services alternative
that can work with JAX-WS and other standards.<a id="I_indexterm14_id775589" class="indexterm"/><a id="I_indexterm14_id775596" class="indexterm"/></p></div><div class="sect2" title="The Weather Service Client"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-14-SECT-4.4"/>The Weather Service Client</h2></div></div></div><p><a id="idx10838" class="indexterm"/> <a id="idx10842" class="indexterm"/>This example shows just how easy it is to use a web
service from client-side code. We’re going to create a client for a
web-based weather lookup service. The service accepts a U.S. zip code as
an argument and returns the city, state, and weather conditions as a
result. Please note that the server-side component of this example is
hosted by a company called <span class="emphasis"><em>cdyne.com</em></span>, which is a
professional web services provider. Because this is a third-party site,
we cannot guarantee that it will remain active. If for any reason this
service disappears, don’t fret—we’ll build our own example in <a class="xref" href="ch15.html" title="Chapter 15. Web Applications and Web Services">Chapter 15</a>, where we implement a simple web service
ourselves.</p><p>All that we need to get started is the web service WSDL
description file. You can view the weather service at the <a class="ulink" href="http://bit.ly/13moiTh">WSDL website</a>. It’s an XML file that
defines a set of operations and data types for arguments and results.
The file is not intended to be human readable, and should make more
sense after we discuss XML in <a class="xref" href="ch24.html" title="Chapter 24. XML">Chapter 24</a>.</p><p>To generate the client code needed to interact with the service,
we run the <a id="I_indexterm14_id775677" class="indexterm"/><code class="literal">wsimport</code> utility that
is found in the JDK bin and pass it the WSDL location like so:</p><a id="I_14_tt910"/><pre class="programlisting"><code class="o">%</code> <code class="n">wsimport</code> <code class="nl">http:</code><code class="c1">//wsf.cdyne.com/WeatherWS/Weather.asmx?WSDL</code></pre><p>When <span class="emphasis"><em>wsimport</em></span> completes, you should find a
new directory tree named <span class="emphasis"><em>com/cdyne/ws/weatherws</em></span>
that contains compiled Java classes for the temperature service client
interface and an implementation. The wsimport command has many useful
options: you may wish to use the <code class="literal">-keep</code> option to retain the generated source
code for the client classes so that you can store the source with your
application. There is also a <code class="literal">-p</code>
option that lets you override the generated Java package name.</p><p>The generated code contains a class called <code class="literal">Weather</code> that represents the overall service
and an interface called <code class="literal">WeatherSoap</code>
that represents various <span class="emphasis"><em>ports</em></span> or groups of methods
on the service, among other implementation classes. (The “port” is WSDL
terminology for a group of functions on a web service.) If you retain
the soure code (with <code class="literal">-keep</code>) and take
a look at it, you’ll see that the generated classes use Java annotations
to identify the service elements. The <code class="literal">Weather</code> class is marked with <a id="I_indexterm14_id775754" class="indexterm"/><code class="literal">@WebServiceClient</code> and
the <code class="literal">WeatherSoap</code> interface is marked
as <a id="I_indexterm14_id775773" class="indexterm"/><code class="literal">@WebService</code>.
Furthermore, the methods of the <code class="literal">WeatherSoap</code> interface are marked with
<a id="I_indexterm14_id775792" class="indexterm"/><code class="literal">@WebMethod</code>. These
annotations add metadata to the code to identify the service and capture
the information needed from the WSDL to map to the service XML. We’ll
discuss web service annotations more when we build and deploy the server
side of a web service in the next chapter. We’ll also see annotations
used in analogous ways when we discuss XML binding with JAXB in <a class="xref" href="ch24.html" title="Chapter 24. XML">Chapter 24</a>.</p><p>Our client application can now use these classes to invoke the
service. The following code looks up the current weather in the 63132
zip code:</p><a id="I_14_tt911"/><pre class="programlisting"><code class="kn">import</code> <code class="nn">com.cdyne.ws.weatherws.*</code><code class="o">;</code>
<code class="kd">public</code> <code class="kd">class</code> <code class="nc">WSTest</code> <code class="o">{</code>
<code class="kd">public</code> <code class="kd">static</code> <code class="kt">void</code> <code class="nf">main</code><code class="o">(</code> <code class="n">String</code><code class="o">[]</code> <code class="n">args</code> <code class="o">)</code>
<code class="o">{</code>
<code class="n">WeatherSoap</code> <code class="n">weatherService</code> <code class="o">=</code> <code class="k">new</code> <code class="n">Weather</code><code class="o">().</code><code class="na">getWeatherSoap</code><code class="o">();</code>
<code class="n">WeatherReturn</code> <code class="n">weather</code> <code class="o">=</code> <code class="n">weatherService</code><code class="o">.</code><code class="na">getCityWeatherByZIP</code><code class="o">(</code> <code class="s">"63132"</code> <code class="o">);</code>
<code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">format</code><code class="o">(</code><code class="s">"%s, %s : %s : Temperature: %s, Wind: %s"</code><code class="o">,</code>
<code class="n">weather</code><code class="o">.</code><code class="na">getCity</code><code class="o">(),</code> <code class="n">weather</code><code class="o">.</code><code class="na">getState</code><code class="o">(),</code> <code class="n">weather</code><code class="o">.</code><code class="na">getDescription</code><code class="o">(),</code>
<code class="n">weather</code><code class="o">.</code><code class="na">getTemperature</code><code class="o">(),</code> <code class="n">weather</code><code class="o">.</code><code class="na">getWind</code><code class="o">()</code> <code class="o">);</code>
<code class="o">}</code>
<code class="o">}</code></pre><p>Remember that you need to either add the compiled service classes
to your classpath or compile the generated source files along with the
example code. If you run it, you should see output like the following.
Note that although this service has returned the values as strings, in
general, web service bindings to Java would allow elements like the
temperature to be returned as numeric types.</p><a id="I_programlisting14_id775838"/><pre class="programlisting"><code class="n">Saint</code> <code class="n">Louis</code><code class="o">,</code> <code class="n">MO</code> <code class="o">:</code> <code class="n">Partly</code> <code class="n">Cloudy</code> <code class="o">:</code> <code class="nl">Temperature:</code> <code class="mi">25</code><code class="o">,</code> <code class="nl">Wind:</code> <code class="n">CALM</code></pre><p>We’ll return to the topic of web services and implement our own
web service in the next chapter, where we hop over to the server side of
things and start building web applications.<a id="I_indexterm14_id775856" class="indexterm"/><a id="I_indexterm14_id775863" class="indexterm"/></p></div></div></body></html>