Using the VisualAge for Java WebSphere TestEnvironmentBy Craig Pelkie

Many iSeries 400 shops are starting to move their development efforts to web enablementusing WebSphere Application Server (WAS). Because WAS is a Java-based environment, itmakes sense to consider using IBM’s VisualAge for Java (VA Java) as one of your tools fordeveloping WAS applications. VA Java is an especially good choice for WAS developmentwhen you use its built-in WebSphere Test Environment (WTE).

The WTE provides the support needed to run and test servlets and JavaServer Pages frominside VA Java. If you don’t use the WTE, you need to either set up a Java applicationserver such as Tomcat on your PC or export your code from your PC to WAS. If you useeither of those approaches, you are then forced to test your code outside of the VA Javaenvironment, meaning that you no longer have access to the integrated debugger.

Perhaps the best news about the WTE is that it is provided with VisualAge for JavaProfessional Edition, version 3.5 and up. That version is included with the new IBMWebSphere Development Tools for iSeries Version 5.1, provided with OS/400 V5R1. If youdon’t have the WebSphere Development Tools, you can acquire VisualAge for Java byitself; the Professional Edition is significantly less expensive than the Enterprise Edition.Although it is possible to install and run VA Java on a low-end Pentium class PC with aslittle as 128MB of memory, you will be much more pleased with the performance of theWTE if you use a PC with a fast CPU and at least 256MB of memory. You can install VAJava and the WTE on a Windows 98, Windows Me, Windows NT 4.0 or Windows 2000 PC.

Installing the WTEThe WebSphere Test Environment is an optionally installable part of VisualAge for Java.When you install VA Java, you can choose to install the complete product or perform acustom install. If you choose the complete option, the WTE is installed. If you choose acustom install, you need to select the JSP Development Environment as a feature toinstall, as shown in the InstallShield Wizard panel (Figure 1). If you already haveVisualAge for Java installed on your PC but did not install the WTE, you can run the installprogram again and add the WTE to your existing configuration.

Figure 1: If you perform a custom install of VisualAge for Java, select the JSP Development Environment to install the WTE.

After installing the WTE, you need to add the feature to the VA Java workspace. In the VAJava Workbench (the default view of the Integrated Development Environment that isshown when you start VA Java), press the F2 key or select the File, Quick Start menu item.

On the Quick Start dialog (Figure 2), select the Feature, Add Feature option and click OK.In the Selection Required dialog shown in Figure 3, select the IBM WebSphere TestEnvironment and click OK. You can select more than one feature to add to the VA Javaworkspace if you want. When you add a feature, VA Java retrieves the required code fromits repository and adds new projects, packages and classes to the workspace. You shouldonly add features that you intend to use, since the start up and shut down times for VAJava are significantly longer when you have more features in the workspace.

After adding the feature to the workspace, you can verify that the feature is available bylooking for the IBM WebSphere Test Environment project in the All Projects frame, asshown in Figure 4. Note that even if you select only the WTE, VA Java also adds otherprojects that are required to support the WTE. You should not remove any of thoseautomatically added projects, as they are required for the WTE.

Figure 2: Select the Feature, Add Feature option on the Quick Start dialog to install additional VA Java features.

Figure 3: Select the IBM WebSphere Test Environment from the list of available features.

Figure 4: After adding the WTE, verify that the IBM WebSphere Test Environment project is in the All Projects list.

Using the WebSphere Test EnvironmentNow that you have the WTE incorporated into VA Java, you can use it to test and debugyour servlets and JavaServer Pages (JSP). If you already have a servlet or JSP that youwant to test, you can start using the WTE immediately. If you have not yet developed aservlet or JSP, you can still start the WTE and begin working with it, using the sampleservlets and JSP files that are included with the WTE.

