C H A P T E R 2 |
Introduction to the Tutorial |
In the process of creating the tutorial example application, you will learn how to build a simple J2EE application using Java Studio Enterprise features.
This chapter describes the application you will build, first describing its requirements, and then presenting an architecture that fulfills the requirements. The final section describes how you use Java Studio Enterprise features--the EJB Builder, the test application facility, and the New Web Service wizard--to create the application.
This chapter is organized into the following sections:
The tutorial application, DiningGuide, is a simple dining guide application that enables users to view a list of available restaurants and their features. The user can also view a list of a selected restaurant's customer reviews, and add a review to a restaurant's record. The restaurant features include the restaurant name, its cuisine type, its neighborhood, address, and phone number, a brief description of the restaurant, and a rating number (1 - 5).
The user interacts with the application's interface as follows:
The interaction of DiningGuide begins when the user executes a client page listing all the restaurant records in the database. The interaction ends when the user quits the application's client. A simple Swing client is provided to illustrate how a user can interact with the application's features. However, other types of clients, such as a web client or another application, could access the business methods of the DiningGuide application.
The following scenarios illustrate interactions that happen within the application, and the application's requirements.
1. The user executes the application's RestaurantTable class.
The application displays the DiningGuide Restaurant Listing window, which displays a list of all restaurants, their names, cuisine type, location, phone number, a short review comment, and a rating from 1 to 5. On the page is a button labeled View Customer Comments.
2. The user selects a restaurant record in the list and clicks the View Customer Comments button for a given restaurant.
The application displays a All Customer Reviews By Restaurant Name window with a list of all the reviews submitted by customers for the selected restaurant.
3. On the customer review window, the user types text into the Customer Name and Review fields and clicks the Submit Customer Review button.
The application adds the customer's name and review text to the CustomerReview database table, and redisplays the All Customer Reviews By Restaurant Name window with the new record added.
4. The user returns to the Restaurant Listing window, selects another restaurant, and clicks the View Customer Comments button.
The application displays a new All Customer Reviews By Restaurant Name window showing all the reviews for the selected restaurant.
The following items list the main functions for a user interface of an application that supports the application scenarios.
The user's view of the application illustrates how the scenarios and the functional specification, described in Functionality of the Tutorial Application are realized.
1. In the Java Studio Enterprise Explorer, right-click the RestaurantTable node and choose Execute.
The IDE switches to Runtime mode. A Restaurant node appears in the execution window. Then, the RestaurantTable window is displayed, as shown:
This window displays the data from the Restaurant table described in Tutorial Database Table Descriptions.
2. To view the customer reviews for a given restaurant, select the restaurant name and click the View Customer Comments button.
For example, select the Bay Fox restaurant. The CustomerReviewTable window is displayed.
In this case, no records are shown, because none are in the database. Refer to TABLE 1-3.
3. To add a review, type in a customer name and some text for the review and click the Submit Customer Review button.
For example, type in New User for the name and I'm speechless! for the review. The application redisplays the customer review window, as shown:
Now, display the reviews of the other restaurant.
4. On the Restaurant List window, select French Lemon and click the View Customer Comments button.
A new customer review list window is displayed, showing the comments for the French Lemon restaurant.
Two customer review records are displayed. Refer to TABLE 1-3 for confirmation.
5. Continue to add and view customer review records.
6. When you are done, quit the application by closing any of the application's windows.
7. To verify that the new customer review records were written to the database, in the IDE, select the Runtime tab of the Explorer.
8. Expand the Databases node, the PointBase connection node, and the Tables node under it.
9. Right-click the CUSTOMERREVIEW table and choose View Data.
A command editor window is displayed, showing any new CustomerReview records you entered in Step 3, for example:
The heart of the tutorial application is the EJB tier that contains two entity type enterprise beans, two detail classes, and a session bean. The entity beans represent the two DiningGuide database tables (Restaurant and CustomerReview); the two detail classes mirror the entity bean fields and include getter and setter methods for each field. The detail classes are used to reduce the number of method calls to the entity beans when retrieving database data. The session bean manages the interaction between the client (by way of the web service) and the entity beans.
FIGURE 2-1 shows the DiningGuide application architecture.
In FIGURE 2-1, the client includes a client proxy, which uses the SOAP runtime system to communicate with the SOAP runtime system on the web server. Requests are passed as SOAP messages. The web service translates the SOAP messages into calls on the EJB tier's session bean's methods. The session bean passes its responses back to the web service, which translates them into SOAP messages to give to the client proxy and ultimately get translated into a display of data or action.
A SOAP request is an XML wrapper that contains a method call on the web service and input data in serialized form.
The elements shown in FIGURE 2-1 are:
You build and test the EJB tier before you build anything else in the tutorial. The EJB tier consists of:
This is automatically created when a test application is built for the session bean.
The client component is a Swing client that displays the application pages. In Chapter 5, you copy code from provided client pages that instantiate the client proxy created in the web service in Chapter 4.
The EJB tier of the DiningGuide application contains two entity-type enterprise beans, two detail classes, and a session bean used to manage the interaction between the client and the entity beans.
The Restaurant bean is an entity bean that uses container-managed persistence (CMP) to represent the data of the Restaurant database table.
Also a CMP-type entity bean, the Customerreview entity bean represents the data from the CustomerReview database table.
This component has the same fields as the Restaurant entity bean, plus getter and setter methods for each field for retrieving this data from the entity bean's remote reference. Its constructor instantiates an object that represents the restaurant data. This object can then be formatted into a JSP page, HTML page, or Swing component for the client to view.
This component serves the same function for the Customerreview entity bean that the RestaurantDetail class serves for the Restaurant entity bean.
This component is a stateless session bean that is used to manage the interaction between the client and the entity beans.
The tutorial building process is divided into three chapters. In the first (Chapter 3), you create the EJB tier and use the IDE's test application facility to test each enterprise bean as you work. Then you create a session bean to manage traffic. This is a common model when creating the web services and the client manually.
In the second chapter (Chapter 4), you create a web service and specify which of the EJB tier's business methods to reference. You deploy the web service, which generates a client proxy, and then you test the client proxy.
In the final chapter (Chapter 5), you install two provided Swing classes into the application and execute them to test the application.
In Chapter 3 you learn how to use Java Studio Enterprise features to:
The EJB Builder wizard automatically creates the various components that make up an enterprise bean, whether it's a stateless or stateful session bean, or an entity bean with container-managed persistence (CMP) or bean-managed persistence (BMP). In Chapter 3, you create two CMP entity beans based on existing database tables, and a stateless session bean.
When you create the entity beans, you learn how to connect to a database during the creation process, and then generate an entity bean whose fields represent the table's columns. The basic parts of the bean are generated into the Java Studio Enterprise Explorer with Java code already generated for the home interface, remote interface, bean class, and (if applicable) the primary key class. You learn how to edit and modify the bean properly by using the logical bean node, which represents the bean as a whole. You learn to add create, finder, and business methods using the EJB Builder's GUI features.
The detail classes must have the same fields as the entity beans. You create two classes and add the appropriate bean properties to them. While adding each property, you activate an option that automatically generates accessor methods for the property. This way, you obtain the getter and setter methods the application requires. Then you code each class's constructor to instantiate the properties. Finally, you add code to each of the two entity beans to return an instance of its corresponding detail class.
The Java Studio Enterprise IDE includes a facility for testing enterprise JavaBean components without your having to create a client for this purpose. This facility uses Sun ONE Application Server 7 as the application server and deploys the enterprise bean as part of a J2EE application that includes a web module and client JSP pages. An HTML page coordinates these JSP pages so that, from a web browser, you can create an instance of the bean and then exercise its business methods.
You create test applications for all three of the enterprise beans separately. For the entity beans, the test application generates a J2EE application that contains a web module, which contains the automatically generated JSP pages for the client's use from a web browser, and an EJB module for the entity bean. The session bean's EJB module must also contain the EJB modules of the entity beans, because it calls methods on those entity beans. You add the entity bean references to the session bean's EJB module using commands in the IDE. The EJB module created while creating the test application is referenced later by the web service.
When you test the session bean in a web browser, you can exercise all the application's business methods. At the end of Chapter 3 are guidelines for using the test client apparatus to guide you if you want to create your own web service and client manually.
In Chapter 4 you learn how to use Java Studio Enterprise features to:
A web service is a logical entity that represents the entire set of objects in the web service, and facilitates modifying and configuring the web service. You create a web service in the Explorer using the New wizard to define its name and package location. As you create the web service, the wizard prompts you to specify the business methods you want the web service to reference.
You inform the web service of the location of the JAX-RPC runtime by specifying its URL as a property of the web service. You then generate the web service's runtime classes, which are EJB components that implement the web service.
You create a test client that consists of front-end client and a back-end J2EE application. You then add references to the session bean's EJB module and to the web service. This action makes the web service's WAR and EJB JAR files available, so you can customize their properties. One property that you customize is the Web Context property. This completes the DiningGuide's J2EE application, and you are ready to deploy it.
When you deploy the J2EE application that contains the web service, the IDE automatically generates a client proxy and supporting files. The supporting files include a JSP page for each referenced method, a JSP error page, and a welcome page.
You use an IDE command to deploy the DiningGuide application. This starts the application server and displays the test client's welcome page that displays all the operations on one page. The generated JSP pages contain input fields when an input parameter is required, and an Invoke button to execute the operation. You use these means to test how the web service calls each of the session bean's methods.
Although this tutorial does not describe how to publish the web service to a UDDI registry, it does describe an informal method for enabling other developers to use the web service for testing purposes. You learn how to generate a WSDL file, which you can then make available, either by placing it on a server, or by distributing it some other way, such as by email. The target developers can generate a client proxy from this file and discover which methods are available on your web service. They can then build a client accordingly, and, if you provide them with the URL of your deployed web service, they can test their client against your web service.
The Java Studio Enterprise IDE also provides a single-user internal UDDI registry for testing purposes. The StockApp example, available from the Tutorials and Code Camps page of the Sun Java Enterprise System Developer's portal, demonstrates how to publish a web service using this device. The Tutorials and Code Camps page is at: http://developers.sun.com/prodtech/javatools/jsenterprise/learning/tutorials/index.html.
See Building Web Services in the Java Studio Enterprise Programming series for complete information about publishing a web service to a UDDI registry.
Code for a simple Swing client that demonstrates the functionality of the DiningGuide application is provided in Appendix A. This client consists of a Swing class for each of the database tables. You create two classes and then replace their default code with the provided code. Then, you simply execute the main class.
You learn by examining the provided code how a client accesses the application's methods. First, the client must instantiate the client proxy. This makes the client proxy's methods available to the client. These methods (see FIGURE 2-1) are used by the SOAP runtime to access the methods of the application's EJB tier.
This tutorial application is designed to be a running application that illustrates the main features of Java Studio Enterprise, while still brief enough for you to create in a short time (perhaps a day). This places certain restrictions on its scope, for example:
Although the tutorial application described in this book is designed to be a simple application that you can complete quickly, you might want to import the entire application, view the source files, or copy and paste method code into methods you create. The DiningGuide application is accessible from the Tutorials and Code Camps page of the Java Studio Enterprise Developer's portal at:
http://developers.sun.com/prodtech/javatools/jsenterprise/learning/tutorials/index.html
Copyright © 2004, Sun Microsystems, Inc. All rights reserved.