 | Level: Introductory Sheldon Wosnick (swosnick@ca.ibm.com), Software Developer, IBM WebSphere Studio Application Developer, IBM Toronto Lab
15 Oct 2001 This article focuses on a larger-scale J2EE application, and takes you through developing, testing, running, and debugging an application with entity and session EJBs, a servlet, a JSP page, and an HTML home page.
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 JSPTM 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.
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
- JavaTM 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.
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.
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.
Figure 1. J2EE view of the completed "Hello World" end-to-end application
Development steps Step 1. Create the EJB project and the HelloWorldEntity
container-managed entity bean (CMP)
- Create a new EJB project called, HelloWorldEJBProject, and a new
EAR project name called, HelloWorldEARProject. Click Finish,
and accept all other defaults.
- 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)
|
- 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
- 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
- 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
- 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.
- 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.
- 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.
- Add the following import statements to
HelloWorldSessionBean.java:
import javax.ejb.*;
import javax.naming.*; |
- 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
- Create a new server project called, HelloWorldServerProject.
- 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.
- 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.
- 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.
- 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
- 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
- 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
- When you have finished with the dialog box, click the OK button.
See Figure 6 below.
Figure 6. Adding a resource property for InstantDB
- 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.
- 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.
- 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.
- 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.
- 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.
- 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).
- 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>
- 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
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.
- 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
- 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
- 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.
- 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
 |
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
- Create a new Application Client project called, HelloWorldApplicationClientProject,
using the existing HelloWorldEARProject EAR.
- In the AppClientModule folder, create a new J2EE application client class
with a main method
HelloWorldEJBTestClient
in a helloworld.ejb.clients package.
- 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.
- 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.
- Add the HelloWorldEJBProject project to the Java Build Path to resolve compilation
references to the EJBs themselves.
- 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.
- 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.
- 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.
|
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.
- Create a new Web project called, HelloWorldWebProject, using the
existing EAR HelloWorldEARProject. Accept the defaults, and click Finish.
- 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
- 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.
- 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.
- 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.
- 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
- 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
- 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.
|
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
Download | Name | Size | Download method |
|---|
| HelloWorldApplicationDeveloper.zip | 104 KB | FTP|HTTP |
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 page
| |
