Introduction

In this tutorial, I will be using WebSphere® Studio Application Developer beta version to develop, test, run and debug a complete J2EE application, consisting of entity and session EJBs, a servlet, a JSP^TM page and an HTML home page. I will be focusing extensively on EJB development. The entire application will use only the Application Developer tools and run times available straight "out of the box."

Keeping true to developer tradition, this J2EE application will be a "Hello World" application in which all components will be named HelloWorld. So, for example, the entity bean you will create and deploy will be called HelloWorldEntity, the session bean will be called HelloWorldSession, the servlet called HelloWorldServlet, and so forth. This will let us concentrate on the main ideas without getting too bogged down in specifics and let us keep the code simple. The source code and listings are provided in the download below. For those who would rather work through this tutorial with a pre-created application, I have also provided this with the download. The download ZIP file contains the completed EAR module and some helpful scripts that I have provided to create the InstantDB database tables. With this ready-made version, including the scripts for the database tables, you can simply import the EAR module, create the tables, create and configure the Server project, instance and configuration, and run, debug and test the application. However, my hope is that you create everything from scratch to get a good sense of the development environment and the tight integration of the various parts.

My goal, then, is to highlight the Application Developer tools. The purpose of this article is not to teach you how to create J2EE applications -- I am sure many of you are masters at this -- but rather to show you how the tools seamlessly integrate all of the steps required to code and unit-test J2EE applications, thus increasing programmer productivity and satisfaction.

As I've already mentioned, in the download file HelloWorldApplicationDeveloper.zip provided at the end of this article, you will find all of the application's source in a single EAR file, the listings referred to in the tutorial, as well as the database script and properties file.

Back to top

Artifacts you will create

In the "Hello World" end-to-end, multi-tiered, distributed J2EE application, I plan to demonstrate that it is possible to create and use all of the following J2EE artifacts spanning the three main tiers in a typical distributed J2EE application -- client (presentation), application and data.

• J2EE application (EAR module)
• J2EE Web application (WAR module)
• J2EE EJB module
• stateless session EJB
• container-managed entity EJB (CMP)
• datasource (mapped to InstantDB)
• J2EE application client module
• Java^TM bean (used in servlet and JSP)
• servlet
• JSP page
• HTML page

This tutorial was written and tested relative to my specific Application Developer installation directory. All paths will be discussed using this installation directory: e:\WSAD_BETA.

Since it is very likely that your path to the Application Developer installation root is different from mine, especially if you accepted the default of c:\Program Files\IBM\WebSphere Studio Application Developer, you will need to adjust these paths and any artifacts created in which a path is specified.

Back to top

Architecture for "Hello World"

The architecture used in this application utilizes the so-called J2EE "Model 2" architecture (a version of the classic MVC, model-view-controller architecture) in which servlets are used as controllers and JSPs are used to display the final output. In this case, a session bean is used to control workflow and interact directly with the client (which happens to be a servlet) and it in turn interacts with an entity bean that further interacts with the datastore that persists it. This simple distributed "Hello World" J2EE application, then, is actually quite complex when you think about it. I will show you how easy it is to develop and test it in WebSphere Studio Application Developer.

Back to top

Working through the tutorial

The following steps and procedures should be followed exactly to build and test the "Hello World" J2EE application. This is the procedure to follow if you plan to create the application from scratch. The pre-created versions (in EAR module format) are available for download and simply need to be imported as you import any other EAR module to Application Developer. It is my expectation that when I say "create an entity bean..." you know what I am talking about. If this is not the case, check out the Application Developer help documentation for details on how to use the Application Developer tools.

When you have completed this tutorial, you will have a number of different types of projects and artifacts, each one representing a different J2EE artifact such as a Web module and an EJB module. The complete, end-to-end application seen through the eyes of the "J2EE view" should look like Figure 1 below when you're done.

Back to top

Development steps

Step 1. Create the EJB project and the HelloWorldEntity container-managed entity bean (CMP)

1. Create a new EJB project called, HelloWorldEJBProject, and a new EAR project name called, HelloWorldEARProject. Click Finish, and accept all other defaults.
   
   
2. Select the HelloWorldEJBProject project. Create a new CMP bean called, HelloWorldEntity, in a package called, helloworld.ejb, with the persistent fields listed below. Make sure to check the Access with getter and setter methods checkbox and the Promote getter and setter methods to remote interface checkbox for each field, except for the id field, which you must make the key field. Supply default values.

   firstName (String) lastName (String) id (int, Key Field)

   
   
