HelloWorld
iPlanet^TM Application Server Samples

Updated June 12, 2001

If you already went through the deployment process of HelloWorld you can run the application by clicking here.

The HelloWorld sample is a simple application based on HTML, Servlets, EJBs, and JSPs. Assembling this application and deploying it to iPlanet Application Server provides an introduction to the server's assembly, deployment and registration tools.

Application Overview

Let's assume that you want to create a small application to demonstrate web-based access to a stateless session bean via a servlet and JSP. The application look and feel is described below.

a. Bring up a web page with a form like this:

b. Enter your name and press the Process button

c. A servlet is invoked. The servlet will be the "controller" for the application.

d. The servlet calls a stateless session bean to determine a greeting based upon the current system time. This EJB fulfills the role of the "model" for our app.

e. The servlet dispatches a JSP to deliver the greeting back to the browser. The JSP servers as the "view" component of our application.

f. As a result of the JSP execution, you see the following page returned to your browser:

The terms "model," "view" and "controller" are used in the description above. If you have done Smalltalk programming, you may recognize the MVC (Model/View/Controller) design pattern. Each part of an MVC design has an independent role. The "model" is the business policy implemented by the application. For us here, it is the EJB that knows how to create appropriate greetings (the "Good afternoon" message would be "Good evening" instead if you ran the application after 6 PM, for example). The "view" is the component that handles the user interface display. That's our JSP. And finally, the "controller" is the traffic cop that provides a single control point from which worker components are dispatched.

Setting Up the Environment

Getting Started includes a checklist of prerequisites for deploying sample applications to iPlanet.

Deploying and Running the HelloWorld Application

Select one of two approaches to deploying the application:

Command Line-based Deployment describes how to manually register the HelloWorld application in iPlanet using a Command Line Interface (CLI). This is the fastest means of deploying HelloWorld to the application server.

GUI-based Deployment describes how to use the iPlanet Deployment Tool to import and deploy the HelloWorld application. It also addresses assembling the application from scratch using the Deployment Tool.

Running the Application describes how to start the application, navigate through it and how to troubleshoot in the event of problems.

Further Exploration

Compiling and Assembling the Application describes how to use command line tools to recompile the sources and rebuild the WAR and EJB modules and the overall EAR file.

Command Line-based Deployment

You have a choice of deploying and registering the application through either command line utilities or the iPlanet Application Server Deployment Tool GUI. Since a complete EAR file is supplied, the fastest means of setting up the application is to use the command line utilities as described in this section. If you would like to experience either deploying through a GUI tool or assembling an application from scratch, then follow instructions in GUI-based Deployment.

The pre-built helloworld.ear file is a Enterprise ARchive file that contains the Web Archive (WAR) and EJB JAR files for the HelloWorld application. Within each of these JAR files reside the XML deployment descriptor files, application class files, JSPs and other content required by the application.

Deploying the pre-built helloworld.ear file is simple.

1. Go to the root of the HelloWorld sample directory:

install_dir/ias/ias-samples/helloworld/

2. Execute iasdeploy to deploy application to the local application server instance:

iasdeploy deployapp helloworld.ear

Refer to the Getting Started section for more information on using the iasdeploy command.

The deployment process involves the following operations:

iasdeploy authenticates against the local application server's administrative server.
the EAR file is transferred to the administrative server.
the administrative server begins the registration process:
- parses the EAR file and embedded WAR and EJB JAR files
- registers the J2EE application "helloworld" in the iPlanet Registry within the directory server
- registers the embedded J2EE modules (WARs and EJB JARs) in the iPlanet Registry within the directory server
- extracts the EJB JAR and WAR modules to the JAR/ directory.
- expands the content of the J2EE modules to the APPS/helloworld/ directory.

If you would like to verify the registration of the application, proceed to Verifying Registration.

Otherwise, you're ready to exercise the application by Running the Application.

GUI-Based Deployment

The Deployment Tool provides an easy-to-use means of assembling J2EE applications and deploying applications to iPlanet Application Server. For most cases, use of Deployment Tool is recommended over the approach of manually creating XML-based deployment descriptors and manually assembling J2EE modules and application JAR files.

Two approaches to using the Deployment Tool are described:

Import Pre-existing EAR File to quickly deploy the HelloWorld application to iPlanet using the Deployment Tool. None of the application assembly steps are covered by this section. On average, this approach will take 10 minutes.
or
Assemble the Application to learn how to use Deployment Tool to assemble the application from scratch and to deploy it to the application server. On average, this approach will take from 30 to 60 minutes.