You start the WTE by selecting the Workspace, Tools, WebSphere Test Environment menuitem, as shown in Figure 5. After selecting that option, the WebSphere Test EnvironmentControl Center is displayed (Figure 6). It may take up to a minute for the Control Centerto appear, since there is a lot of initialization work done when you start the WTE. After theControl Center appears, click the plus sign next to the Servers item to expand the options,as shown in Figure 6. Note: the Control Center is a Java GUI application. In some cases,the buttons and other GUI elements are not rendered correctly when the Control Center isdisplayed. You can click the minimize icon in the upper right corner, then click the icon inthe Windows tray to make the Control Center reappear. By forcing the GUI to repaint itself,you will usually be able to make it appear correctly.

Figure 5: Start the WTE with the Workspace, Tools, WebSphere Test Environment menu item.

Figure 6: The WebSphere Test Environment Control Center is used to start and set options for the WTE.

The first thing to do in the Control Center is click the Servlet Engine option, then click theEdit Class Path button. In the Servlet Engine Class Path (Figure 7), scroll through the list ofprojects and select the projects that include the Java classes you are using in your servletsand JSPs. Although you can click the Select All button to choose all of the current projects,you may not want to do that if you have many projects in your workspace, since it mightcause your servlets and JSPs to run more slowly in the test environment. After selecting theprojects to include in the class path, click the OK button to return to the Control Center.

Figure 7: You can select a list of projects in your VA Java workspace to appear in the WTE class path.

On the Control Center, you can now click the JSP Execution Monitor Options. The optionsare shown in Figure 8. You should select both the Enable monitoring and Retrieve syntaxoptions. You should leave the JSP execution monitor port set to its default of 8082 unlessyou know that you are running another TCP/IP application on your PC that uses that port.After checking the options, be sure to click the Apply button, as the options will not takeeffect unless you do.

Figure 8: Check both of the options on the JSP Execution Monitor Options panel to start monitoring JavaServer Pages.

You can now click the Servlet Engine option again to return to the options shown in Figure6. Click the Display trace messages option, then click the Start Servlet Engine button. TheWTE servlet engine now loads, which is similar to starting the actual WebSphere ApplicationServer. You will see the VA Java Console open (if it does not open as a visible window, clickits icon in the Windows tray to bring the Console window to the foreground). In the Consoleyou will see a series of status messages marking the progress of the WTE start up (seeFigure 9). When you see the message Servlet Engine is started, you can begin testingservlets and JSPs.

Figure 9: The VA Java Console displays status messages when you start the WTE.

Run the Java Servlet and JSP SamplesBefore testing your own servlets and JSPs, you should run the samples that are includedwith the WTE. I make it a practice to run the samples every time I start the WTE to verifythat the WTE is started correctly and ready to work. If the samples do not run, it is unlikelythat your own code will run either.

To load the samples, open your browser and enter the following URL:

http://127.0.0.1:8080/jsp/index.html

A page similar to Figure 10 should be displayed. There are three samples on the page;samples 1 and 3 are trivial programs that perform some calculations and display output toyour browser. Sample 2, the Servlet Engine Configuration sample, is actually quite usefulas it displays all of the options used by the WTE itself when it starts. The configurationoptions are stored in several properties files in the VA Java directories and can be edited ifit is necessary to change the behavior of the WTE. In most cases, you will simply use thedefault configuration of the WTE to test your servlets and JSPs before exporting them toWAS on your server. There are no particular configuration tools provided with the WTE tochange its configuration, beyond the options provided in the Control Center. IBM doesdocument the properties files and the options you might want to change, but theexplanations of the options are not always clear.

Figure 10: Use the Servlet Engine Configuration link on the VA Java servlet and JSP Samples page to view the WTEconfiguration options.

The value of displaying the configuration, as shown in Figure 11, is that you can determinethe document root directory. It is the incredibly long and complicated path shown in Figure11. The significance of the document root is that you need to save your HTML and JSP filesto that directory or in a subdirectory located in the document root directory so that the WTEwill be able to locate and serve the files.

Figure 11: The Configuration for Web Application page shows the document root, which is where your HTML and JSP filesmust be located.

