Chapter 13   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 12 "Writing Secure Applications," are based on emerging Sun Microsystems standards and conforms to these future standards.

This chapter contains the following sections:

• Accessing the Servlet Engine

• Caching Servlet Results

• Using a Startup Class

Accessing the Servlet Engine

---

The servlet engine controls all servlet functions, including instantiation, destruction, service methods, request and response object management, and input and output. The servlet engine in the iPlanet Application Server is a special class called an AppLogic. AppLogics are iPlanet Application Server components that interact with the core server. In previous iPlanet Application Server releases, AppLogics were part of the application model, though for current and future releases they are solely available to access the iPlanet Application Server internal features.

Each servlet is scoped in an AppLogic. You can access an AppLogic instance controlling a servlet using the getAppLogic() method in the iPlanet Application Server feature interface HttpServletRequest2. When you do this, you also gain access to the server context. These activities are necessary to take advantage of other iPlanet Application Server features, as described in the following sections.

Accessing the Servlet's AppLogic

To access the controlling AppLogic, cast the request object as an HttpServletRequest2. This interface provides access to the AppLogic through the getAppLogic method, which returns a handle to the superclass.

The following example servlet header shows how to access an AppLogic instance:

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import com.kivasoft.applogic.*;
import com.kivasoft.types.*;
import com.netscape.server.servlet.extension.*;

public class AppLogicTest extends HttpServlet {

   public void service(HttpServletRequest req,
                     HttpServletResponse res)
      throws ServletException, IOException
   {
      HttpServletRequest2 req2 = (HttpServletRequest2)req;
      AppLogic al = req2.getAppLogic();
      //al is now a handle to the superclass
...

Accessing the Server Context

Some iPlanet Application Server features require an IContext object. IContext defines a server context view. For more information, see the IContext interface section in the Foundation Class Reference (Java).

To obtain an IContext from a servlet, the standard servlet context can be cast to IServerContext and from there, a com.kivasoft.IContext instance can be obtained, as shown in the following example:

ServletContext ctx = getServletContext();
com.netscape.server.IServerContext sc;
sc = (com.netscape.server.IServerContext) ctx;
com.kivasoft.IContext kivaContext = sc.getContext();

Alternatively, you can access the underlying AppLogic instance from a servlet, as described in "Accessing the Servlet's AppLogic," and obtain the context from the AppLogic's context member variable, as shown in the following example:

HttpServletRequest2 req2 = (HttpServletRequest2)req;
AppLogic al = req2.getAppLogic();
com.kivasoft.IContext kivaContext = al.context;

From an EJB, the standard javax.ejb.SessionContext or javax.ejb.EntityContext can be cast to IServerContext and from there, a com.kivasoft.IContext instance can be obtained, as shown in the following example:

javax.ejb.SessionContext m_ctx;
....
com.netscape.server.IServerContext sc;
sc = (com.netscape.server.IServerContext) m_ctx; /
com.kivasoft.IContext kivaContext;
kivaContext = sc.getContext();

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 13-1 shows the caching settings in a servlet configuration file.

Table 13-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 13-2 shows the cache-criteria field syntax.

Table 13-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.

---