Developing an Amazon Web Services Client

By Beth Stearns and Rakesh Garishakurthi, March 2003  


Sun Microsystem's Java 2 Enterprise Edition (J2EE) platform, coupled with the Sun ONE Studio 4 Enterprise Edition product, provides an environment that greatly simplifies the process of developing a Web Services client. The J2EE 1.3 platform incorporates the Java Web Services Developer Pack (Java WSDP), which includes the Java technologies needed to develop and deploy Web Services and their clients. In addition to simplifying the development process, Sun ONE Studio 4 takes care of many of the administrative tasks associated with developing and deploying a Web Service client application. In contrast to other IDEs on the market, Studio tightly integrates the various Web Service technologies.

The example in this article uses a Web Service that -- a large seller of books, CDs, and other products -- has created so that client applications can browse their product catalog and place orders. Your client can access the Amazon Web Services using either XML over HTTP or a remote procedure call API with a Simple Object Access Protocol (SOAP) interface. Both techniques return structured data (product name, manufacturer, price, and so forth) about products at, based on such parameters as keywords and browse tree nodes. To make it possible to use the service, has provided a Web Services Definition Language (WSDL) file, which contains the definition of the Web Service, the messages that can be sent to the service, and so forth. A developer with access to this WSDL file can write a client application to use the Amazon Web Service.

This article shows you how to use Sun ONE Studio 4 to create a client that accesses the Amazon Web Service. A Web Service client can be a simple client based on JavaServer Pages (JSP) technology, or it can be more sophisticated and use the Swing APIs. This article shows you how to use the tool to develop a Swing-based client that communicates to the Amazon Web Service through proxy or stub classes generated from the WSDL file. The communication is via SOAP and relies on remote procedure calls implemented with the Java API for XML-based Remote Procedure Call (JAX-RPC) runtime. It is this remote procedure call mechanism that enables a remote procedure call from a client to be communicated to a remote server.

What's Covered in this Article

  • Example application
  • Background
  • Setting up the environment, including installing and downloading all necessary software
  • Setting up Sun ONE Studio
  • Using Sun ONE Studio to generate SOAP messages and proxy classes
  • Writing the Swing components for the client
  • Writing the proxy class to connect to the Web Service

The Example Web Services Client Application

The example client application is a Swing client that searches the Amazon catalog for books whose subject matches a user-selected topic. The application displays ten books that match the chosen topic, and shows the author name, book title, list price, Amazon discount price, and the cover icon. The user may optionally view one review per displayed title.

You will write five Java classes for this application.

  • class includes the code to communicate with the JAX-RPC proxy or stub classes generated for you by Sun ONE Studio.
  • class is the main Swing component. In addition to its graphic functions, it instantiates the AmazonProxy class.
  • Swing component displays individual book detail information.
  • Swing component lets the user select categories of books from Amazon's catalog.
  • Swing component displays review comments on a particular book.

Note that the four Swing component classes have corresponding .form files that Sun ONE Studio generates to depict the GUI you design.

This application has been intentionally kept simple to illustrate how to create Web Service clients. It is not intended to showcase the entire range of functionality available to an application through the Amazon Web Services, nor is it intended to illustrate all the capabilities of a Swing client.

Figure 1 gives a quick view of the application's GUI interface. In the first screen, the user selects from the various available book categories.

Figure 1: Client Application Category Selection Screen

Figure 2 shows a sample of the kind of data that the client can retrieve from the Amazon Web Service.

Figure 2: Matching Book Display
Click image to enlarge

If the user clicks a title's See Review button, the example client application displays a review of that book, shown in Figure 3.

Figure 3: Book Review
Click image to enlarge


This example application uses Java bindings or classes generated from the WSDL description and the JAX-RPC runtime for the remote access to the service (JAX-RPC over SOAP), rather than using the option of XML over HTTP. By using JAX-RPC and SOAP, you're shielded from XML processing details, particularly parsing and transforming the XML document, and the application can be written entirely using Java technology. Sun ONE Studio provides extensive support for accessing Web Services via JAX-RPC over SOAP, because the SOAP access approach allows a richer API, and potentially a deeper Web Service provider access, compared to the HTTP access approach.

The XML over HTTP option also passes information between the Web Service and the client as XML documents. The client must transform these XML documents, using XSLT, so that the data can be displayed on a Web page.

