Fortune
iPlanetTM
Application Server Samples
Updated June 18, 2001
You can run the application by clicking here.
The Fortune sample is a simple application based on a servlet driving a JSP.
Assembling this application and deploying it to iPlanet Application Server
provides an introduction to the server's assembly, deployment and registration
tools. If you're interested in configuring an application that uses an EJB in
addition to a servlet and JSP, see the HelloWorld
sample application. Although the Fortune application is pre-registered during
installation of iPlanet Application Server, the following instructions describe
how to either manually deploy the application or assemble the application from
scratch using the iPlanet Deployment Tool. You might want to experiment by modifying
the Fortune example and redeploying it using the following instructions.
Setting Up the Environment
Getting Started includes a
checklist of prerequisites for deploying sample applications to iPlanet.
Deploying and Running the Application
Select one of two approaches to deploying the application:
Command Line-based Deployment describes how to
manually register the application in iPlanet using a Command Line Interface
(CLI). This is the fastest means of deploying the application.
GUI-based Deployment describes how to use the
iPlanet Deployment Tool to import and deploy the sample 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
module 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 fortune.ear
file is a Enterprise ARchive file that contains the Web Archive
(WAR) file of the application. Within the WAR file resides the XML deployment
descriptor files, application class files, JSPs and other content required by
the application.
Deploying the pre-built fotune.ear
file is simple.
1. Go to the root of the sample directory:
install_dir/ias/ias-samples/fortune/
2. Execute iasdeploy
to deploy application to the local application server instance:
iasdeploy
deployapp fortune.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 file
- registers the J2EE application "fortune" in the iPlanet Registry within
the directory server
- registers the embedded WAR module in the iPlanet Registry within the
directory server
- extracts the WAR module to the JAR/
directory.
- expands the content of the WAR module to the APPS/fortune/
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 Fortune application to iPlanet using the Deployment Tool. None of
the application assembly steps are covered by this section. On average, this
approach will take 5-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 15-30 minutes.
Import Pre-existing EAR File
Since a pre-built Enterprise ARchive (EAR) file for the sample 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 sample 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
fortune.ear file.
- Navigate to ias/ias-samples/fortune/
and open the fortune.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 Fortune application from scratch. After
compiling the Java sources, you will start Deployment Tool and create the application
WAR module and EAR files. Then you will deploy the application to the application
server.
- Compile Application Sources
- Create fortune.war
Module
- Assemble fortune.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 WAR Module
1. Create assembly location:
Create the new directory install_dir\ias\ias-samples\fortune\assemble\
outside the Deployment Tool. You will assemble the application
into archive files and save them to this directory.
2. Launch the Deployment Tool:
Start->Programs->iPlanet Application Server 6.0->iAS Deployment Tool
3. Create fortune.war:
- In the welcome dialog, select the Create a New Application radio
button and click OK
- Alternatively, if Deployment Tool is already started, select File ->
New...
- Make the following selections in the New Application or Module dialog
box:
- Select the Web Application (.war) radio box in the Application
Type panel
- Use the filename fortune.war
- To select the destination directory, left-click the Browse...
button and choose the directory install_dir\ias\ias-samples\fortune\assemble
- Click OK
4. Now insert all class files needed in the
fortune.war file:
5. Add JSP file 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\fortune\src\docroot
directory.
- Press Shift key, then select the JSP file.
- Click on the double arrows (>>) to move the file into right side of
the dialog window.
- Click on Resolve to modify the location of the file 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 the file 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
file to the WAR.
6. Review the Fortune XML descriptor (this is an optional step):
- In the Web Applications pane, expand the
fortune.war by clicking on the switch to the left of the file name.
Once the WAR file is expanded, you should be able to see the FortuneServlet.class.
- Click on the FortuneServlet.class
to select it and then right-click on the servlet and select Edit Descriptor
(this may also be done by selecting from the menu bar Edit -> Edit
Descriptor
- You can review the descriptor settings by clicking on each of the tabs
at the top of the descriptor window. It's not necessary to modify any of these
values for this sample application. When you're through reviewing the settings,
you can simply close the descriptor window by clicking the close box in the
upper right-hand corner
7. Modify the Web Application XML descriptor
- In the Web Applications pane, right-click on the fortune.war
file and select Edit Descriptor (this may also be done
by selecting the WAR file and choosing Edit -> Edit Descriptor from
the menu bar)
- Next, we'll add a servlet name mapping to the descriptor.
- Click on the Servlet tab.
- Under Servlet Mapping, click Add
- In ServletName, enter "FortuneServlet".
- In URL pattern, enter "/fortune".
- This mapping is a means of aliasing the original servlet name.
- Close the descriptor window by clicking the close box in the upper right-hand
corner. When prompted, choose to save the descriptor settings
8. Save and close the web application archive
- In the Web Applications pane, click on the fortune.war
file to select it
- From the menu bar, select File -> Save to save the WAR file
- Right-click on the fortune.war
file and select Close to close the WAR file (this may
also be done by selecting File -> Close
Now that you've assembled the WAR module, you are ready to create the Enterprise
ARchive (EAR) file.
Assemble fortune.ear
1. Create fortune.ear:
- Choose File -> New... from the Deployment Tool menu bar
- Make the following selections in the New Application or Module dialog
box:
- Select the J2EE Application (.ear) radio box in the Application
Type panel
- Use the filename fortune.ear
- To select the destination directory, left-click the Browse...
button and choose the directory install_dir\ias\ias-samples\fortune\assemble
- Click OK
2. Add fortune.war:
- Select the fortune.ear
file from the J2EE Applications pane (it may be in either
FileView or ComponentView)
- Right-click on the fortune.ear
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 fortune.war
file resides: install_dir\ias\ias-samples\fortune\assemble\
- Highlight the fortune.war
file and click the right arrows to add it to the list of modules
to be added to the EAR file
- Click the Resolve button. This ensures that all of the module's
dependent classes can be resolved before it's added to the EAR file.
It will ask you to update the file destination paths--simply select the file
from the list and click Update and then click OK
- Click the Insert button to add the web application to the EAR file
3. Review the application XML descriptor (this is an optional step):
- In the J2EE Applications pane, right-click on the fortune.ear
file and select Edit Descriptor (this may also be done by selecting
Edit -> Edit Descriptor from the menu bar)
- You can review the descriptor settings by clicking on both of the tabs
at the top of the descriptor window. It's not necessary to modify any
of these values for this sample application. When you're through reviewing
the settings, you can simply close the descriptor window by clicking the close
box in the upper right-hand corner
4. Modify the Web Application Context Root
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/fortune/fortune
the first occurrence of "fortune"
is the context root of the web application.
- Select EAR module, right click and select the Context Root tab
- Set the Context Root of the Fortune WAR module to "fortune".
- 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.
5. Save fortune.ear:
- In the J2EE Applications pane, click on the fortune.ear
file to select it.
- From the menu bar, select File -> Save to save the EAR file
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 fortune.ear
is opened in Deployment Tool. If you opened the pre-existing EAR file, you are
working with install_dir\ias\ias-samples\fortune\fortune.ear.
If you are following the "Create EAR File from Scratch" instructions, you are
modifying install_dir\ias\ias-sample\fortune\assemble\fortune.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 fortune.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 fortune.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 instance of the application server.
- You should see several folders for the "fortune" J2EE application. The
"fortune" folder with the world icon represents the web application module.
To see more details associated with the Fortune application, you can browse the
iPlanet Application Server Registry using a tool named kregedit:
- 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 "fortune" application.
- Expand the "fortune" folder and explore this portion of the directory tree.
- Now open the J2EE-Module/
tree and look for the "fortune" web application module entry.
- Expand each of these folders and explore their contents.
- Once you find the GUID associated with servlet in the Fortune application,
you can navigate through the SOFTWARE/iPlanet/Application
Server/ClassDef/ folders to find out more details on the servlet.
Expanding the matching GUID folder under the ClassDef
folder will show you the detailed settings associated with the servlet.
Running the Application
To run the application, go to the following URL:
http://<web server
hostname>:<port>/NASApp/fortune/fortune
Repeatedly click on the browser's reload button to see a new fortune appear.
Troubleshooting And Notes
- Although the war, ear, context-root and servlet alias names in this sample
are all "fortune", it is not necessary that it is so. The application
will work as expected if the names of each of these attributes is unique.
Rebuild the app after changing the context-root (in application.xml), the
servlet alias (in web.xml) and the war and ear names (in the Ant build.xml),
redeploy and test the sample to confirm this.
- 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 Web Application
Execute "build"
under fortune/src/
The default target core
will be executed to rebuild the WAR and EAR files.
2. Redeploy Application
Execute "build deploy"
under fortune/src/
3. Restart Application Server
An application server restart will be necessary if you've modified deployment
descriptors. For servlet and/or JSP modification, no restart is is necessary.
To clean the web application project area, execute "build
clean".
Copyright
(c) 2001 Sun Microsystems, Inc. All rights reserved.