IntroductionSun 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 Amazon.com -- 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 Amazon.com, based on such parameters as keywords and browse tree nodes. To make it possible to use the service, Amazon.com 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
The Example Web Services Client ApplicationThe 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.
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. If the user clicks a title's See Review button, the example client application displays a review of that book, shown in Figure 3. BackgroundThis 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 EnvironmentBefore 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 SoftwareTo 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 FileThrough its Web Service, Amazon.com 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 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 http://soap.amazon.com/schemas2/AmazonWebServices.wsdl 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: Developing the Web Client ApplicationAlthough 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 StudioBegin 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:
Figure 4 shows the screen for setting the default application server and starting it. Mount the Directory
Prior to starting Sun ONE Studio, you should have copied the 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
The Explorer window shows the new folder, Create a Web Service ClientYou are now ready to create the Web Service client. The Sun ONE Studio wizard guides you through these steps.
![]() 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.) 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.)
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. 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) 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
You create the classes for the client application in the client folder. This example creates them in the 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,
To create the
Sun ONE Studio creates a new Java class that extends
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 ( 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
Create the Proxy Class
The proxy class --
Create a new Java class for 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
The code in
Get access to the JAX-RPC API and runtime. Import the import javax.xml.rpc.Stub;
Import the generated Amazon classes. The example imports the generated classes in the 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,
To do this, instantiate an instance of the generated Stub stub = (Stub) (new AmazonSearchService_Impl().getAmazonSearchPort());
Then, cast the 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.
KeywordRequest kwr = new KeywordRequest
(type,"1","books","D3HW0PG66IPLAM","heavy",
"D3HW0PG66IPLAM","");
When instantiating the object, you must be careful to correctly set the parameters that
Invoke the search request. Invoke the Web Service's
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
Once the information is in the
Here is the portion of the
Compile, Build, and Execute the Client ApplicationWith 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:
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. ConclusionThis 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 AlsoAmazon Web Services Developer Toolkit Further reading on Web Services Latest information on J2EE and related technologies About the AuthorsBeth 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. Have a question about programming? Use Java Online Support.
IMPORTANT: Please read our Licensing policy: | ||||||||||
|
| ||||||||||||