Once you’ve located the document root setting as shown in Figure 11, you should navigateto the directory using your Windows Explorer program. In the /web directory you will find asubdirectory /jsp, and in that directory you will find the index.html file. That is the file thatyou requested when you typed the URL shown above to load the Samples page.

Because the index.html file is located in a subdirectory of the document root, you alsoinclude the subdirectory in the URL. Note that you do not include any of the otherdocument root directory names in the URL; the WTE starts looking for files andsubdirectories in the /web directory that is at the end of the document root. If you want, youcan add additional directories to the document root directory on your PC, then save HTMLand JSP files to that directory. To serve them, you simply include the name of the newsubdirectory in the URL, followed by the name of the HTML or JSP file that you want toserve.

Testing a ServletTo test a servlet, you enter a URL like this:

http://127.0.0.1:8080/servlet/com.web400.JdbcPartsServlet

You need to specify the directory name /servlet, as that special name indicates to the WTEthat it will be running a servlet. After that, you specify the full package-qualified name ofthe servlet class file. In the URL shown above, the servlet class file name is JdbcPartsServletand it is contained in a package named com.web400. Note that you request a servlet by itspackage name, which is not the same as the project that contains the package. A project is aVA Java construct used to organize groups of packages. The WTE does not care about yourproject name, but it does need to know the package name so that it can locate and serveyour servlet.

Because the WTE is running under the control of VA Java, you can set breakpoints in yourservlet class file in the VA Java Source window. When the WTE runs your servlet, it will stopat the breakpoints. You can then use the VA Java breakpoint tools to step through thesource, examine and change values, or stop executing the servlet. The ability to debug aservlet at the source code level is quite valuable, especially when you have a servlet thatruns but does not produce any visible output.

Testing a JSPTo test a JSP, you enter a URL like this:

http://127.0.0.1:8080/jspTest.jsp

In this case, the file jspTest.jsp is located in the document root directory, as shown in Figure11.

When you run a JSP with the monitor option set (shown in Figure 8, JSP Execution MonitorOptions), the JSP Execution Monitor (“JEM”) opens, as shown in Figure 12. The JEMdisplays the source code of the JSP, the source code for the servlet that was created whenthe JSP was compiled and the resulting HTML from the execution of the JSP. Note, the JSPis automatically compiled to a servlet when you initially request it or after you make anychanges to the JSP source code itself; you simply create, test and work with the JSP source.

Figure 12: The JSP Execution Monitor is used to step through a JSP as it runs.

Using the JEM, you can step through the JSP code a line at a time. As you step through,you can view the corresponding servlet code that is executed and the resulting HTML. Ifthere are any errors, you can open the VA Java Debugger and examine the value of anyvariables. You can also have the JSP continue executing in “run” mode (you can visuallytrack its execution), or continue execution in “fast forward” mode (you simply see theresulting output, not each step of the execution).

Although JSPs are very easy to write, compared to the equivalent servlet code, they can bequite difficult to debug if you are simply depending on text output to the browser. Beingable to perform breakpoint debugging on a JSP while developing it is a tremendousproductivity aid.

About the URLsYou have probably noticed that the URL you use to invoke the WTE starts like this:

http://127.0.0.1:8080

If you are familiar with TCP/IP, you recognize the TCP/IP address as being the loopbackaddress. In fact, you can enter any of the hostnames as shown in Figure 9 to start runninga servlet or JSP in the WTE (localhost, 127.0.0.1, the PC’s network name or its unique TCP/IPaddress). The TCP/IP address or name in each case points back to the PC you are runningthe WTE on. The important part of the URL is the port 8080, which is assigned to the WTEwhen you start it running on your PC. In the unlikely event that you have another TCP/IPapplication running on your PC that uses that port, you will either have to reassign theother application’s port number, or delve into the WTE configuration files and assign adifferent port number.

Note that the WTE itself uses port 8080 and the JEM uses port 8082 (see Figure 8). Whenyou test a JSP, you test it by passing your request to port 8080, as shown in the URLabove. The WTE uses port 8082 internally to talk with the JEM. You never enter 8082 asthe URL port to invoke WTE services from the browser.