3. Once you have added all three fields, click the Finish button.

Step 2. Create the EJB to RDB mapping using InstantDB for the HelloWorldEntity CMP

1. Select the HelloWorldEJBProject project and perform a default top-down EJB to RDB mapping to InstantDB v3.26 as the target database. You should specify the following:
   
   Target Database: InstantDB v3.26
   Database Name: HelloWorld
   Schema Name: <remove NULLID and leave blank>
   
   Note that you should leave the schema name blank. InstantDB does not support schemas, so the SQL generated in the persistors of the style schemaName.table name will fail with an SQLException.
   Figure 2. Creating an EJB to RDB mapping for InstantDB
   
   
2. Ensure that the Generate DDL checkbox is checked, and then click Finish. When completed, the generated table.dll should look similar to this:
   

   - Generated by Relational Schema Center on Thu Sep 1 09:22:47 EDT 2001 CREATE TABLE HELLOWORLDENTITY (FIRSTNAME VARCHAR(250), LASTNAME VARCHAR(250), ID INT NOT NULL); ALTER TABLE HELLOWORLDENTITY ADD PRIMARY KEY (ID);

   
   Later, we will use this DDL to create an InstantDB SQL script to build the database tables.

Step 3. Create a HelloWorldSession stateless session bean

1. Select the HelloWorldEJBProject project and create a new stateless session bean called, HelloWorldSession, in the helloworld.ejb package. Accept all the defaults, and click Finish.
   
   
2. Open the Java editor on HelloWorldSessionBean.java for this HelloWorldSession bean. Add a protected member of type HelloWorldEntity with name helloWorldEntity, and assign it a value of null.
   

   protected HelloWorldEntity helloWorldEntity = null;

   
   Now, add code to enable the session bean to manage workflow and interact with the entity bean's remote interface. The Web browser client will never interact with the entity bean directly, not even with its remote interface. The client will only interact with the session bean.Using session beans to control workflow is a typical way in which J2EE applications are implemented. To reiterate, I am not suggesting that the "Hello World" code and implementation is typical or a best practice; I am simply using this code to demonstrate how well the tools integrate.
   
   
3. Create the method getHelloWorldEntity() in the HelloWorldSessionBean class, but do not promote it to the remote interface since it does not need to be exposed to the client. It is internal to this class and can be hidden.
   

   Protected HelloWorldEntity getHelloWorldEntity(int id) { ... return helloWorldEntity; }

   
   See Listing 1 in the download ZIP file for the full implementation of this method.
   
   
4. Add the following import statements to HelloWorldSessionBean.java:

   import javax.ejb.*; import javax.naming.*;

   
   
5. Add the following remote methods to talk to the HelloWorldEntity entity bean (and promote them to the remote interface, which needs to be done manually in the beta version) to the HelloWorldSession interface for the bean:
   

   public String getFirstName(int id) throws java.rmi.RemoteException { ... } public void setFirstName(int id, String firstName) throws java.rmi.RemoteException { ... } public String getLastName(int id) throws java.rmi.RemoteException { ... } public void setLastName(int id, String lastName) throws java.rmi.RemoteException { ... }

   
   See Listing 2 in the download ZIP file for the implementation of these four methods.

Step 4. Generate WebSphere deployed code

Generate deployed code and run RMIC for both HelloWorldSession and HelloWorldEntity beans by selecting the project HelloWorldEJBProject, and then from the pop-up menu, select Generate for enterprise bean(s) => Deploy code and RMIC Stub and Tie code.

Step 5. Create a server project

1. Create a new server project called, HelloWorldServerProject.
   
   
2. Using the server project you just created, create a new combined, Server Instance and Configuration. Set the Server name to HelloWorldServer, and use the WebSphere v4.0 Unit Test Environment server instance type. If a different HTTP port than the default 8080 is required, go to the next page and change this value. Otherwise, click Finish.
   
   
3. You will now be in the Server perspective. Use the Server Configuration view to add the project HelloWorldEARProject to the HelloWorldServer configuration.
   Figure 3. Server configuration view
   
   