Import Pre-existing EAR File

Since a pre-built Enterprise ARchive (EAR) file for the HelloWorld application is included with the application server, you can use the Deployment Tool to quickly read in the .ear file and deploy it to the application server.

Open the pre-existing HelloWorld EAR file.

Launch the Deployment Tool.

UNIX:
Execute install_dir/ias/bin/deploytool
Windows:
Start->Programs->iPlanet Application Server 6.0->iAS Deployment Tool

Open the EAR file

In the startup dialog, select "Browse for more applications" to find the helloworld.ear file.
Navigate to ias/ias-samples/helloworld/ and open the helloworld.ear file.
Click on the file name to expand the EAR file.
Proceed to Deploying the Application

Assemble the Application

This approach involves assembling the HelloWorld application from scratch. After compiling the Java sources, you will start Deployment Tool and create the application WAR, EJB JAR and EAR files. Then you will deploy the application to the application server.

Compile Application Sources
Create helloworldEjb.jar Module
Create helloworld.war Module
Assemble helloworld.ear
Deploy Application

Compile Application Sources

To compile the application sources, simply execute "build compile" under the application's src/ directory. See the section Compiling and Assembling the Application for more information on recompiling the application using the supplied build facility.

Create helloworldEjb.jar Module

Now that the source files have been compiled into Java .class files, you are ready to begin assembling the application. Your first step is to create the EJB JAR file.

Insert EJBs and Supporting Classes

1. Create assembly location:

Create the new directory install_dir\ias\ias-samples\helloworld\assemble\ outside the Deployment Tool. You will assemble the application into JAR files and save them to this directory.

2. Launch the Deployment Tool:

UNIX: Execute install_dir/ias/bin/deploytool&
Windows: Programs->iPlanet Application Server 6.0->iAS Deployment Tool

3. Create helloworldEjb.jar:

In the startup dialog, select New EJB Application (.jar file)
Alternatively, if Deployment Tool is already started, select File -> New.
Click on EJB JAR Module.
Enter "helloworldEjb.jar" as the archive file name.
Click on Browse to navigate to the directory install_dir\ias\ias-samples\helloworld\assemble\
Click on OK to exit the dialog window.
The EJB JAR module appears in the EJB pane of the Deployment Tool window.
Click on Component View to see only the name of the EJB JAR module without the directory path.

4. Now insert all class files needed in the helloworldEjb.jar file:

Select the EJB JAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
Navigate to the directory in which the sample application's EJB classes resides:

ias-samples\helloworld\build\classes\samples\helloworld\ejb\

