| Sun ONE Studio 5 J2EE Application Tutorial |    
|
| Sun ONE Studio 5 J2EE Application Tutorial |
|
| C H A P T E R 4 |
|
Creating the DiningGuide Application's Web Service |
This chapter describes how to use the Sun ONE Studio 5 IDE to create web services for the DiningGuide application. This chapter covers the following topics:
For a complete discussion of Sun ONE Studio 5 web service features, see Building Web Services from the Sun ONE Studio 5 Programming series. This book is available from the Sun ONE Studio 5 portal's Documentation page at http://forte.sun.com/ffj/documentation/index.html. For information on specific features, see the Sun ONE Studio 5 online help.
In this chapter, you will create the DiningGuide application's web service. As part of this procedure you will explicitly create a number of components and generate some others.
For more complete information about web services and how to create and program them, see Building Web Services. See also the Sun ONE Studio 5 online help for specific web service topics and procedures.
In this tutorial, you develop your web service's functionality by creating references in the web service to the methods you want clients to be able to access.
After creating your web service and its method references, you generate its runtime classes. You do not work directly on the runtime classes, but you will see them generated in the package containing the web service.
When you create a client and generate its files, supporting client pages are created. You will use these client pages for testing the web service. You can also use them as a starting point or a guide for developing a full-featured referenced method. These client files include a JSP page for each reference method, a JSP page to display errors for the web service, and an HTML welcome page to organize the method JSP pages for presentation in a web browser.
The welcome page contains one HTML form for each of the JSP pages generated for the referenced methods. If a method requires parameters, the HTML form contains the appropriate input fields. You test the methods by inputting data for each parameter, if required, and pressing the method's Invoke button. The following actions then occur:
1. The JSP page passes the request to the SOAP client file.
2. The SOAP client file passes the request to the JAX-RPC runtime system on the application server.
3. The JAX-RPC runtime system on the application server transforms the SOAP requests into a method call on the appropriate method referenced by the DiningGuide web service.
4. The method call is passed to the appropriate business method in the EJB tier.
5. The processed response is passed back up the chain to the SOAP client file.
6. The SOAP client file passes the response to the JSP page, which displays the response on a web page.
Creating the tutorial's web service requires two steps:
1. Creating the logical web service for the application.
2. Generating the web services runtime classes.
Use the New Web Service wizard to create the logical web service. The wizard offers a choice of architectures: multitier or web-centric. The DiningGuide application's web service calls methods on the EJB tier components, so choose the multitier architecture.
The wizard also prompts you to select the methods the web service will call, so it can build references to these methods. Select the five business methods of the EJB tier's session bean.
To create the tutorial's logical web service:
1. In the Explorer, right-click the mounted DiningGuide Filesystem and choose
New 
Java Package.
The New Package dialog box is displayed.
2. Type WebService for the name and click Finish.
The new WebService package appears under the DiningGuide directory.
3. Right-click the WebService package and choose New All Templates.
The New wizard is displayed, showing the Choose Template page.
4. Expand the Web Services node, select Web Service and click Next.
The New wizard displays the Web Service page.
5. Type DGWebService in the Name field, select the following options:
The Select Methods page of the New wizard is displayed.
7. Expand the Data, DiningGuideManager(EJB), and Business Methods nodes.
8. Use Shift-Click to select all the DiningGuideManager's business methods:
The Methods page looks like this:
The new DGWebService web service (the icon with a blue sphere 
) appears under the WebService package in the Explorer. If you expand this node, the Explorer looks like this:
Before you can assemble the web service as a J2EE application and deploy it for testing, you must generate the web service's runtime classes. When the architecture is multitier, the IDE generates many classes to implement the web service, three of which are for a generated EJB component.
|
Note - Make sure your admin server is running and your application server is set as the default server. |
To generate a web service's runtime classes:
1. Right-click the DGWebService node and choose Generate Web Service Files.
When the operation is complete, the word "Finished" appears in the IDE's output window. Runtime classes that are EJB components for implementing the SOAP RPC web service appear in the Explorer:
2. Display the DGWebService node's properties.
Either view them in the Properties window beneath the Explorer, or right-click the node and choose Properties from the contextual menu.
3. Verify that the value of the SOAP RPC URL property reflects the hostname and portnumber of your application server.
For example, for an application server host name of "tech5" and a port number of "4855," the URL should be as follows:
http://tech5:4855/DGWebService/DGWebService
Testing your web service requires the following tasks:
1. Creating a test client that includes:
2. Deploying the test application.
3. Using the test application to test the web service.
The Web Services test application generates a JSP page for each XML operation in the web service, plus a welcome page to organize them for viewing in a browser. When you execute the test client, you exercise the XML operations from the welcome page.
To test your web service, create a test client and a J2EE application. Add the EJB modules and the web service module to the J2EE application.
|
Tip - When you create the test client, make it the default test client for the web service. Then when you deploy the J2EE application, the test client is deployed as well. |
To create and deploy a client application for your web service:
1. In the Explorer, right-click the DGWebService node (
) and choose Create New Web Service Test Client.
The Create a New Web Service Test Client dialog box is displayed.
The option to make this client the default test client for the web service is selected by default.
2. Accept all the defaults and click OK.
A new client node appears in the Explorer (
). Now create a new J2EE application for the web service.
3. Right-click the WebService package and choose New All Templates.
4. In the New wizard, expand the J2EE node, select Application and click Next.
5. Type DGApp in the Name field and click Finish.
The new J2EE application node (
appears under the WebService package.
Now add the web service to the application:
1. Right-click the DGApp node and choose Add Module.
The Add Module to Application dialog box appears.
2. In the dialog box, expand the DiningGuide filesystem and both the Data and WebService packages.
3. Using Control-Click, select both the DiningGuideManager_EJBModule and the DGWebService nodes.
The dialog box looks like this:
4. Click OK to accept the selection and close the dialog box.
5. In the Explorer, expand the DGApp J2EE application.
Both the DGWebService's WAR and EJB JAR files have been added to the application, as well as the DiningGuideManager_EJBModule:
You must first undeploy the any deployed test applications before you deploy the session bean's test application, for the same reason given in . (Because they use the same JNDI lookups to the Restaurant and Customerreview beans that will be used by the web service test application.)
For the procedure for undeploying an application, see .
To deploy the DGApp application:
1. Undeploy any deployed DiningGuide test applications.
Refer to for this procedure, if it is necessary. Make sure you also restart the application server.
2. In the Explorer, right-click the DGApp node (
) and choose Deploy.
A progress monitor window shows the deployment process running.
3. Verify that the application is deployed.
A Progress Monitor window shows the progress of the deployment process. The server instance's log file tab on the output window displays progress messages. The application is successfully deployed when you see success messages.
The Execution View window of the Explorer displays a servername(server-hostname:server-port-number) node.
4. Expand the DGWebServiceClient$Documents node under the WebService package.
The following supporting items have been created:
See Building Web Services for more information about these pages.
These files are also referenced under the Generated Documents node under the DGWebServiceClient node.
For an explanation of the details of how SOAP requests and responses are passed between the client and the web service, see Building Web Services, available from the Sun ONE Studio 5 portal's Documentation page at http://forte.sun.com/ffj/documentation/index.html.
|
Note - Make sure the admin server and the PointBase server are running. Make sure your application server is the default application server. |
1. In the Explorer, right-click the DGWebServiceClient node (
) and choose Deploy.
The DGWebServiceClient is deployed. The node is visible under your application server instance's Deployed Web Modules node in the Runtime pane of the Explorer.
2. Right-click the same node and choose Execute.
The IDE deploys the test client, launches the default web browser, and displays the client's generated welcome page (DGWebServiceClient_SOAP.html):
This page lets you test whether the operations work as expected.
3. Test the getCustomerreviewsByRestaurant method by typing French Lemon in the text field and clicking the Invoke button.
A SOAP message is created and sent to the application server. The DGApp web service turns the SOAP message into a method invocation of the DiningGuideManager.getCustomerreviewsByRestaurant method. This method returns a collection to the generated JSP page, getCustomerreviewsByRestaurant_TAGLIB.jsp, which displays the returned data in a formatted table, as shown.
The data includes all the records entered for the French Lemon restaurant.Verify the data by starting the Pointbase console and running the following SQL statement:
The results show what CustomerReview records you have entered.
4. To view the SOAP message, click the View SOAP Request/Response link.
This is displays the returned data as an XML-wrapped SOAP message.
5. Use the Back button on your browser to return to the welcome page.
6. Test the createCustomerreview operation by typing French Lemon in the restaurantname field, and whatever you want in the other two fields.
This method takes a complex Java object as an input parameter. The generated JSP page, createCustomerreview_SOAP.jsp, prompts for the three inputs. These are then converted into a Customerreview object and passed as a SOAP message. This message is sent to the application server, where it is turned back into a Java method call and sent to the DiningGuideManagerEJB component. The result is displayed in the browser:
8. Click the View SOAP Request/Response link.
The SOAP request and response looks like this.
9. Use the Back button on your browser to return to the welcome page.
10. Test the getAllRestaurants operation by clicking its Invoke button on the welcome page.
This method does not require an input parameter. It returns a collection of restaurant data, which the getAllRestaurants_SOAP.jsp page displays as XML:
Notice the Restaurant record you entered when you tested the Restaurant entity bean (see ) is the last record on the page.
You have successfully created a web service for the DiningGuide tutorial. In Chapter 5, you will use a provided Swing client to run the DiningGuide application.
You have learned a convenient method for testing web services if you are a web services developer. However, other development groups in your organization, particularly the client developers, need to test their work against your web service, as well. You can easily provide them with your web service's WSDL file. From this file, they can generate a client files from which they can build the application's client. They can then test the client against your web service, if you provide them with the URL of your deployed web service (and make sure the web server is running).
To make web services available to other developers involves these tasks:
1. The web services developer:
Generating the client files generates the JSP pages required for developing a real client for the application.
The first step in sharing access to the application's web service is to generate a WSDL file for the web service. This is performed by the developers of the web service.
To generate a WSDL file for the web service:
1. In the Explorer, right-click the DGWebService node (
) and choose Generate WSDL.
A WSDL file (the node with a green sphere 
) named DGWebService is created under the WebService package.
You can find this file, named DGWebService.wsdl, in the DiningGuide/WebService directory on your operating system's file system.
2. Make this file available to other development teams.
You can attach the file to an email message or post it on a web site.
The second part of sharing access to the application's web service is to generate all the web service supporting files from the WSDL file. This is performed by the developers of the client.
To generate the web service files and client files from the WSDL file:
1. On your operating system's file system, create a directory and place the DGWebService.wsdl file in it.
For example, create the c:\wsdlHolder directory and paste the file in it.
2. In the Sun ONE Studio 5 Explorer, mount this directory.
3. Right-click the new directory and choose New Java Package.
4. Type MyClientPackage in the Name field and click Finish.
MyClientPackage is displayed in the mounted directory.
5. In the Explorer, right-click MyClientPackage and choose New All Templates.
6. In the New wizard, expand the Web Services node, select Web Service Client and click Next.
The Web Service Client page is displayed.
7. Type NewClient in the Name field.
8. Make sure the package is the MyClientPackage package.
9. For the Source, select the Local WSDL File option and click Next.
The Select Local WSDL File page of the New wizard is displayed.
10. Expand the directory you created in Step 1, select the DGWebService WSDL file, and click Finish.
A new client node (
) appears in the Explorer.
11. Right-click the NewClient client node and choose Generate Client Files.
A Generated Documents node is generated in the Explorer. The expanded Generated Documents node reveals the JSP pages and welcome page required for the client, as shown:
You can now use the client to test the web service, as described in Using the Test Application to Test the Web Service.
When your application is finished, you will probably publish your web service to a UDDI registry, to make it available to developers outside your immediate locale. Sun ONE Studio 5 provides a single-user internal UDDI registry to test this process, and the StockApp example, available from the Sun ONE Studio 5 portal's Examples and Tutorials page at http://forte.sun.com/ffj/documentation/tutorialsandexamples.htmlillustrates how to use this feature. For information on publishing to an external UDDI registry, see Building Web Services.
| Sun ONE Studio 5 J2EE Application Tutorial | 817-2322-10 |
|
Copyright © 2003, Sun Microsystems, Inc. All rights reserved.