WTE SummaryThe point of knowing about the WTE and how to work with it is twofold:

1) You can have a complete development, test and debugging environment on yourPC. You can test servlet and JSP code without needing to export it to and configure itin WAS. If you copy some test data from your iSeries 400 database files to PC files(for example, to an Access database), you can use the JDBC-ODBC driver to connectto the test files and completely simulate the run-time environment of the servlet orJSP.

2) It is much simpler to test a servlet or JSP with the VA Java breakpoint anddebugger facilities. Although you can establish a remote debugging session from VAJava to WAS running on the iSeries 400, it is much simpler to just start up the WTEon your PC and test the code there. Also, if you need to make modifications to aservlet or JSP that is already in production, it will be far more comfortable to makeyour modifications and tests off-line, rather than trying to change code that is inuse.

Another point about the WTE is that it is not obvious from the VA Java packaging orenvironment that such a feature even exists. I remember being quite surprised to find outthat this was included with VA Java, and especially surprised to find that IBM includes it inthe Professional Edition of VA Java. The documentation for the WTE is included in the setof PDF manuals that are installed with VA Java, and can be accessed through the VA JavaHelp system (look for the “WebSphere Test Environment” and “JSP/Servlet DevelopmentEnvironment” manuals).

If you are just getting started with WebSphere programming, you should make theVisualAge for Java WebSphere Test Environment one of your first stops. If you are familiarwith servlet and JSP programming, you will probably be pleasantly surprised to find outabout this tool. Properly used, it will save you hours of debugging time.

Copyright © 2003, Craig Pelkie. All Rights Reserved

No part of this presentation or the accompanying computer source code may be reproducedor distributed in any form or by any means, or stored in a database or data retrievalsystem, without the prior written permission of Craig Pelkie, who is the author of thepresentation and the computer source code.

All computer source code distributed with this presentation, either on diskettes, CD-ROM,or available for downloading from sources such as the Internet is Copyright © 2003 CraigPelkie, All Rights Reserved. The source code is for use in computer programs that youdevelop for internal use within your company, or for use within programs that you developfor the use of your clients, when such programs are compiled and distributed in anexecutable computer program such that no part of the source code is readily visible withoutthe aid of a computer program disassembler. No part of the computer source codedistributed with this presentation shall be reproduced in source code format, either printedor in electronic format, by you or by others who you allow to have access to the sourcecode. You shall not cause the source code to be stored on any information retrievalsystem, such as computer Bulletin Board Systems or the Internet. You shall not developany written articles, books, seminar materials, or other presentations that include thesource code provided on the diskettes accompanying this manual or within the manualitself.

For any questions regarding your rights and responsibilities using the computer sourcecode distributed with this presentation, contact Craig Pelkie, Rochester Initiative, who is theowner of the source code.

LIMITATION OF LIABILITY AND DISCLAIMER OF WARRANTY

No representation is made that any of the programs, computer source code, commands, orconfigurations described and depicted in this manual and on the computer source codeaccompanying this presentation are error-free and suitable for any application that youmay develop. Craig Pelkie makes no warranty of any kind, expressed or implied, includingthe warranties of merchantability or fitness for a particular purpose, with regard to theinformation, examples, and computer source code presented in this presentation and onthe accompanying diskettes. Everything provided in this manual and on the accompanyingdiskettes is provided “as is”. Craig Pelkie shall not be liable in any event for incidental orconsequential damages or any other claims, pursuant to your use of any of the techniquespresented in this presentation, or your use of the computer source code in programs thatyou develop, even if Craig Pelkie has been advised of the possibility of such damages.

You are responsible for testing any and all programs, configurations, commands, andprocedures presented in this manual prior to using the programs, configurations,commands, and procedures with important user data. You must ensure that adequate andsufficient backup of important user data is available, in the event that recovery of theimportant user data is required.