JAX-RPC defines Java APIs that Java applications use to develop and access Web Services regardless of the platforms upon which they are deployed or the language in which they are coded. In JAX-RPC, remote procedure calls are represented by an XML infoset -- SOAP -- carried over some network transport (in this case, HTTP). SOAP is a lightweight, XML-based protocol for exchanging information in a distributed environment. The core of this protocol, a SOAP envelope, defines a framework for describing a message's contents and how to process it.

WSDL specifies an XML format for describing a Web Service as a set of endpoints operating on messages. WSDL describes the Web Service in a standard format: it specifies the service's location and the operations exposed by the service.

Setting Up the Environment

Before you can get started, you must install the necessary software and obtain a copy of Amazon's Web Services WSDL file (links below). You should also obtain a copy of the Amazon developer's license, since you need to pass this license token as a parameter when making a request to the service.

Install Sun ONE Studio Enterprise Edition and Related Software

To follow the example presented in this article, you should install the Sun ONE Studio 4 update 1 Enterprise Edition development environment. If you don't already have this product, you can download a trial copy at no charge. You can go directly to the product page and select the Enterprise Edition for Java product from the Trial Downloads page. The download page explains what you need to do to download the Sun ONE Studio products. It also tells you what other software you might need to install, such as the Java 2 Platform, Standard Edition (J2SE), v 1.4.1 software, and how to obtain that software. Download the correct version of Sun ONE Studio (and the J2SE software, if need be) for your system and follow the installation instructions that come with these products.

Note that installing Sun ONE Studio also installs the J2EE 1.3 software, the Java WSDP software, and a default server, Apache Tomcat 4. It also includes the JAX-RPC runtime (part of the Java WSDP), which is essential for this example.

The example uses the Apache Tomcat 4 server, which is included in the software package and is available to everyone -- so it's a good server to use for test implementations such as this. However, for production purposes, you may prefer to use the Sun ONE Application Server or any other J2EE-compliant Web server.

Obtain the Amazon Web Services WSDL File

Through its Web Service, has expanded its Web site so that it is not limited to browsing by individual customers, and its partner businesses are not restricted to merely linking to the site. The Amazon Web Service lets Web applications dynamically make calls to the Amazon database (its catalog), extract information about its complete product line, and purchase products. Applications make the calls to the Amazon Web Service and receive responses containing the very latest data in real time.

Amazon has made available an entire toolkit, including documentation and sample programs, for accessing their Web Services. You can download this toolkit from their site. For this article, you only need to obtain a copy of the Amazon Web Services Web Services Definition Language (WSDL) file, called AmazonWebServices.WSDL. The WSDL file is an XML file that describes the Web Service, and is necessary for passing messages to and from the service using SOAP.

Be sure to register with the Amazon Web Services and obtain a developer license or token. Copy the Amazon WSDL file to your local directory through your browser. Point your browser to and use the save option from your browser to save the WSDL file to your local directory.

This example places the WSDL file in the top directory for its Web Services client: D:\amazonwebservice.

Developing the Web Client Application

Although you can manually develop a Web Services client using the J2EE platform and the Java WSDP APIs and scripts, this article shows you how to create your Web client application using Sun ONE Studio 4 Enterprise Edition. This way of creating a Web Services client is much easier and less prone to error.

Set the Development Options in Sun ONE Studio

Begin by starting Sun ONE Studio, since the development work is done from within it. Once Sun ONE Studio is running, verify that the development options are set correctly.

Set the Default Web Server

You must have a Web server container installed and running for this example to work. This example deploys the Web Services client to the Apache Tomcat 4.0 Web server, so make sure Apache Tomcat 4.0 is set to be the default server.

To set Tomcat as the default server:

  1. Select the Runtime tab in the Explorer window.
  2. Expand Server Registry, then Default Servers.
  3. Right click the Web Tier Applications and select the Set Default Server option.
  4. Once Tomcat is set as the default Web tier server, start the server.
  5. Expand Installed Servers, then Tomcat 4.0
  6. Right click Internal [Not Running] and select the Start Server option.

Figure 4 shows the screen for setting the default application server and starting it.

Figure 4: Setting Default Server and Starting the Server
Click image to enlarge

Mount the Directory

