| Sun ONE Studio 4, Enterprise Edition for Java Tutorial |    
|
| Sun ONE Studio 4, Enterprise Edition for Java 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 4 IDE to create web services for the DiningGuide application.
This chapter covers the following topics:
For a complete discussion of Sun ONE Studio 4 web service features, see Building Web Services from the Sun ONE Studio 4 Programming series. This book is available from the Sun ONE Studio 4 portal's Documentation page at http://forte.sun.com/ffj/documentation/index.html. For information on specific features, see the Sun ONE Studio 4 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 4 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 the client proxy, 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 proxy pages 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 proxy.
2. The SOAP client proxy 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 proxy.
6. The SOAP client proxy passes the response to the JSP page, which displays the response on a web page.
Create the tutorial's web service with the following tasks:
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 web service module:
1. In the Explorer, right-click the mounted DiningGuide2 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 DiningGuide2 directory.
3. Right-click the WebService package and choose New Web Services Web Service.
The New wizard displays the Web Service pane.
4. Type DGWebService in the Name field, make sure the Multitier option is selected for the Architecture type, and click Next.
The Methods pane of the New wizard is displayed.
5. Expand the Data, DiningGuideManager(EJB), and Business Methods nodes.
6. Use Control-Click to select all the DiningGuideManager's business methods:
The Methods pane 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:
The SOAP RPC URL property locates the SOAP rpcrouter Servlet of the JAX-RPC runtime on the application server. This property includes a string called the context root or web context. This string must match the web context property of the J2EE application WAR node that you will create later in Specifying the Web Context Property.
To set the SOAP RPC URL property:
1. Display the properties of the DGWebService node.
Select the DGWebService node and view the properties in the Properties window. If the Properties window is not displayed, choose View Properties.
2. Display the property editor for the SOAP RPC URL property.
Click once in the value field, then click the ellipsis button that appears to display the editor.
3. Change the first instance of the string DGWebService in the URL to DGWSContext, so that the entire URL is:
http://localhost:80/DGWSContext/DGWebService
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 four classes to implement the web service, three of which are for a generated EJB component.
To generate a web service's runtime classes:
Right-click the DGWebService node and choose Generate Web Service.
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:
Testing your web service requires the following tasks:
1. Creating a test client that includes:
2. Specify the web context property of the web service WAR file
3. Deploying the test application
4. 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 New Client.
The New 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 J2EE Application.
4. Type DiningGuideApp 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.
5. Right-click the DiningGuideApp node and choose Add Module.
The Add Module to Application dialog box appears.
6. In the dialog box, expand the DiningGuide filesystem and both the Data and WebService packages
7. Using Control-Click, select both the DiningGuideManager_EJBModule and the DGWebService nodes.
The dialog box looks like this:
8. Click OK to accept the selection and close the dialog box.
9. In the Explorer, expand the DiningGuideApp J2EE application.
Both the DGWebService's WAR and EJB JAR files have been added to the application, as well as the DiningGuideManager_EJBModule:
Now specify a web context for the new J2EE application in the web service's WAR file. This must be the same context that you specified in Specifying the Web Service's SOAP RPC URL.
1. Display the Properties window of the DGWebService_War file inside the DiningGuideApp application.
Select the node and view the properties in the Properties window. If the Properties window is not already displayed, choose View Properties.
2. In the Web Context field, type DGWSContext for the property value.
You are now ready to deploy the DiningGuideApp test application.
You must first undeploy the any deployed test applications before you deploy the session bean's test application, for the same reason given in Deploying and Executing the Test Application. (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 Undeploying the Entity Bean Test Applications.
|
Note - Make sure the Oracle server is running before you deploy the test application or any other J2EE application that accesses the database. In addition, make sure the Sun ONE Application Server 7 server is running and is the default application server of the IDE. See Making the Sun ONE Application Server the Default Server for information. |
To deploy the DiningGuideApp application:
1. In the Explorer, right-click the DiningGuideApp node (
) and choose Deploy.
A progress monitor window shows the deployment process running. You might see a message and a prompt like the following:
....implements the java.rmi.Remote inteface. Do you wish to mark it as an RMI object?
If this appears, respond with No To All.
2. 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 window of the Explorer displays a server1(hostname:hostport) node.
3. Click the Editing tab of the IDE to return to the Explorer.
4. Expand the DGWebServiceClient$Documents node under the WebService package.
The following supporting items have been created:
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 4 portal's Documentation page at http://forte.sun.com/ffj/documentation/index.html.
1. In the Explorer, right-click the DGWebServiceClient node (
) and choose Deploy.
Check the messages in the Output window for completion of the deployment process.
2. Right-click the DGWebServiceClient node again, and choose Execute.
The IDE automatically starts the Sun ONE Application Server 7 web server, launches the default web browser, and displays the client's generated welcome page (DGWebServiceClient_SOAP.html):
This page lets you to test whether the operations work as expected.
3. Test the getCustomerreviewsByRestaurant 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 DiningGuideApp web service turns the SOAP message into a method invocation of the DiningGuideManager.getCustomerreviewsByRestaurant method. This method returns a collection that the generated JSP page, getCustomerreviewsByRestaurant_SOAP.jsp, displays as a collection of customer review data. The XML wrapper containing the return value is displayed as shown.
The data includes all the records entered for the French Lemon restaurant. Refer to TABLE 1-3 to verify the data. Or you can verify the data by starting the Oracle console and running the following SQL statement:
The results show what CustomerReview records you have entered.
4. Use the Back button on your browser to return to the welcome page.
5. 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 to 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:
7. Use the Back button on your browser to return to the welcome page.
8. 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 Using the Test Client to Test the Restaurant Bean) 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 proxy 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 proxy 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 on your operating system's file system, named DGWebService.wsdl.
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 proxy from the WSDL file:
1. On your operating system's file system, create a directory and place the DGWebService.wsdl file in it.
2. In the Sun ONE Studio 4 Explorer, choose New Mount Filesystem.
3. Select Local Directory and click Next.
The Select Directory pane of the New wizard is displayed.
4. Find the directory you created in Step 1 and click Finish.
The directory is mounted in the Explorer.
5. Right-click the new directory and choose New Java Package.
6. Type MyClientPackage in the Name field and click Finish.
MyClientPackage is displayed in the mounted directory.
7. In the Explorer, right-click MyClientPackage and choose New Web Services Web Service Client.
8. Type NewClient in the Name field.
9. Make sure the package is the MyClientPackage package.
10. For the Source, select the Local WSDL File option and click Next.
The Select Local WSDL File pane of the New wizard is displayed.
11. Expand the directory you created in Step 1 and the MyClientPackage package. Select the DGWebService WSDL file and click Finish.
A new client node (
) appears in the Explorer.
12. Right-click the NewClient client node and choose Generate Client Proxy.
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 4 provides a single-user internal UDDI registry to test this process, and the StockApp example, available from the Sun ONE Studio 4 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 4, Enterprise Edition for Java Tutorial | 816-7860-10 |
|
Copyright © 2002, Sun Microsystems, Inc. All rights reserved.