In the left hand pane, select all EJB class files. Click on the double arrows (>>) to move the selected classes into right side of the dialog window. For HelloWorld, we're placing all of the class files save for servlet classes in the EJB JAR module and only servlet classes in the WAR module.
Click on Resolve to determine if any of the included classes depend on classes that are not part of the EJB JAR module. (You'll notice that the classes change from red to blue as they are resolved. Any files remaining as red are dependent on classes not included in the EJB JAR module. The unresolved references do not inhibit you from adding the classes to the EJB JAR module.) You might encounter a warning of unresolved class dependencies. Click on Resolve again to attempt the resolution again.
Click on Insert to add the classes to the EJB JAR module.
Since you selected Component View, you'll see the EJB listed in the EJB module window. Deployment Tool introspects the classes to determine the EJBs, if any, contained in the inserted classes.
Click on File View to see the complete list of files added to the module.

Modify Deployment Descriptor Settings for Greeter EJB

1. Modify Descriptor for Greeter EJB

Click on Component View.
Select the GreeterEJB, right mouse click and select Edit Descriptor.
Adjust the EJB descriptor window size to see all of the settings.
Note the unique GUID (Globally Unique IDentifier) assigned to the EJB. This ID is used by the application server to manage the EJB as a unique component throughout the application server.
The next steps in this section lead you through modifications to the EJB descriptor.

2. Begin Modifying the Greeter EJB Descriptor

Set Bean Name to TheGreeter
Set State Management Type to Stateless

3. Close the Descriptor for the EJB

Now we can close the EJB descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes.

Save and close helloworldEjb.jar

Before closing the EJB JAR file, you might find it useful to double check your settings against the previous instructions.
Select the helloworldEjb module in the EJB Modules window.
Select File->Close to save and close the EJB JAR file.

Now that we've assembled the EJB JAR module, we're ready to move on to assembling the Web Application aRchive (WAR) file.

Create helloworld.war Module

Identify the Content for WAR File

1. Create helloworld.war:

In the startup dialog, select New Web Application (.war file)
Alternatively, if Deployment Tool is already started, select File -> New.
Click on Web Application.
Enter "helloworld.war" as the archive file name.
Click on Browse to navigate to the directory install_dir\ias\ias-samples\helloworld\assemble\
Click on OK to exit the dialog window.
The WAR module appears in the Web Applications pane of the Deployment Tool window.
Click on Component View to see only the name of the WAR module without the directory path.

2. Now insert all class files needed in the helloworld.war file:

Select the helloworld.war file from the Web Applications pane (it may be in either FileView or ComponentView)
Right-click on the helloworld.war file and select Insert Files... from the pop-up menu (this may also be done by selecting Edit -> Insert Files... from the menu bar
Navigate to the directory in which the sample application's servlet class resides:

ias-samples\helloworld\build\classes\samples\helloworld\servlet\

Highlight the GreeterServlet.class file and click the right arrows to add it to the list of classes to be added to the WAR file
Click the Resolve button. This ensures that all of the servlet's dependent classes can be resolved before it's added to the WAR file (you'll notice that the servlet name in the right-hand pane changed from red to blue--indicating that all of it's dependent classes can be resolved)
Click the Insert button to add the servlet to the WAR file

3. Add JSP and HTML files needed to the .war file

Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
Navigate to path install_dir\ias\ias-samples\helloworld\src\docroot directory.
Press Shift key, then select the JSP and HTML files.
Click on the double arrows (>>) to move these files into right side of the dialog window.
Click on Resolve to modify the location of these files relative to the root of the WAR file.
Select al files using the Shift key.
Set the Update Destination Path to blank since the application requires that these files be located at the root of the WAR module. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
Click on Insert to close the insert dialog window and to add the files to the WAR.
Click on File View

Modify Web Application Descriptor

Now we need to make several changes to settings at the WAR module level. To do so, select either the WAR file path if in File View or the WAR module name if in Component View. Right click and select Edit Descriptor.

As described for the helloworldEjb.jar, in the following paragraphs, the title gives the tab name, where you have to enter the data given below.

References Tab

EJB References:

Reference Bean Type Linked to Bean Bean Home Interface Bean Remote Interface

ejb/greeter Session TheGreeter samples.helloworld.ejb.GreeterHome samples.helloworld.ejb.Greeter

Save and close helloworld.war

Before closing the WAR file, you might find it useful to double check your settings against the previous instructions.
Select the WAR module in the Web Applications window.
Select File->Close to save and close the WAR file.

Now that we've assembled both J2EE modules (EJB JAR and WAR), we're ready to move on to assembling the modules into an EAR file.

Assemble helloworld.ear

1. Create helloworld.ear:

In the startup dialog, select New J2EE Application (.ear file)
Alternatively, if Deployment Tool is already started, select File -> New.
Click on J2EE Application.
Enter "helloworld.ear" as the archive file name.
Click on Browse to navigate to the directory install_dir\ias\ias-samples\helloworld\assemble\
Click on OK to exit the dialog window.
The EAR file appears in the J2EE Applications pane of the Deployment Tool window.
Click on Component View to see only the name of the EAR without the directory path.

2. Add helloworldEjb.jar and helloworld.war Files:

Select the helloworld EAR entry.
Right click, select Insert Files.
Navigate to the install_dir\ias\ias-samples\helloworld\assemble\ directory.
Select both the EJB JAR and WAR files.
Click on the double arrows (>>) to move these files into right side of the dialog window.
Click on Resolve to modify the location of this file relative to the root of the EAR file.
Select all files using the Shift key.
Set the Update Destination Path to blank since the J2EE modules should appear at the root of the EAR file. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
Click on Insert to close the insert dialog window and to add the files to the EAR.

3. Set Context Root for Web Application

Next, we need to set the context root of the web application. This value will appear in URLs that access web application components. For example, in the URL http://localhost/NASApp/helloworld/GreeterServlet the "helloworld" value is the context root of the web application.

Select EAR module, right click and select the Context Root tab
Set the Context Root to "helloworld".
Close the descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes.

4. Save helloworld.ear:

Select the EAR file in the J2EE Applications window.
Select File->Close to save and close the EAR file

Now that the EAR file has been assembled, the next step is to deploy the application to an application server instance.

Deploy the Application

Now you're about to deploy the application by transferring the EAR file to a target iPlanet Application Server. First, you will identify the target server. After the EAR file is deployed to the server, registration occurs. After deployment completes, you will be able to run the application. No server restart is required.

If you followed the assembly instructions, then helloworld.ear is opened in Deployment Tool. If you opened the pre-existing EAR file, you are working with install_dir\ias\ias-samples\helloworld\helloworld.ear. If you are following the "Create EAR File from Scratch" instructions, you are modifying install_dir\ias\ias-sample\helloworld\assemble\helloworld.ear.

If you entered all deployment information manually, you can skip the following steps 1 to 3, because you have entered this information already.

1. Select the helloworld.ear file under the J2EE Application window.

2. Select File -> Deploy

3. If you have not already registered a target application server, do so now by clicking on the Register button. Enter the host name, administrative port number and username/password for the target application server. Otherwise, select a pre-registered target server.

Note: You may authorize additional users to deploy applications to an application server by using the application server's Administrative Console. See the Security settings tab in the Administrative Console.

5. If you deployed helloworld.ear previously, then select Overwrite Modules.

4. Click on Deploy to start the deployment process.

6. Now the file transfer and application registration begins. See the Deploy tab for the status of the deployment. The deployment may take several minutes to complete.

Verifying Registration

As an optional step, you can use the iPlanet Application Server Administration Tool to verify that the application has been registered. If you do not want to verify that the application has been registered, proceed directly to Running the Application.

Start the application server's Admin Tool

UNIX:
install_dir/ias/bin/ksvradmin
Windows:
Start->Programs->iPlanet Application Server->iAS Administration Tool

Connect to your application server instance by selecting File->New->Server. Click on Localhost to specify the default connection settings. Enter the application server administrator's password and click on OK.
Select the server name (default name of iAS1) and select the Application button in the top right hand corner of the window to see the applications registered in this application server instance.
You should see several folders for the "helloworld" J2EE application. The "helloworld" folder with the world icon represents the web application module while the "helloworldEjb" folder represents the EJB module packaged as part of the HelloWorld application.

To see more details associated with the HelloWorld application, you can use the lower level tool named kregedit to browse the contents of the application server Registry:

Execute kregedit to start the application server's Registry Editor GUI.

Navigate to the SOFTWARE/iPlanet/Application Server/6.0/ portion of the tree.

Browse the J2EE-Application/ tree and look for the "helloworld" application.

Expand the "helloworld" folder and explore this portion of the directory tree.

Now open the J2EE-Module/ tree and look for the "helloworld" web application module entry and the "helloworldEjb" EJB module entry.

Expand each of these folders and explore their contents.

Once you find the GUID associated with each EJB in the HelloWorld application, you can navigate through the SOFTWARE/iPlanet/Application Server/ClassDef/ folders to find out more details on each EJB. Expanding the matching GUID folders under the ClassDef folder will show you the detailed settings associated with each EJB. Many of these settings appear in the XML deployment descriptors for EJBs.

Running the Application

Then start the application by accessing the URL:

http://<web server hostname>:<port>/NASApp/helloworld/index.html

Enter your name and click submit. You should see a greeting message with your name displayed.

Troubleshooting

If you encounter problems when running the application, review the General Troubleshooting section to learn how to view logs files.

Compiling and Assembling the Application

To easily recompile, assemble and deploy the application, see the Sample Application Build Facility document for details on using a build facility to quickly perform these tasks.

For example, to rebuild the entire application from scratch, follow these steps:

1. Compile and Assemble EJB JAR Components and Web Application

Execute "build" under helloworld/src/

The default target core will be executed to rebuild the EJB JAR and WAR files as well as the web application's EAR file.

2. Redeploy Application

Execute "build deploy" under helloworld/src/

3. Restart Application Server

An application server restart will be necessary if you've modified either deployment descriptors or EJBs. For servlet and/or JSP modification, no restart is is necessary.

To clean the web application project area, execute "build clean".

Reference	Bean Type	Linked to Bean	Bean Home Interface	Bean Remote Interface
ejb/greeter	Session	TheGreeter	samples.helloworld.ejb.GreeterHome	samples.helloworld.ejb.Greeter

HelloWorld iPlanetTM Application Server Samples