Chapter 14   Taking Advantage of the iPlanet Application Server Features


This chapter describes how to implement the iPlanet™ Application Server features in your application. The iPlanet Application Server provides many additional features to augment your servlets for use in an iPlanet Application Server environment. These features are not a part of the official servlet specification, though some, like the servlet security paradigm described in Chapter 13 "Writing Secure Applications," are based on emerging Sun Microsystems® standards and conforms to these future standards.

This chapter contains the following sections:

• Caching Servlet Results

• Using a Startup Class

Caching Servlet Results

---

The iPlanet Application Server has the ability to cache a servlet's results in order to make subsequent calls to the same servlet faster. The iPlanet Application Server caches the request results (for example, a servlet's execution) for a specific amount of time. In this way, if another data call occurs the iPlanet Application Server can return the cached data instead of performing the operation again. For example, if your servlet returns a stock quote that updates every 5 minutes, you set the cache to expire after 300 seconds.

Whether to cache results and how to cache them, depends on the data type involved. For example, it makes no sense to cache the results of a quiz submission because the input to the servlet is different each time. However, you could cache a high level report showing demographic data taken from quiz results and updated once an hour.

You can define how an iPlanet Application Server servlet handles memory caching by editing specific fields in the servlet's configuration file. In this way, you can create programmatically standard servlets that still take advantage of this valuable iPlanet Application Server feature.

Table 14-1 shows the caching settings in a servlet configuration file.

Table 14-1    Servlet Cache Settings

Name	Type	Value
cache-timeout	Integer	Optional. Elapsed time (in seconds) before the servlet's memory cache is released.
cache-size	Integer	Optional. Servlet memory cache size (in KB).
cache-criteria	String	Optional. Criteria expression string containing comma-delimited descriptors. Each descriptor defines a match with one servlet input parameter.
cache-option	String	Optional. Sets the cache timeout option to either TIMEOUT_CREATE or TIMEOUT_LASTACCESS.

For more information on these settings, see "Elements for Specifying Servlet Caching."

The cache-criteria field sets criteria to determine if servlet results are cached. This field tests one or more fields in the request. This allows conditionally cache results based on value or presence of one or more fields. If the tests succeed, the servlet results are cached.

Table 14-2 shows the cache-criteria field syntax.

Table 14-2    CacheCriteria Field

Syntax	Description
arg	Tests whether an arg value is in the input parameter list. For example, if the field is set to "EmployeeCode", results are cached if a request contains an "EmployeeCode" field.
arg=v	Tests whether arg matches v (a string or numeric expression). For example, if the field is set to "stock=NSCP", results are cached if the request contains a stock field with the value NSCP. Assign an asterisk (*) to the argument to cache a new results set when the servlet runs with a different value. For example, if the criteria is set to "EmployeeCode=*", results are cached if the request object contains a field called "EmployeeCode" and the value is different from the currently cached value.
arg=v1|v2	Tests whether an arg matches a list value (v1, v2, and so on). For example: "dept=sales|marketing|support".
arg=n1-n2	Test whether an arg number is within the given range. For example: "salary=40000-60000".

Using a Startup Class

---

A startup class is a user-defined class object that is automatically loaded into memory when the iPlanet Application Server starts up. It performs initialization tasks within the Application Server environment. The characteristics of a StartupClass object are:

• It spans through the life of server in which it runs.

• It is notified when the server shuts down.

• It runs within the JVM of a kjs process, so each kjs process owns one instance of the StartupClass object.

A startup class must meet the following requirements:

• It must be in the package com.iplanet.ias.startup.

• It must be named StartupClass.

• It must implement the interface com.iplanet.ias.startup.IStartupClass.

  
  

  ---

  Note	Only one StartupClass object can be deployed to an Application Server instance.

  ---

  
  

The following sections describe how to create and use a startup class:

• The IStartupClass Interface

• Building the Startup Class

• Deploying the Startup Class

• How kjs Handles the StartupClass Object

The IStartupClass Interface

The StartupClass class must implement the IStartupClass interface. The IStartupClass interface defines two methods:

• public void startUp() throws StartupClassException

  This method is called to perform activities when kjs starts up (kjs calls the StartupClass default constructor, which calls this method). This method may perform any action. It is invoked after the kjs engine establishes all the relevant contexts, so it can access EJB and JDBC resources.

  If an exception occurs, this method throws a com.iplanet.ias.startup.StartupClassException.

• public void shutDown()

  This method should deallocate any resources allocated during startup.

A com.iplanet.ias.startup.StartupClassException is thrown if the startUp method fails. Its signature is as follows:

public class StartupClassException extends java.lang.Exception

Its one constructor is as follows:

public StartupClassException(java.lang.String msg)

Building the Startup Class

Building the class is supported through Ant (although using Ant is not required). Building the StartupClass file and any dependent java files in the install_dir/startup directory is recommended, because the files necessary for building it are there. Make sure you have done these things first:

• Include install_dir/bin in the Shell's PATH environment variable.

• Include the path to the JDK in the Shell's PATH environment variable.

• If you are not building the StartupClass file in the install_dir/startup directory, copy the StartupClass.java, startup.properties, and build.xml files from that directory into the build directory you are using.

The following are the build options:

build compile	Compiles all the java files in the install_dir/startup directory and places the class files under the classes subdirectory.
build jar	Runs build compile, then jars the class files into the startup.jar file and places this file under the classes subdirectory.
build clean_jar	Removes the startup.jar file.
build clean	Removes the classes subdirectory and its subdirectories.
build deploy	Deploys the startup.jar file to install_dir/STARTUPCLASS.
build	The default build, which runs build clean, build compile, build jar, and build deploy in that order.

---

Note	The name of the .jar file must be startup.jar.

---

Deploying the Startup Class

Deployment is supported through the iasdeploy tool. There are two kinds of deployment:

• Local deployment

  iasdeploy deploystartup path/startup.jar

  For example:

  iasdeploy deploystartup /iasroot/ias/startup/classes/startup.jar

• Remote deployment

  iasdeploy deploystartup -host server -port port -user userName -password password path/startup.jar

  For example:

  iasdeploy deploystartup -host myserver -port 80 -user jjones -password secret /iasroot/ias/startup/classes/startup.jar

The path can be the following:

• The relative path to the startup.jar file from the directory in which iasdeploy is run

• The absolute path, for example install_dir/startup/classes

Concurrent deployment on multiple machines is not supported by the iasdeploy tool.

The startup.jar file is deployed to the install_dir/STARTUPCLASS directory.

---

Note	If the startup class is deployed to a directory other than install_dir/STARTUPCLASS, an informational message is generated in the kjs log when the application server starts up.

---

---

Note	The Deployment Tool does not provide support for assembling startup class modules.

---

How kjs Handles the StartupClass Object

For each kjs process that runs in its own JVM, there is one instance of the StartupClass object.

Inside the run method of com.kivasoft.engine.Engine.java, the StartupClass object is created by the system class loader after the environment is set up, but before any other method is performed. The startUp method is performed when the StartupClass object is created.

If the startUp method executes successfully, kjs runs until it shuts down normally. At graceful shutdown (with iascontrol stop), kjs calls the shutDown method of the StartupClass object.

If the startUp method throws a com.iplanet.ias.StartupClassException, kjs calls the shutDown method, and the StartupClass object is immediately garbage collected. Then kjs exits.

---

Note	Since each kjs process has its own copy of the StartupClass object, you should design a startup class with caution. It is recommended that you take care of synchronization issues for shared resources.

---