Prior to starting Sun ONE Studio, you should have copied the AmazonWebServices.WSDL file to the local directory in which you plan to place the Web Services client (as described earlier). Mount this directory so that Sun ONE Studio includes it in the required class paths. A directory that has been mounted appears in the Explorer [Filesystems] window. As mentioned previously, this example mounts the directory called amazonwebservice, which happens to be located on its D drive ( D:\amazonwebservice).

From the main window's File pull-down menu, select Mount Directory. This opens a wizard screen, from which you select Local Directory. Then, within the wizard, navigate to the directory you want to mount, select it. and click Finish.

Create a Client Folder

You must create a folder to hold the Web client. Later, you use this folder as the package name for your client. Right click the directory you are using for your Web Services client, then select New->Folder. (Figure 5.) You are prompted for a name for the new folder. This example creates a new folder, which it calls myamazonclient, within its amazonwebservice directory.

Figure 5: Create a New Folder for the Client
Click image to enlarge

The Explorer window shows the new folder, myamazonclient, and the WSDL file, AmazonWebServices.wsdl, in the directory amazonwebservices. (Figure 6.)

Figure 6: Directory Containing Client Folder and WSDL File
Click image to enlarge

Create a Web Service Client

You are now ready to create the Web Service client. The Sun ONE Studio wizard guides you through these steps.

  1. In the Explorer [Filesystems] window, right click the folder for the client. This example selects the myamazonclient folder in the directory D:\amazonwebservice.
  2. Select New->All Templates.. then select Web Services->Web Service Client. (Figure 7.) The wizard opens a template for creating a Web Service client.

    Figure 7: Starting the New Web Service Client Wizard
    Click image to enlarge

  3. Specify the client name, its package, and the option to use the local WSDL file. In the template, enter the name of the new Web Services client and select its package by choosing a folder using the browse function. Use whatever name you want for the client. Click the option to use the local WSDL file. The example named the client AmazonClient and selected myamazonclient for the package. (Figure 8.)

    Figure 8: Specifying the Client Name, Package, and Local WSDL File
    Click image to enlarge

  4. Select the WSDL file that you copied to your local directory. The example selects the AmazonWebService.wsdl file in the myamazonclient directory. (Figure 9.)

    Figure 9: Select the WSDL File
    Click image to enlarge

    Sun ONE Studio creates the new Web Services client in the specified package. (Figure 10.) Right click the client and view its properties.

    Be sure that the SOAP runtime property is set to JAXRPC. The JAX-RPC runtime is the means by which the Swing client makes remote calls to the Web Services. The Welcome Page property shows you a simple HTML page that Sun ONE Studio has generated, and which you can use later to access the different methods exposed by the WSDL file on Amazon's Web Service.

    The Amazon developers designed their Web Services to be accessed either via XML over HTTP or using a remote procedure call API with SOAP. When data is retrieved using XML over HTTP, it must be parsed or transformed to extract information (such as by using XSLT, or Extensible Stylesheet Language Translation) and reformatted into a Web page. Data can also be retrieved using JAX-RPC and sending and receiving SOAP-encoded messages. SOAP messages are well-suited to XML data binding; the messages can be represented as Java objects, making them easier to manipulate programmatically with JAX-RPC.

    Figure 10: AmazonClient Web Service Client and its Properties
    Click image to enlarge

  5. To generate the Client Proxy, right click the Web Service client and select Generate Client Proxy. (See Figure 11.)

    Figure 11: Generating the Client Proxy
    Click image to enlarge

    Sun ONE Studio reads the information in the WSDL file and generates two sets of files. (Figure 12.)

    Figure 12: Generated Client Proxies

    One set of files are SOAP documents that let you test the Amazon Web Service via a browser and HTML. Sun ONE Studio generates a test client-- a simple JSP page -- that lets you invoke these operations. It places these files in the subdirectory AmazonClient$Documents.

    Sun ONE Studio also generates a set of Java classes or objects from the WSDL file, which it places in the subdirectory AmazonClientGenClient. These classes, considered client-side implementation classes, are stub files that enable the client application to get a handle to the Amazon Web Service endpoint and to invoke the operations exposed by the WSDL file on Amazon's Web Service interface. The example Swing client uses these generated Java classes, via JAX-RPC, to access the Web Service.

  6. It's very simple to execute the HTML client. Just right click the client for which you just generated the client proxy, and select Execute.