Step 6. Create a datasource

Complete the following steps to create a datasource, configure it, and to use it to persist the data for the HelloWorldEntity CMP bean created and mapped above.

1. In the Server Perspective within the Server Configuration view, edit the HelloWorldServer configuration using the configuration editor. For more information on how to do this, refer to the Application Developer Server Tools documentation. Click the Datasource tab in the editor, select the idbJdbcDriver from the JDBC drivers list, and then click the Add button to add a new datasource. Note that you should do this using the Add button in the datasources pane. That is, in this case, you want to add a new datasource with a predefined JDBC driver; you do not want to add a new JDBC driver. Both DB2® and InstantDB JDBC drivers are already available to you.
   
   
2. Specify the following values (exactly) in the Add a Datasource dialog:
   
   Name: HelloWorldDatasource
   JNDI Name: jdbc/idb/HelloWorldDatasource
   Description: HelloWorld Datasource
   Category: helloworld-testing
   Database Name: <leave blank>
   Figure 4. Adding a datasource
   
   
3. Leave all other values as-is and leave the Database name field empty for InstantDB. The default time-outs and pool sizes are fine for basic testing. Also, since you will not require transactions in the database, do not check the Enable JTA checkbox. When you have finished, click OK. Then, press the Save icon on the toolbar or type Ctrl-S to save the configuration.
   
   The name, category, description and JNDI name fields could be set to anything you want and do not need to follow a special format. But, to be safe, for the purposes of completing this tutorial, I recommend that you type it in as I have described. What is most important is that the JNDI name is identical to the name you will use later in the EJB bindings to bind your CMP to this datasource. For simplicity, I simply made up jdbc/idb/HelloWorld, which is what I use in the bindings later on.
   
   Figure 5. A datasource defined
   
   
4. Because the InstantDB JDBC URL is handled as a separate vendor-specific resource property (unlike DB2 for example, but like Oracle) you need to define a new resource property for this datasource. Select the datasource you just created, and then from the Resource properties pane, click the Add button to add a new resource property. Set the values as follows:
   
   Name: url
   Type: java.lang.String
   Value: jdbc:idb:e:\WSAD_BETA/HelloWorld.prp
   Description: JDBC url resource for HelloWorld
   
   
5. When you have finished with the dialog box, click the OK button. See Figure 6 below.
   Figure 6. Adding a resource property for InstantDB
   
   
6. Remember that all paths described here are relative to my particular Application Developer installation path e:\WSAD_BETA where I chose to build my actual tables. Once you have defined this property, save the configuration again. You should see the added resource property.

Step 7. Create the InstantDB HelloWorld database tables

First, take the table.ddl created above and use it to generate the actual tables that will persist the CMP. You need to create an InstantDB script to accomplish this. Then, create an InstantDB properties file that specifies, among other things, how and where the tables should be created. Finally, create a simple batch file to create the tables as specified.

1. Using the Application Developer default text editor, create an InstantDB properties file called HelloWorld.prp in your Application Developer installation directory. At a minimum, set it up as you see it in Listing 3 of the download ZIP file. This will signal InstantDB to create the tables below the current directory. If you want or need the tables to be created elsewhere, set the path here in this file.
   
   
2. Using the table.dll as input, create a new InstantDB SQL script that specifies what to create and what JDBC driver to use. You can use the Application Developer default text editor, and save the file in your Application Developer installation directory as HelloWorld.idb. See Listing 4 in the download ZIP file for the content of this file.
   
   
3. Optionally, you can create a simple convenience batch file to invoke and create the tables, called appropriately enough, HelloWorld.bat, that looks functionally like the implementation in Listing 5 in the download ZIP file.
   
   
4. When HelloWorld.bat is run from the command line, you should see the following output indicating that the tables were successfully created. As defined above, your tables should be created just below the current directory in a subdirectory called -- you guessed it -- HelloWorld.

   Enhydra InstantDB - Version 3.26 The Initial Developer of the Original Code is Lutris Technologies Inc. Portions created by Lutris are Copyright (C) 1997-2001 Lutris Technologies, Inc. All Rights Reserved. Connected to jdbc:idb:HelloWorld.prp Driver InstantDB JDBC Driver Version Version 3.26 Database HelloWorld is shutting down... Database HelloWorld shutdown complete.

   
   

