Java Web Services in a Nutshell

An Example Web Service

Although it might appear from Figure 1-1 that there is a lot to learn before you can properly make use of web services, in practice, this is not true. Even though the technology is still relatively new, there are already tools in existence that simplify life for both the end user and the developer. To illustrate this, let’s look at how you might go about the task of developing a client application for the web service provided by Amazon.com.

First of all, how would you know that Amazon.com offers a web service? One way to find out is to visit their web site. In general, though, when looking for web services, you won’t know in advance all of the companies that might offer the service that you need, so you will most likely go to an electronic business registry and perform a search based on criteria such as industry sector, country of residence, etc. In Chapter 7, you’ll see exactly how businesses can publish information to a registry and attach classifications to it so that you can, indeed, perform a search based on various criteria, much as you would when looking for a business in the Yellow Pages.

Figure 1-3 shows the result of performing a search for Amazon.com in a UDDI business registry, which in this case is hosted by IBM.^[4] As it happens, Amazon.com has not applied any meaningful criteria to its entry in this registry (at least at the time of writing), so I did not find it by looking for booksellers. However, in an ideal world, this would be possible and, no doubt, for many other businesses, a search using reasonable criteria would produce the desired results. As you can see, the information on this page includes the URL of the WSDL definition of the service.

Figure 1-3. Results of looking for details of the Amazon.com web service in a UDDI registry

The WSDL definition can be downloaded using a web browser and, since it is an XML document, can be inspected to determine the details of the service interface. However, there is a simpler way. Using a tool called wscompile that is supplied with both the JWSDP and the J2EE 1.4 reference implementation, you can obtain a definition of the service in the form of a Java interface. You’ll see exactly how to perform this conversion in the chapters of this book that deal with JAX-RPC. The result is shown in Example 1-2.

Example 1-2. A Java version of the Amazon.com web service interface

public interface AmazonSearchPort extends java.rmi.Remote {
    public ora.jwsnut.chapter1.amazon.ProductInfo keywordSearchRequest(
        ora.jwsnut.chapter1.amazon.KeywordRequest keywordSearchRequest) 
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo browseNodeSearchRequest(
        ora.jwsnut.chapter1.amazon.BrowseNodeRequest browseNodeSearchRequest) 
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo asinSearchRequest(
        ora.jwsnut.chapter1.amazon.AsinRequest asinSearchRequest) 
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo upcSearchRequest(
                  ora.jwsnut.chapter1.amazon.UpcRequest upcSearchRequest) 
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo authorSearchRequest(
         ora.jwsnut.chapter1.amazon.AuthorRequest authorSearchRequest) 
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo artistSearchRequest(
         ora.jwsnut.chapter1.amazon.ArtistRequest artistSearchRequest) 
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo actorSearchRequest(
         ora.jwsnut.chapter1.amazon.ActorRequest actorSearchRequest) 
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo manufacturerSearchRequest(
         ora.jwsnut.chapter1.amazon.ManufacturerRequest
                     manufacturerSearchRequest) throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo directorSearchRequest(
         ora.jwsnut.chapter1.amazon.DirectorRequest directorSearchRequest) 
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo listManiaSearchRequest(
         ora.jwsnut.chapter1.amazon.ListManiaRequest listManiaSearchRequest)
                     throws java.rmi.RemoteException;
    public ora.jwsnut.chapter1.amazon.ProductInfo similaritySearchRequest(
         ora.jwsnut.chapter1.amazon.SimilarityRequest similaritySearchRequest)
                     throws java.rmi.RemoteException;
}

The Java interface is much easier to understand than the WSDL version, which you’ll find in the file chapter1\amazon\AmazonWebService.wsdl relative to the installation directory of the example source code for this book. The interface uses several classes, such as asinSearchRequest, which are passed to the methods that represent the web service operations, to supply the criteria for a product search. Each of these methods returns a ProductInfo object that contains the results of the search. These classes are all defined, in XML terms, in the WSDL document and are converted to Java form by the wscompile utility.

