IBM WebSphere Developer Technical Journal
Developing and Testing a Complete "Hello World" J2EE Application with WebSphere Studio Application Developer
Part 2 - Running on WebSphere Application Server 4.0
In Part 1 of this series, I showed you how to assemble, run, test and debug a real, 3-tier, J2EE application using the new WebSphere Studio Application Developer product. In Part 2, I demonstrate in a similar step-by-step manner how to deploy and test this same application on WebSphere Application Server, Version 4.0.
You will see that it is relatively easy to take an Enterprise
Archive (EAR) module that was produced in WebSphere Studio Application Developer,
and then deploy and test it on WebSphere Application Server 4.0, on both
Advanced Single Server Edition (ASSE) and Advanced Edition (AE). This demonstrates
that the new run times and development environments for the WebSphere products
all share a common programming model; therefore, it is fairly straightforward
to move from the simpler edition to the more feature-filled one since you do
not have to overhaul the applications themselves. In the case of our example
"HelloWorld" application, you will not need to remodel, recompile or change
a single line of code as the application is being deployed from Application
Developer to WebSphere Application Server ASSE and to AE. Typically, the only
change potentially required is that you may need to change the port number from
8080 to 9080 for the home page
The source code and scripts described in this tutorial are available for download below.
To work through the entire tutorial, including deploying to WebSphere Application Server 4.0, ASSE and AE, you need to have the following properly installed on your system:
- WebSphere Studio Application Developer
- WebSphere Application Server, Advanced Single Server Edition, Version 4.0
- WebSphere Application Server, Advanced Edition, Version 4.0
- DB2, Version 7.2 as required by the WebSphere Application Server AE administration server, with fixpacks properly installed
If you don't have AE installed, don't worry. You can simply walk through the ASSE section. (In this case, you also don't need to have DB2 installed since this is required for use with AE only). At the minimum, you will need to have WebSphere Studio Application Developer beta version and ASSE installed.
Export the J2EE application from Application Developer
file to any location you want. For this tutorial, I exported it to
(this is the same directory that I used in my previous tutorial).
In Application Developer, with the application you developed
in the previous tutorial (you can download the code below),
export the EAR file by selecting File => Export => EAR file. Export the
HelloWorldEARProject EAR project to a convenient location. Again, for
me, this is
e:\WSAD_BETA. Make sure to export
the source files as well, since you may need them at some point. Once you have
completed the dialog, click Finish.
Figure 1. Exporting the completed EAR project from Application Developer
WebSphere Application Server, Advanced Single Server Edition, Version 4.0
Install the Application Developer EJB Test Client to ASSE
One of the goals of this tutorial is to test the application logic directly on the Application Server, perhaps on the Application Server used in actual production or on a staging server that is very similar to the production level one. To do this, you can easily use the EJB Test Client to test the methods in your EJBs.
Since the EJB Test Client was itself designed to be an EAR module (J2EE application) that runs on Application Server in Application Developer, you should have no trouble deploying it to other WebSphere installations. This makes using the EJB Test Client convenient for a number of reasons. One reason is that it is very easy to install (and deploy) the application. Another reason is that since the Test Client is a Web application itself, it also runs within the Application Server in the same process; this means that it is as close to your application logic as you can get in a production-level environment. In this way, you can see exactly how the application or core application logic behaves.
- The EJB Test Client EAR module is located at:
- Create or edit the following batch file to run SEAppInstall for the EJB
Test Client that is already packaged as an EAR module in the Application Developer
plugins directory. Save the file as
InstallIBMUTC.bat. Alternatively, you can run the commands directly from the command line. The choice is yours.
set WAS_HOME=i:\WebSphere-AEs\AppServer set e:\WSAD_HOME=e:\WSAD_BETA set EJB_TEST_CLIENT_EAR=%e:\WSAD_HOME%\plugins \com.ibm.etools.websphere.tools\IBUTUC\IBMUTC.ear SEAppInstall -install %EJB_TEST_CLIENT_EAR% -expandDir %WAS_HOME%\installedApps\IBMUTC.ear -ejbdeploy false -interactive false
- If you created the batch file, run the batch file from the command line to install the application and precompile the JSPs that are part of the application. The bin directory for ASSE, where EAppInstall is located, should be on your path from when you installed ASSE because the installation process puts this directory on the path. Therefore, an unqualified "SEAppInstall" should suffice.
- You should see standard output in your command prompt window as the application loads the configuration, installs the EAR module and sets up the bindings. As the JSPs are compiled, you can watch the status of the compilation. All compilation should occur without errors. You can safely disregard the security roles warnings since we are not using security roles for this tutorial.
- You'll know that the EJB Test Client installed properly when you see the line, "Installation Completed Successfully." If this is not the case, go back and see where you may have introduced an error or an incorrect path, which are two likely causes for a failure.
Create a datasource for the "Hello World" application
Earlier, you needed to create the datasource for the server configuration in Application Developer; now you need to do the same thing in ASSE itself. You can do this manually by editing the server configuration file. However, this is not the recommended method. Instead, you should run and use the ASSE Administrative Console (this is Web-based, and it is well-documented). I will assume that you are already somewhat familiar with the concepts.
- Start or restart ASSE using
%WAS_HOME%\bin\startServerBasic.batuntil you see "Server Default Server open for e-business." Once the server is started, launch the Administrative Console from the link provided for you during the ASSE installation process or by bringing up a Web browser and pointing it to http://localhost:9090/admin. (This is assuming defaults.)
- Once you have logged in to the Administrative Console, expand the Resources
node under the WebSphere Administrative Domain and then expand JDBC Drivers.
From here, you can add support for new JDBC drivers and/or new datasources
based on these drivers.
Figure 2. Locating the datasource resources
- In ASSE, the InstantDB JDBC drivers are already deployed for use with the sample applications (idbJdbcDriver) and you do not need to install the JDBC driver. (Note that you will need to do so for AE later on because it is not installed by default.)
- Click on the Data Sources folder link for idbJdbcDriver and you will see that there are a number of sample InstantDB datasources already installed.
- From this view, click the New buttonto create the new datasource.
To keep things simple, assign the same values that you did when you created
the datasource in Application Developer, and assume the other connection time-out
and pool default settings. You may recall from the first tutorial that you
used the values below. You should also enter these values in this form.
JNDI Name: jdbc/idb/HelloWorldDatasource
Description: HelloWorld Datasource
Database Name: <leave blank>
You can also leave the Default User ID and Default Password fields blank. Click the OK button when done. You will notice an important reminder indicating that you need to save the configuration. Whenever a configuration change occurs, you will get this reminder. You will need to save the configuration, but before you do so, complete the next step (that is, create the additional property).
- If you successfully created and saved your datasource, it should be added
to the list.
Figure 3. Viewing the added InstantDB datasource
- As you did in Application Developer, you need to set a driver-specific custom property to use InstantDB. Click on the datasource that you just created. Then, click the Properties button at the bottom of this form (in the Driver Specific Setting section) to add the property. When you click Properties, you will see that the URL property we need to create is started for you. Click on the URL link in the name field to edit this property.
- Similarly, just as you did in Application Developer, supply the following
values (some of which are already supplied) by clicking the HelloWorldDataSource
link that was just created and editing a resource property to be associated
with this datasource:
Description: JDBC url resource for HelloWorld
Note: If you want to use the tables created in the previous tutorial, you can. Alternatively, you can use the same scripts (also available in the download below) and recreate the tables just for ASSE. Here, I chose to reuse the same tables which highlights the fact that we are running the identical run times and databases in Application Developer that we will later run on ASSE. What's more, since your CMPs were persisted, they should be available from ASSE itself. Before you click the OK button, the Properties form should look like this:
Figure 4. Editing a new resource property
- After you click OK, you will see that the resource property has been
Figure 5. Viewing the added resource property
- Your datasource and associated database-specific properties are now set but not yet saved in the configuration. For the properties to be available the next time you restart ASSE, click on the link at the top of page to bring up the Save Configuration view and save your server configuration file.
Set the module visibility of ASSE
While ASSE is still running, or restarted if necessary, you need to set the module visibility mode to COMPATIBILITY so that the EJB Test Client can see the other modules it wants to interact with (you can do this or install a separate version of the EJB Test Client Web application for each EAR module that contains the EJB modules that you want to work with directly). For security reasons, if this is a production server and you do not require WebSphere 3.5x support, you will likely want to set it back to APPLICATION (this is the default). But, while testing, you should set it to COMPATIBILITY. You can always reset it later.
- In the Administrative Console, select Nodes => Nodename => Application Servers => Default Server.
- Click on the Default Server link. This brings you to the Application
Servers frame. Here, you can reset the application visibility at the global
server level. The comments on the page suggest that a mode value of COMPATIBILITY
is essentially present to support earlier versions of WebSphere Application
Sever (that is, Versions 3.0 to 3.5). Change the value from the default of
APPLICATION to COMPATIBILITY and make sure to save your configuration.
Figure 6. Changing the module visibility
Install the "Hello World" application
- Create another batch file,
installHelloWorld.bat, similar to the one for the EJB Test Client, so that you can use the commandline tool, SEAppInstall, to install the
HelloWorld.earfile that was exported from Application Developer to ASSE. Since the EAR file contains deployed code, you do not want to redeploy; so set the ejbdeploy flag to false. Alternatively, you can simply run the commands from the command line. The choice again is yours.
Set WAS_HOME=i:\WebSphere-AEs\AppServer set PATH_TO_HELLOWORLD_EAR=e:\WSAD_BETA\HelloWorld.ear SEAppInstall -install %PATH_TO_HELLOWORLD_EAR% -expandDir %WAS_HOME%\installedApps\HelloWorld.ear -ejbdeploy false -interactive false
- You should see output like you did when you installed the EJB Test Client application. Here, you can safely ignore the warnings about the bindings for the session bean since we never created or intended for there to be a binding for this bean. Check the output in the command prompt window to make sure the process was successful. Once again, if you see the last line, "Installation Completed Successfully," this means that the HelloWorld application has been properly installed. If this is not the case, go back and see where you may have introduced an error or an incorrect path.
Now that you have successfully
- deployed the HelloWorld application,
- created and configured your datasource,
- recreated the InstantDB tables or reused the existing ones, and
- deployed the EJB Test Client
it is time to run and test your application!
- Stop ASSE (stop it cleanly, by running
StopServer.batin the WebSphere binaries directory). Then, start ASSE using
%WAS_HOME%\bin\startServerBasic.bat(do not run
startServer.batsince this provides less console output). ASSE is started when you see Server Default Server open for e-business in the console. Note: You need to restart the server to ensure that any changes you have made to the configuration up to this point get picked up.
- Look at the console output (recall that there will be console output if
you launched ASSE by running
startServerBasic.batinstead of the
startServer.batbatch file) to make sure that there were no exceptions thrown and that the server started properly.
- Check the console output to make sure that the EJB Test Client application,
the datasource, and the HelloWorld application have all started up.
All three components need to start properly. You should see the following
confirmations in the output, although your timestamps of course will be different:
... [01.09.01 17:29:26:677 EDT] 566ca8ba ResourceBinde I WSVR0049I: Binding HelloWorldDatasource as jdbc/idb/HelloWorldDatasource ... [01.09.01 17:29:42:570 EDT] 566ca8ba EJBEngineI WSVR0037I: Starting EJB jar: Hello EJB Module ... [01.09.01 17:29:58:873 EDT] 566ca8ba ServletEngine A SRVE0169I: Loading Web Module: UTC. ...
Run the EJB Test Client
- If you are using the default host and ports, and the Web browser is on the machine that is hosting ASSE, point your Web browser to http://localhost:9080/UTC. Otherwise, set the host name and port number appropriately.
- Since the JSPs that are part of the EJB Test Client application were precompiled when you installed them, it should launch quickly. When it launches, you will find yourself at the EJB Test Client home page.
- Go to the JNDI Explorer and find the HelloWorldSessionHome link,
which will be there if everything started properly. The InstantDB datasource
will also be there, along with HelloWorldEntityHome.
Figure 7. Using the JNDI Explorer in the EJB Test Client
- Use the various features of the EJB Test Client that is running inside ASSE
to test the HelloWorldSession and HelloWorldEntity beans on the Application
Server.First, click on HelloWorldSessionHome because we constructed
the logic to use the session bean to access the entity bean. Of course, you
can also test the entity bean itself. What you should see is that you can
do the same things you did within the Application Developer but now you are
testing real deployed beans on the "real" Application Server.
Figure 8. Using the EJB Test Client to test remote methods
Run the complete end-to-end J2EE application
If you were able to run the EJB Test Client successfully, then try running the complete application from the home page.
- You need to make a change in
index.htmlin the HelloWorldWebProject module because when we used it inside Application Developer for the POST method, it was set to:
<FORM METHOD=POST ACTION="http://localhost:8080 /HelloWorldWebProject/servlet /helloworld.servlet.HelloWorldServlet">
Change the URL to fit either the default ASSE host/port combination or to which ever setting you are using. By default, you only need to change the port to ASSE's internal Web server default port of 9080if you are running a WebSphere instance on the local machine. If you have deployed to a remote instance, set the host name accordingly. You will find the
index.htmlfile in the
WAS_HOME\\installedApps\HelloWorld.ear\HelloWorldWebProject.warfolder where SEAppInstall installed the application.
- Point your Web browser to http://localhost:9080/HelloWorldWebProject/index.htmlor to the remote equivalent if the WebSphere instance is not on the local machine. Enter some data in the form that is displayed.
- After a short delay, the full J2EE application that you tested in Application
Developer should run its course and have sent the output back to the browser
through the response page - exactly the same as it did during development!
Figure 9. JSP producing HTML output to the Web browser
WebSphere Application Server, Advanced Edition, Version 4.0
WebSphere Application Server AE takes a more "expert" skill set to administer, and is not really intended for novices new to WebSphere Application Server. I feel that in this article, it would be useful for me to show the same application, datasources and so on, deployed to the Advanced Edition. However, rather than walk you through step-by-step as I have until this point, I will highlight only the important points and leave it up to the curious readers to try it for themselves and fill in the missing pieces. The steps will be similar though. First, we will set up the database and datasources, and install the applications. Then, we will run them. Note that when I say start the Admin Server, I assume that you know what I am talking about, and that you have AE properly installed as well as the right level of DB2.
- Start the Admin Server service.
- Once the Admin Server service is started, start the AE Administrative Console.
Once it is started, you will create the datasource. Navigate to the JDBC Providers
to add a new JDBC driver. You need to add InstantDB JDBC driver because it
is not installed in AE as it is in ASSE. Select JDBC Providers and
begin to set the new JDBC driver properties. Enter HelloWorld for the
Figure 10. Adding a new JDBC provider
- For the implementation class, select the InstantDB implementation
class from the list, and then click OK. It is now added to the current
list of JDBC drivers available.
Figure 11. Selecting the JDBC driver implementation class (for InstantDB)
- Next, specify where the JDBC Provider is located. Since the InstantDB drivers
are packaged with Application Developer's WebSphere run time, point to that
location when you specify the location of the driver. Click the Install
New button to install the provider, then move through the various dialogs
until you browse to the path that the InstantDB JAR file is located in. In
the Application Developer beta version, it is always located at:
- Once the driver is located and set, click the Apply button to apply
the configuration change.
Figure 12. JDBC provider added successfully
- Locate the HelloWorld JDBC Provider that you just added in the Resources
tree, and right-click on the Data Sources folder icon to create at
new datasource. Set the values exactly as we did above (Step 2) to specify
the datasource. Leave the connection pooling values at their default values.
Click OK when done. The datasource is now added.
Figure 13. Adding the datasource correctly
- Specify a custom property as you did in Application Developer and in ASSE.
In AE, only the name and value are required. Again, if you don't want to reuse
the existing InstantDB tables, then recreate them elsewhere and specify this
here. I chose to reuse my InstantDB database tables. Click the Apply
button when done.
Figure 14. Adding the Custom Property for the JDBC provider
- Install the
HelloWorld.earusing the Install New Enterprise Application wizard. Browse to the path where you exported the
HelloWorld.earfrom Application Developer. Set the Application Name to HelloWorld. Since this is not a stand-alone module, you should have the Install Application radio button selected.
- Since you don't need to specify roles or any other attributes for this simple application, simply skip through all the pages of the wizard until you reach the Specifying Data Sources for Individual CMP Beans page. The JNDI bindings have already been specified during development and deployment in Application Developer and they do not need to be changed. You could have specified the default datasource for all CMPs in the previous page of the wizard, but since we only have a single CMP, it does not matter.
- Click the Select Datasources button and select the HelloWorldDatasource
datasource you created above. Optionally, supply a user ID and password, and
then click OK.
Figure 15. Selecting the datasource you just created
- Click through the pages to the last page of the wizard. Click Finish. You will be prompted to regenerate deployed code. Since you have freshly deployed code from your development in Application Developer, select No -- do not regenerate now. After a brief delay, the application is installed.
- Locate the new HelloWorld enterprise application in the Enterprise Applications node in the tree and browse both the EJB modules and the Web Modules. They contain the modules you just installed and the CMP will have the new datasource associated to it. You can always make changes and reapply them if you earlier made a mistake or omitted a step.
- Install the EJB Test Client from the Application Developer plugins as you
did with ASSE. In this example, you will install a single version of the EJB
Test Client Web application and change the module visibility as described
below. Alternatively, you could install a separate EJB Test Client for each
While working through this tutorial, I discovered that in AE, when installing EAR modules from directories named "
.ear" that are not actual EAR archives, the application does not get fully installed (the Administrative Console seems to indicate that it was installed, but if you look in the installedApps directory, you'll notice that nothing was actually installed there). But in ASSE, this seems to work. So, first you need to "ear up" the Application Developer version of the EJB Test Client which lives in an extracted state in Application Developer and make the EAR file available to the application installer. The following very basic batch file will create an EAR file from the Application Developer installed EJB Test Client (with the assumption that the
@echo off @setlocal set e:\WSAD_HOME=%1 set WORKING_DIRECTORY=%2 set JAVA_HOME=%e:\WSAD_HOME%\plugins \com.ibm.etools.server.jdk set PATH=%JAVA_HOME%\bin;%PATH% REM clean up if necessary first rd %WORKING_DIRECTORY%\temp /S /Q md %WORKING_DIRECTORY%\temp MD %WORKING_DIRECTORY%\temp\META-INF xcopy %e:\WSAD_HOME%\plugins\com.ibm.etools.websphere.tools\ IBMUTC\IBMUTC.ear\META-INF %WORKING_DIRECTORY%\ temp\META-INF /S /E jar cvf %WORKING_DIRECTORY%\temp\UTC.war -C %e:\WSAD_HOME%\plugins\ com.ibm.etools.websphere.tools\IBMUTC\IBMUTC.ear\UTC.war\ . jar cvf %WORKING_DIRECTORY%\IBMUTC.ear -C %WORKING_DIRECTORY%\temp\ . rd %WORKING_DIRECTORY%\temp /S /Q @echo. @echo Done. You will find your IBMUTC.ear module in your designated working directory. @endlocal
- Run this batch file, supplying the Application Developer installation directory
and a working directory, to create your own
IBMUTC.earmodule which you will install in the next step. This batch file is available in the download if you prefer to use this method to create your EAR module.
- Once again, start the Add New Enterprise Application wizard, and install
IBMUTC.earfrom the directory you created it in. Although it is just a Web module, it is packaged in an EAR module so it is not considered a stand-alone application but an enterprise application. Give it an application name of IBMUTC. Go through all pages until you get to the last page and then click Finish. Other than the first page, simply accept the defaults.
- Just like I described for ASSE, one way to use the EJB Test Client (to interact
with EJBs in other modules) is to temporarily set the module visibility to
COMPATIBILITY. Select Default Server from the Application Servers
node and change the module visibility from MODULE to COMPATIBILITY.
Then, click the Apply button to apply the changes.
Figure 16. Switching the module visibility mode
- Since a configuration change at the global application server level has occurred, you must restart AE. Stop it and then start it again, all from the Administrative Console.
- When you have completed all of the above steps, you should have two enterprise applications installed, a new JDBC provider created, and a new datasource that uses the provider. Your application is set up to properly use these resources. Now it is time to test your application. You need to issue a command to actually start the applications you installed. You may find you need to restart the Default Server, then restart the two enterprise applications. Right-click on the IBMTUTC application and select Start. Do the same for the HelloWorld application. Everything should start without error.
- To test your core business logic, bring up the EJB Test Client by pointing your Web browser to: http://<hostname>:9080/UTC. Then, run the EJB Test Client on the HelloWorld EJBs exactly as you did in both Application Developer and in ASSE.
In this two-part Application Developer tutorial, I demonstrated how to create, test and debug an end-to-end J2EE application using the new WebSphere Studio Application Developer product. I also demonstrated how to deploy and test the application on both WebSphere Application Server ASSE and AE. This article demonstrates the close relationship between the various run times and the tools, which all share a common programming model. As such, they truly are part of a "WebSphere family."
Although this was a relatively simple application, it does nevertheless encompass the central J2EE artifacts and helps to show how easy it is to move your application from Application Developer to both editions of WebSphere Application Server 4.0, without any changes taking place in the underlying core application. We didn't have to change or recompile one line of code, and we used the same programming model throughout.
Note: The following [enclosed] code is sample code not created by IBM Corporation. This sample code is not part of any standard IBM product and is provided to you solely for the purpose of assisting you in the development of your applications. The code is provided "AS IS," without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample code, even if they have been advised of the possibility of such damages.