Step 8. Binding the datasource to the HelloWorldEntity CMP

As a final step to creating and binding this datasource to our particular CMP, we need to edit the EJB bindings using the EJB Extension editor.

1. Locate the ejb-jar.xml file in the META-INF folder of the ejbModule folder in the HelloWorldEJBProject project. Right-click and perform an "Open with" on this file using the EJB Extension Editor (not the ejb-jar.xml editor which is the default).
   
   
2. Select the Binding tab, and then select the HelloWorldEntity bean to configure the binding. Enter the following values for the JNDI name for the binding, based on how you created and configured the datasource above and the JNDI name you used for the datasource itself:
   
   JNDI name: helloworld/HelloWorldEntity
   Datasource JNDI name: jdbc/idb/HelloWorldDatasource
   Default user id: hello <optional>
   Default password: hello <optional>
   
   
3. When you are finished, type Ctrl-S or click the Save icon on the toolbar to save the configuration.
   Figure 7. Binding the datasource to the CMP EJB
   
   

Back to top

First round of unit testing: the EJB Test Client

Since you have actually created, developed, deployed, and configured quite a bit to this point, I suggest that some unit testing is in order before proceeding to the next set of steps to implement the servlet, the JSP and the associated code. This is where I believe (biased, of course, but you judge for yourself) that the Application Developer tools really shine and provide you seamless, integrated and powerful unit-testing capabilities. Since the EJB Test Client is already built into the Server configuration by default and runs in the Application Server itself, use the EJB Test Client first to make sure that your EJBs are at least functional and that the persistence mechanism works properly to InstantDB.

1. Right-click the HelloWorldSession bean in the ejbModule in the HelloWorldEJBProject project, and select Run on Server from the pop-up menu.
   
   This is one of the numerous "automatic" features of Server Tools that I think is cool. It will do just "the right thing" for you to configure the selected module (EJB or Web application component), initialize and start the application server for the selected type of module. In the case of an EJB, install the Web-based EJB Test Client, execute the EJB Test Client on this bean in the embedded Web browser, do a lookup on the name service, find the home and make it available to you. You can do this all with one simple menu command to Run on Server. Now this is automation!
   Figure 8. Running the EJB Test Client Run on Server command
   
   
2. Check the console in the Server Perspective to make sure the beans fired up properly. If you see no exception or load module errors, you can assume it succeeded. If not, there is likely something wrong with the generated code or your datasource configuration. Once started successfully, the status will change to Started.
   Figure 9. Checking the server status: server is started
   
   
3. If the server started properly, use the Web-based, integrated, EJB Test Client, which will automatically surface for you, to create an instance of the HelloWorldSession. Doing so in this application will create an instance of HelloWorldEntity. Make sure that there are no messages in the console indicating that the persistor code failed to generate or that the datasource was not bound properly.
   
   
4. Try out some of the remote methods on the session bean which in turn invoke similar methods on the entity bean. This allows the two beans to talk to each other and persists data to the configured datasource.
   Figure 10. EJB Test Client testing the HelloWorldSession bean
   
   

Back to top

Second round of unit testing: the J2EE application client

If you were successful with the EJB Test Client, you may now want to test the beans using a standards-based J2EE Application Client, which is part of a J2EE application module. This means that it is a built-in part of the application as a whole and is part of the EAR module.

Step 9. Creating a Java application client project and implementation