Figure 13: Execute the HTML Client

Sun ONE Studio completes whatever assembly and deployment tasks are required, starts the server (if it is not already running), and displays the simple test HTML page (the welcome page for the client) in a browser window. This is useful for testing a Web Service. You could also use these generated SOAP documents as a start to creating a more interesting JSP-based client. (For this test JSP page to work correctly, you must complete the request parameters according to Amazon's guidelines, which you can find in their toolkit documentation.)

Figure 14: Keyword Search Request Form
Click image to enlarge

For example, to perform a keyword search (as shown in Figure 14), you need to enter values for these parameters as indicated in the following list. (Note that your application client will programmatically be setting these same parameter values. See Set the parameter values, below.)

  • keyword: the key for the search, such as "food" or "EJB." The keyword only applies to this type of request.
  • page: an integer indicating the number of pages with matching data that the search request returns. One page contains up to 10 matching results.
  • mode: the Amazon product line, such as books, music, electronics, and so forth.
  • tag: the Amazon Associates identifier, if you have one. Otherwise, you can use the default identifier: webservices-20 or your developer's 14-digit token.
  • type: set type to either lite or heavy, depending on how much information you want returned in the response document.
  • dev-tag: the Amazon developer's 14-digit token (or 14 zeros).
  • sort: set to null.
  • variation: set to null.
  • locale: set to null.

Note: You should change the input proxy if you are working behind the firewall.

Figure 15 shows an example of a completed product keyword search request form.

Figure 15: Completed Product Keyword Request
Click image to enlarge

After you enter these values for the respective parameters, select Invoke, which appears at the bottom of the browser page. The request executes and the browser page shows a table of attributes and their values. (Figure 16)

Figure 16: Response to Product Keyword Request
Click image to enlarge

Creating the Application as a Swing Client

Now, let's look at how to create this Web client application as a Swing client. As noted earlier, the application consists of five classes: four classes are Swing components that pertain to the application GUI, and one class serves as a proxy to invoke the Web Services methods on the generated Java classes that are in the AmazonClientGenClient subdirectory. These Swing components have corresponding .form files which are generated by Sun ONE Studio's Form Editor. You can find all the Java classes and form files in the AmazonClientCode zip file . Unzip this file into the myamazonclient directory.

You create the classes for the client application in the client folder. This example creates them in the myamazonclient folder.

Note that this article assumes that you know how to code these GUI classes. If you are not already familiar with the Java Foundation Classes and the Swing components, look here for more information. You can also find help on using Sun ONE Studio to create JFC classes and Swing components through the Sun Developer Connection. Rather than take you through the details of developing the Swing classes, this article focuses on the code you need to write to enable your Swing client to access the Amazon Web Service.

Create the Main Application Class and Swing Components

The main client application class, , is a javax.swing.JFrame class that initializes the form for the client. This class, along with the three classes that extend javax.swing.JPanel, create the look and feel of the client application.

To create the class, right click the client folder, myamazonclient, then select New->GUI Form->JFrame. (Figure 17.)

Figure 17: Create a Swing Component
Click image to enlarge

Sun ONE Studio creates a new Java class that extends JFrame and includes any required methods and default values. Use the associated wizard to define the class, or enter the code directly in the source editor. Sun ONE Studio has a form editor through which you can design the layout for the GUI screen, place buttons on the screen, and so forth.

In a similar fashion, use Sun ONE Studio to create the classes that control the various panel displays within the screen and that render the returned data. These classes ( , , and ) extend javax.swing.JPanel.

To create these panel classes, right click the client folder and select New->GUI Form->JPanel. (Figure 17.) Complete the code for the three panel classes and the main frame class. Feel free to try out the Sun ONE Studio form editor, which opens automatically when you double-click a Swing component class, and change the look and feel of the application.

Instantiating the Amazon Proxy

AmazonServices starts the client application, initializes it, and controls the application's progression through its several screens. From the perspective of a Web Service client, the most interesting thing is that AmazonServices instantiates an AmazonProxy object. It is AmazonProxy that enables access to the JAX-RPC generated methods and subsequently to Amazon's Web Services.

AmazonServices instantiates a new AmazonProxy within its showScreen method:

private void showScreen() {
  myamazonclient.AmazonProxy amp = new AmazonProxy();

Create the Proxy Class

The proxy class -- in this example -- is of most interest, since this class invokes the methods in the generated stub classes to access the Amazon Web Service. The proxy class uses the JAX-RPC runtime through the javax.xml.rpc.Stub class.

Create a new Java class for AmazonProxy, in a similar fashion to the way you created the JFrame and JPanel classes. Right click the myamazonclient client folder, then select the File->New->Classes->Class option in the Explorer window. (Figure 18.) Sun ONE Studio creates a Java class for you.

Figure 18: Create a Java Class
Click image to enlarge

Write the Proxy Code

To write the code in the proxy class, you need to know how to use the JAX-RPC API to access a Web Service. This article takes you through the code in the AmazonProxy class, which you write in Sun ONE Studio's Source Editor. For a more in-depth explanation, refer to the Java Web Services Tutorial and other articles on Web Services.

The code in AmazonProxy must do the following:

Get access to the JAX-RPC API and runtime. Import the javax.xml.rpc.Stub class so that you have access to the JAX-RPC API and runtime.

import javax.xml.rpc.Stub;

Import the generated Amazon classes. The example imports the generated classes in the AmazonServicesGenClient subdirectory.

import myamazonclient.AmazonServicesGenClient;

Get access to the Amazon service's port. Clients access a Web Service via the service's port, which in turn passes a client request to the service's endpoint, ultimately invoking the service's method on the service interface. To gain access to the Web Service port, the client must first get a handle to the service's generated stub file,, by using methods in the impl file, The stub class includes the location of the Amazon service port: The impl file includes the getAmazonSearchPort method, which returns a handle to the stub file and access to the port.

To do this, instantiate an instance of the generated AmazonSearchServices_Impl class and invoke the AmazonSearchServices_Impl.getAmazonSearchPort method. You must cast the method's returned object to a javax.xml.rpc.Stub type. The example invokes getAmazonSearchPort after instantiating AmazonSearchService_Impl, casts its return value to Stub, and sets the object into stub.

Stub stub = (Stub)
  (new AmazonSearchService_Impl().getAmazonSearchPort());

Then, cast the Stub object returned by getAmazonSearchPort to an AmazonSearchPort type and set an A mazonSearchPort object equal to this cast Stub object. The example casts stub to an AmazonSearchPort type, then sets the AmazonSearchPort object asp equal to stub.

AmazonSearchPort asp = (AmazonSearchPort) stub;

Set the parameter values. Set up the parameters for the Amazon Web Service methods that the client application will invoke. In this example, the client requests that the product mode books be selected by a particular keyword. AmazonProxy sets up the parameters by instantiating a new KeywordRequest object; the KeywordRequest class was generated from the WSDL description. KeywordRequest's constructor sets the appropriate values into the new object, using the values passed to it when AmazonProxy invoked the new method. (In the same manner, the client can use other generated classes to search the catalog by a key phrase, browse by nodes, get shopping cart data, and so forth.)

KeywordRequest kwr = new KeywordRequest

When instantiating the object, you must be careful to correctly set the parameters that KeywordRequest (or any other Amazon Web Service request) expects. Here, AmazonProxy sets the variable type to the category type selected by the user. This is the keyword for the search. The number 1 refers to the number of pages of matching book titles that will be returned. The third value, books, is the product mode for the search. The associate's identifier and/or developer token (which you were given when you registered with Amazon) is passed as the fourth and sixth parameters. Amazon allows two types of searches -- heavy and lite -- and this is indicated by the fifth parameter. The last parameter, left as null here, lets you specify a sort option.

Invoke the search request. Invoke the Web Service's keywordSearchRequest method through the AmazonSearchPort stub reference, passing it the KeywordRequest object you just instantiated. This example invokes the search method, passing it the kwr object, through the asp object. The Amazon Web Service returns the information as a ProductInfo type. ( is also a generated class.)

ProductInfo pinfo = asp.keywordSearchRequest(kwr);

Extract the data from the response. Extract the individual pieces of data that you are interested in from the returned object. Use the generated helper class to extract the returned data into an array. The file contains an array with an element for each piece of data from the Amazon catalog. This examples retrieves the data into a Details object.

Details[] details = pinfo.getDetails();

Once the information is in the Details object, set up a loop to extract the elements of interest for each book in the array. Keep in mind that the array potentially holds data on up to ten different books. (There may be data on less than ten books, if there were less than ten matches to the search parameters.)

Here is the portion of the AmazonProxy class that accesses the Web Service, and sends the request and receives the response:

package myamazonclient;
import myamazonclient.AmazonClientGenClient.*;
import javax.xml.rpc.Stub;
import java.util.Vector;
public class AmazonProxy{
  public AmazonProxy() {
  public Vector getBookTypes() {
    Vector v = new Vector();
    v.addElement("Blue Prints");
    v.addElement("Web Services");
    return v;
  public String[] getBookNames(String type) {
    String[] books;
      Stub stub = (Stub) (new
      AmazonSearchPort asp = (AmazonSearchPort) stub;
      KeywordRequest kwr = new
      ProductInfo pinfo = asp.keywordSearchRequest(kwr);
      Details[] details = pinfo.getDetails();
      String newline = System.getProperty("line.separator");
      books = new String[details.length];
      imageURL = new String[details.length];
      bookReviews = new String[details.length];
      for (int i=0;i<details.length;i++) {
        // extract data from details vector
    } catch (Exception e) {
      //handle exception
  public  String[] getImageURL() {
    return imageURL;
  public String[] getBookReviews() {
    return bookReviews;
  private String[] imageURL;
  private String[] bookReviews;

Compile, Build, and Execute the Client Application

With Sun ONE Studio, you can do the compilation, build, and execute steps separately, or you can have Sun ONE Studio do all the steps at once. Use Execute to compile, build, and execute the application in one step. To perform these steps separately, use Compile to compile the Java classes and Build to assemble and deploy the application.

Before executing this code, you should check your proxy setting if you are behind the firewall. To set the proxy, follow these steps:

  • Right click AmazonServices in the Explorer window, then select Properties.
  • Select the Execution tab and choose the External Execution option for the executor.
  • Click on the property's ellipsis (...) button and select External Process.
  • Click again on the property's ellipsis (...) and write
    -Dhttp.proxyHost=yourproxyhostname  -Dhttp.proxyPort=yourproxyport
    in the beginning of the Arguments text box.
  • Click OK.

This example uses Execute. Right click AmazonServices in the Explorer window, then select Execute.

Figure 19: Compiling and Executing the Client Application

Sun ONE Studio compiles the five classes in the application. It then performs the necessary assembly and deployment tasks, starts the Tomcat server if necessary, and runs the client.


This article showcases the Sun ONE Studio 4 product from Sun Microsystems, Inc. It illustrates Sun ONE Studio's powerful and comprehensive functionality that allows for rapid application development, while at the same time shielding developers from the complexities of the Web Service infrastructure. Using an example of creating a Swing-based Web Service client with Sun ONE Studio, it shows how to set up and create the client, and illustrates how you can use the classes generated by Sun ONE Studio to write code that accesses a Web Service such as Amazon's. The article demonstrates how Sun ONE Studio simplifies many of the development and deployment tasks for you so that you can concentrate on writing the application code.

With the knowledge gained from this article as a foundation, you can use Sun ONE Studio to write production-quality clients that can be deployed on any J2EE-compliant Web server, such as the Sun ONE Application Server. Sun ONE Studio can handle most, if not all, of the packaging and deployment details for you, especially when the target platform is the Sun ONE Application Server. For deploying to other Web servers, you should refer to their specific product documentation.

See Also

Sun ONE Studio product page

Amazon Web Services Developer Toolkit

Amazon developer token

Swing tutorial

Java Web Services tutorial

Further reading on Web Services

Latest information on J2EE and related technologies

AmazonClientCode zip file

About the Authors

Beth Stearns is a principal partner of ComputerEase Publishing, a computer consulting firm she founded in 1982. She has written documentation for many enterprise-related products from Sun and other companies, including Oracle Corporation, Borland, and Rational. Beth received a B.S. degree from Cornell University and a master's degree from Adelphi University.

Rakesh Garishakurthi is a Sun engineer specializing in Sun ONE platform solutions and Web services related technologies. You can often find him at the Sun ONE Software Forum working with developers on the Sun ONE Application Server.