Given the interface definition in readable and compilable form, it only remains to write an application to use it. At this point, you would probably be looking for some documentation that would tell you what the method parameters mean, what each method does, and how to interpret the results. Usually, a company would publish a link to relevant documentation along with the service entry in the registry. It so happens that, at least when I looked, Amazon.com had not done this. You can, however, obtain documentation from the Amazon.com web site, where you will also discover that you need to obtain a “developer token” to make use of the service.

The example source code for this book contains a simple GUI application that uses the Amazon.com web service by collecting search parameters from the user, and using authorSearchRequest( ), asinSearchRequest( ) , and keywordSearchRequest( ) to perform the search. If you look at the source code for this example, which you’ll find in the directory chapter1\amazon\client\ora\jwsnut\chapter1\client, you’ll see that almost all of it is concerned with managing the user interface. In fact, only three lines of code are required to set up the JAX-RPC library in preparation for a call to be made to the service:

AmazonSearchService service = new AmazonSearchService_Impl(  );
amazonSearch = service.getAmazonSearchPort(  );
((Stub)amazonSearch)._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY, address);

What is convenient about JAX-RPC is that all of the classes required by the client application are generated for you from the WSDL. All you have to do is supply the service address, which can also be found in the WSDL file:^[5]

<!-- Endpoint for Amazon Web APIs -->
<service name="AmazonSearchService">
    <port name="AmazonSearchPort" binding="typens:AmazonSearchBinding">
        <soap:address location="http://soap.amazon.com/onca/soap"/>
    </port>
</service>

Actually calling the web service and obtaining the results requires the construction of a SOAP message containing the query parameters, transmitting it, receiving the response message, and converting it back from XML to Java objects. If you were to code this using the low-level SAAJ API, you would probably end up with a couple of pages of code. However, JAX-RPC reduces this to something much simpler. Here, for example, is how you might perform a search for a book based on author name:

AuthorRequest authorReq = new AuthorRequest(newKey, String.valueOf(page), 
MODE, WEBSERVICE, TYPE, devtag, VERSION);
result = amazonSearch.authorSearchRequest(authorReq);

At the moment, it’s not necessary to worry about what all of the method arguments mean. The important point is that obtaining information from a web service is no more complex in programming terms than making a local method call. The tools provided by JAX-RPC handle the details of parsing the service’s WSDL definition, and the use of SOAP and XML to encode the content of the message ensures that you don’t need to be concerned about either the nature of the platform on which the service itself is running or the programming language used to implement it.

You can try out the Amazon web service for yourself by obtaining a developer tag from the Amazon.com web site, including it in the jwsnutExamples.properties file in your home directory as the value of the AMAZON_TAG property, making chapter1\amazon your working directory, and typing the following commands:

ant compile
ant run-client

The user interface that appears allows you to choose a search based on Author, Keyword, or ISBN, and a search string of your choice. To start the search, press the Go button. The books (up to 10 of them) that match your search criterion appear in the form of a list. If you select an entry from this list, the sales ranking for that book, together with any available customer reviews, appears, as shown in Figure 1-4.

Figure 1-4. The results of a book search using the Amazon web service

The Amazon.com web service is one of a small but growing number of commercial web services that are now becoming available on the Internet. At the moment, many of these services are more experimental than serious, and there are still minor interoperability issues between SOAP implementations from different vendors. It is likely that real business transactions over the Internet using web services will not take place in any volume until the security features are fully defined, implemented, and deployed. However, as you’ll see in the rest of this book, there is already a lot of functionality available for use and for developers to become familiar with.

---

^[4] In fact, you have to go through several steps before reaching this screen. Refer to Chapter 7 for a description of the complete process.

^[5] Although this code explicitly supplies the web service address, you’ll see in Chapter 6 that you can also create JAX-RPC applications that obtain the service address directly from the WSDL document.