1. Create a new Application Client project called, HelloWorldApplicationClientProject, using the existing HelloWorldEARProject EAR.
   
   
2. In the AppClientModule folder, create a new J2EE application client class with a main method HelloWorldEJBTestClient in a helloworld.ejb.clients package.
   
   
3. See Listing 6 in the download ZIP file for the full implementation for the HelloWorldEJBTestClient.
   

   package helloworld.ejb.clients; import javax.naming.*; Import java.util.*; Import javax.rmi.*; Import helloworld.ejb.*; public class HelloWorldEJBTestClient { public static void main(String[] args) { ... }

   
   One thing you should notice is that since this is a J2EE-compliant application client packaged with the EAR module, there is no need to use a network-specific JNDI InitialContext. You do not need to specify the service provider to connect to the J2EE server; this demonstrates that J2EE application clients have location transparency. The real power of location transparency is that the "Hello World" application client component does not need to know the exact location of the EJBs it needs to connect to and work with.
   
   
4. For the project, in the properties dialog box under the libraries tab, add the external j2ee.jar file to the Java Build Path. This file is found in your WSAD_HOME\plugins\com.ibm.etools.webphere.runtime\runtime directory.
   
   
5. Add the HelloWorldEJBProject project to the Java Build Path to resolve compilation references to the EJBs themselves.
   
   
6. Start WebSphere Application Server in the Server Configuration panel if it is not already started. Wait until it is fully started without exceptions. If it is already started from working through the steps above, there is no need to restart it.
   
   
7. Run your home-grown HelloWorldEJBTestClient class using the Java Launcher (not the Server Launcher). The easiest way to do this is to work from the Server Perspective. First, select Menu => Perspective => Customize => expand Other tree => check Run\Debug, which will add the "running person" and debug icons to your toolbar in the current (Server) perspective. Then, select the HelloWorldEJBTestClient class and click the running person icon. Use the Java launcher to run this program. You will be switched into the Debug perspective where you can work with the process and see the console output. If you want, you can simply launch the client from the Debug perspective.
   
   
8. You should get a clean run without exceptions, and will see the following in the console window after the application finishes its run:
   

   Getting the IntialContext... Performing the lookup.. Parameters passed to the commandline: Parameter 'id' = 99 Parameter 'firstName' = Sheldon Parameter 'lastName' = Wosnick Calling Session bean methods.. Verifying method calls happened... First Name Returned: Sheldon Last Name Returned: Wosnick

   
   If this is not the case for you, then go back and trace through your steps to see where you might have made a mistake. If the application runs successfully, you have now ensured your core application logic works properly in yet a different (open standards, nonproprietary) client configuration.

Back to top

Third round of unit testing: the full end-to-end J2EE application

Now that you have developed and tested your EJBs using the EJB Test Client that runs in the application server itself, and further tested them with an application client which runs completely outside the application server, you might want to do one more round of unit testing. You may want to create a servlet, JSP, Java bean and HTML home page so that you can run the J2EE application from end-to-end through all the various tiers, just as I illustrated in Figure 1 above. In this way, you have an authentic entry point that resembles closely how you would expect your users to access the application that is composed of this core logic.

Step 10. Create the Web projectand a simple Java bean to read and write properties

The architecture used here is a typical separation of content presentation from content generation and is one of the suggested servlet and JSP implementations.

1. Create a new Web project called, HelloWorldWebProject, using the existing EAR HelloWorldEARProject. Accept the defaults, and click Finish.
   
   
2. Then, create a simple Java bean in a new package called, helloworld.servlet, in the Web project (where we will subsequently build our servlet) in the source tree called, HelloWorldJavaBean. It will store the values returned from the session bean, so that the servlet you will create next can make the values available to the JSP you will also create. During compilation, the actual binaries will be moved over to the webApplication folder to the WEB-INF\classes location, but you should work with your source from only the source tree. See Listing 7 in the download ZIP file for the full implementation of HelloWorldJavaBean.

Step 11. Create the HelloWorldServlet servlet

1. Use the Web tools to create a simple servlet called, HelloWorldServlet, in a helloworld.servlet package, implementing the doPost() method stub only. Then, implement the code required to communicate to the HelloWorldSession bean. Accept all the other defaults.
   
   The servlet will not be anything fancy and it is not really suggestive of the way to perform the JNDI lookup, which is typically done in an init() method. We will be referencing the HelloWorldJavaBean created above, so make sure that you have created it as described in Step 10.
   
   
2. In the end, you should code the implemented servlet and the doPost() method. Refer to Listing 8 in the download ZIP file. This servlet is virtually identical to the application client above except that it is implemented as a servlet and like the application client, the service provider and the network-specific JNDI initial context do not need to be specified because the servlet is part of a Web module. The Web module is part of the EAR module that contains your EJBs.
   
   
3. Add the HelloWorldEJBProject project to the Java Build Path for the HelloWorldWebProject project to resolve class references to your HelloWorld EJBs.
   
   Note that if you choose to import the pre-created HelloWorld.ear file, you must also add the EJB project to the Java Build Path of any project that contains references to the EJBs as well as the path of j2ee.jar for the javax.ejb.* packages.

Step 12. Create the HTML home page

Using the Web tools, add a simple home page, index.html, to serve as a form to pass parameters and post them to the servlet. Since HTML is not considered "source," add it to the webApplication folder, which is the working document root. A specific style sheet is not required here so do not specify one. Then, using the design or source views, create three text fields for the ID number, First Name and Last Name fields and a Submit action to perform a POST. Refer to Listing 9 in the download ZIP file for an example of such a page.

Step 13. Create the JSP for final presentation to the user

Using the Web tools, create a simple JSP page called HelloWorldJSP.jsp without specifying a style sheet. Complete the same steps as you did to create the HTML page. The JSP could look as simple as the one provided in Listing 10 in the download ZIP file.

Step 14. Run the full application on the server

By now, you have constructed all the various pieces of the full, end-to-end J2EE application and can test it from beginning to end in a simple, straightforward manner.

1. Select the index.html file and use the Run on Server command to run the index.html form you created on the server. Just like I described earlier, the command will just do the "right thing" to process and run a specific component automatically for you.In this case, if the server is already running, you must stop it first and restart it to pick up the changes in the configuration from adding the new Web application (WAR module) to your enterprise application (EAR module).
   Figure 11. Running the application on the server
   
   
2. Enter some data in the entry fields and perform a submit. This will pass execution on through to the servlet controller to the session bean on to the entity bean. This bean is persisted to the datastore and then transfers execution back to the servlet which will place the values in a Java bean, set that bean into the session, and dispatch the entire request and response to the JSP for presentation to the user. Be patient, since the first time you submit the request, the JSP needs to be generated first and then compiled, which can take a few seconds. Subsequent submits will be almost instantaneous.
   Figure 12. A simple HTML entry and submit form
   
   
3. Once the full application has run its course through all of the distributed tiers in Figure 1 above, the final output is HTML generated by the presentation JSP and sent back to the browser.

Back to top

Conclusion

This article has described how to develop, test, run, and debug a complete, end-to-end, distributed, multi-tier application with the tools provided in WebSphere Studio Application Developer. The Application Developer tools free you from being distracted by set-up and configuration issues, and let you concentrate fully on your core business logic and on creating and unit testing powerful, integrated J2EE artifacts.

Part 2 will show in a similar step-by-step manner how to deploy and test this same application on WebSphere Application Server 4.0.

Top of page

Back to top

Download

Name	Size	Download method
HelloWorldApplicationDeveloper.zip	104 KB	FTP|HTTP

Information about download methods

About the author

Sheldon Wosnick is a software developer on the IBM WebSphere Studio Application Developer, Server Tools team at the IBM Toronto Lab. With his teammates, he is currently responsible for the entire server run time and unit test environment for Application Developer. Previously, he was a member of the VisualAge® for Java WebSphere Tools team. Sometimes fondly known as the "run time guy," he designed and integrated the WebSphere Test Environment and the Apache Tomcat Test Environment for VisualAge for Java, two very popular features in VisualAge for Java. You can reach Sheldon at swosnick@ca.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Artifacts you will create
• Architecture for "Hello World"
• Working through the tutorial
• Development steps
• First round of unit testing: the EJB Test Client
• Second round of unit testing: the J2EE application client
• Third round of unit testing: the full end-to-end J2EE application
• Conclusion
• Download
• About the author
• Comments

Next steps from IBM

With the WebSphere Application Server you can benefit from the simplified EJB 3.0 development experience, new persistence model, and interceptors.

---

• Try: Download a free trial version of WebSphere Application Server Community Edition, the lightweight Java 5 application server with robust EJB 3.0 funtionality.
• Article: Learn how call patterns and components involved in making calls to EJB components deployed in the EJB container operate in WebSphere Application Server.
• Tutorial: This tutorials shows you how to create an enterprise J2EE application that implements both Plain Old Java Object (POJO) and EJB Web services endpoints.
• Demo: Watch this demo and learn how to configure and use the WebSphere Application Server and the Eclipse IDE with the Web Tool Project Platform.
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers