Web Caching Samples

iPlanet^TM Application Server Samples

If you have already configured the web caching sample, then you can run the application by clicking here.

iPlanet Application Server provides value-added services that enable results caching at both the JSP and Servlet level. Using results caching enables you to increase server performance by allowing subsequent calls to JSPs and Servlets to be returned using cached results instead of reinvoking Java code to generate the resulting content from scratch.

The servlet caching sample demonstrates how servlet caching can be controlled using deployment descriptors. Several unique deployment descriptor samples are provided that demonstrate how cache sizes, timeouts, and parameters can be adjusted at deployment time without any coding changes.

The JSP caching sample shows how JSP caching can be enabled by utilizing custom JSP tags. There are two primary methods within iPlanet Application Server of determining whether to refresh a JSP cache. A sample JSP is provided for each of these methods.

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 Web Caching application in iPlanet using a Command Line Interface (CLI). This is the fastest means of deploying the sample to the application server.

GUI-based Deployment describes how to use the iPlanet Deployment Tool to import and deploy the sample application.

Exercise Servlet Result Caching describes how to run the servlet result caching samples.

Exercise JSP Result Caching describes how to run the JSP result caching samples.

Known Issues describes the known problems at this time

Command Line-based Deployment

Servlet caching is controlled via deployment descriptors. Specifically, there is an optional <caching> XML element (with several sub-elements) as part of each <servlet-info> element in the ias-web.xml file. These elements are described in detail in the iPlanet Application Server Developer's Guide.

Thus, the caching characteristics of the application can be changed simply by editing the ias-web.xml file and modifying the <caching> element of the ServCache servlet.

Alternatively, there are several sample caching descriptors available in the src/alt_deploy directory. These descriptors can be used by replacing the ias-web.xml file with one of the alternate descriptor files.

If you intend to use one of the alternate servlet caching descriptor the the EAR file must be rebuilt using the new ias-web.xml file and redeployed. Refer to the section Modifying Servlet Result Caching Characteristics. If you want to start exercising the samples using the default caching characteristics, then proceed with the following section to deploy the prebuilt EAR file.

Deploying Prebuilt EAR File (default caching characteristics)

Deploying the prebuilt caching.ear file is simple.

1. Go to the root of the Web Caching ample directory:

installdir/ias/ias-samples/caching/

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

iasdeploy deployapp caching.ear

In order to use iasdeploy, you must register an instance of the application server in the iPlanet Application Server's administrative console. Refer to the Getting Started section for more information on using the iasdeploy command.

Once deployment completes, you are ready to Exercise Servlet Result Caching.

Modifying Servlet Result Caching Characteristics

Given a set of prebuilt ias-web.xml files in the src/alt_deploy/ directory, you can change the servlet result caching characteristics of the sample by simply copying over the ias-web.xml file with one of the following files:

<caching>

  <cache-timeout>1800</cache-timeout>

  <cache-size>4</cache-size>

  <cache-criteria>inputtext</cache-criteria>

  <cache-option>TIMEOUT_CREATE</cache-option>

</caching>

 <Caching>

   <cache-timeout>900</cache-timeout>

   <cache-size>64</cache-size>

   <cache-criteria>inputtext</cache-criteria>

   <cache-option>TIMEOUT_CREATE</cache-option>

 </caching> 

<Caching>

  <cache-timeout>60</cache-timeout>

  <cache-size>8</cache-size>

  <cache-criteria>inputtext=one|two|three</cache-criteria>

  <cache-option>TIMEOUT_LASTACCESS</cache-option>

</caching>

To change the settings, simply:

1. Copy the desired deployment descriptor to the current directory. For example,

[UNIX]

cd installdir/ias/ias-samples/caching/src
cp alt_deploy/cachesize.xml ./ias-web.xml

[Windows]

cd installdir\ias\ias-samples\caching\src
copy alt_deploy\cachesize.xml .\ias-web.xml

2. Build the EAR file:

build core

If you built the EAR file previously, then you can simply reassemble it without recompiling by executing:

build ear

3. Deploy the new EAR file and restart the server.

build deploy

Once deployment completes, you are ready to Exercise Servlet Result Caching.

GUI-based Deployment

To change the caching characteristics of the web caching sample application follow these steps:

1. In the startup dialog, select Browse for more applications.
2. Alternatively, if Deployment Tool is already started, select File -> Open.
3. Navigate to the installdir\ias\ias-samples\caching\assemble\ear\ directory and select caching.ear.
4. If you desire to modify the default caching characteristics of the ServCache servlet, follow these steps:
   1. Select the Component View tab in the left pane.
   2. Open the caching folder.
   3. Open the Web Caching Sample folder.
   4. Right click the ServCache icon and select Edit Descriptor from the pop-up menu.
   5. Select the iAS tab in the Servlet Descriptor pane.
   6. Modify the Cache timeout,Cache size, Caching criterion, and Cache timeout begins at values to the desired settings.
   7. Select File -> Save
5. Select the caching folder and select File -> Deploy
6. If you have not already registered the target application servers, do so now by clicking on the Register button. Enter the host name, administrative port number and username/password for each target application server.
7. Click on Deploy to start the deployment process.

Once the deployment completes, you are ready to exercise the sample application.

Exercise Servlet Result Caching

Servlet result caching is performed by each Executive Server (kxs process) within an application server instance. Consequently, a separate cache is maintained per application server instance. Since the kxs process is located in front of the Java Engines (KJS processes - JVMs), as requests for the servlet arrive at an application server instance, the KXS determines whether or not the servlet result cache content should be returned by the kxs or the request should be forwarded to a KJS for processing.

To ensure that the servlet sample provide repeatable and predictable results even in a multi-server clustered environment, the sticky flag has been set in the ias-web.xml deployment descriptors. Sticky has been enabled to aid tracing of the execution flow and so that the same caches will be utilized for each request. More information on servlet result caching can be found in the iPlanet Application Server Developer's Guide.

Exercising Using Default Caching Parameters

• Timeout = 900 seconds
• Cache Size = 64KB
• Criteria = inputtext
• Timeout option = TIMEOUT_CREATE

The default caching criteria makes it easy to verify that servlet caching is working. Take the following steps to verify that caching is working correctly:

1. Go to the http://<web server hostname>:<port>/NASApp/caching/index.html
2. Enter an input string of "one", select delivery mechanism of "servlet only", and then submit the form by clicking "execute servlet".
3. Observe the generated output and make a note of the time the content was created.
4. Return to the start page using the link at the bottom of the page.
5. Enter an input string of "one", select delivery mechanism of "servlet only", then submit the form by clicking "execute servlet". (The same as the previous step.)
6. Observe that that the timestamp did not change. This indicates that the page is being returned from the cache as maintained by the KXS process, and not by executing the servlet's Java code. This can also be verified by looking at the KJS log. The KJS should only show one log message indicating that one request was passed on to the KJS. You may also be able to see "entry found" and "entry expired" messages in the KXS log (depending on the level of log verbosity you have enabled) for each request serviced.
7. Return to the start page and enter an input string of "one", a delivery mechanism of "Via JSP", and then submit the page.
8. Observe that the returned content still says "println statements within a Servlet". This is because inputtext is the only caching criteria. The cached results will be returned as long as the criteria are met, even if additional differing parameters are specified.
9. Return to the start page and enter an input string of "two", a delivery mechanism of "Via JSP", and then submit the page.
10. Observe that the returned page now indicates the "two" input parameter and the JSP delivery mechanism.
11. Make another request with an input string of "two" (any delivery mechanism). Note that the result was returned from the cache. This demonstrates that the servlet result cache is effective regardless of the mechanism used to generate the page content. The servlet result cache will cache the HTML results regardless of how many backend datasources, EJBs, and JSPs are utilized to generate the output.
12. Wait until at least ten minutes after you made the original "one" request. Then submit another request with the input string of "one".
13. Observe that the servlet executed again (showing a new timestamp), since the original cached entry had expired.

Testing Using cachesize.xml

• Timeout = 30 minutes
• Cache Size = 4KB
• Criteria = inputtext
• Timeout option = creation time

The cachesize.xml caching configuration demonstrates how the cache size parameter can be used to limit the maximum size of the servlet cache. An extremely small cache size is specified so that the maximum cache size can be easily exceeded. This sample assumes that you already have practiced with the default caching parameters and understand the basics of the servlet caching sample.

1. Change the caching parameters by redeploying with a modified ias-web.xml descriptor as described above.
2. Go to the http://<web server hostname>:<port>/NASApp/caching/index.html
3. Make a request using the inputstring of "one" and any delivery mechanism. Make a note of the timestamp and repeat the request a few times to make sure that the results are being returned from the cache.
4. Make a request using a different input string.
5. Make another request with the input string of "one". Use the timestamp to determine if the results are being generated from the servlet or returned from the cache.
6. Repeat the previous two steps making note of how many servlet results can be cached before the cache size is exceeded and the "one" cache has to be rebuilt. (Assuming your input string is small, the cache should store about four different results.)

Testing Using selective.xml

• Timeout = 1 minute
• Cache Size = 8KB
• Criteria = inputtext=one|two|three
• Timeout option = last accessed

The selective.xml demonstrates both selective caching criterion and the last accessed timeout option. Specifically, the caching criteria are modified so that only a few input parameters are eligible for caching. This sample assumes that you already have practiced with the default caching parameters and understand the basics of the servlet result caching sample.

1. Change the caching parameters by redeploying with a modified ias-web.xml descriptor as described above.
2. Go to the http://<web server hostname>:<port>/NASApp/caching/index.html
3. Make a request using the inputstring of "one" and any delivery mechanism. Make a note of the timestamp and repeat the request a few times to make sure that the results are being returned from the cache.
4. Keep making requests with the inputstring of "one" every few seconds. Note that the results continue to be return from the cache, even after the cache has passed its expiration time (60 seconds). This is because of the "last accessed" option. The cache will not expire until after the servlet has been unused for the amount of time specified.
5. Make a request using the inputstring of "five" and any delivery mechanism. Make a note of the timestamp and repeat the request a few times. Note that the results are being generated each time and not returned from the cache. This is because "five" was not specified as one of the cacheable parameters for inputtext in the caching criteria. Only requests with the values of "one", "two", and "three" will be cached.

Exercising JSP Result Caching

Unlike servlet caching, JSP caching is managed on a per Java Engine or KJS basis. This means that one cache is maintained by each executing JVM. Be aware of this fact when your user's requests are load balanced across multiple JVMs. More information on JSP caching can be found in the iPlanet Application Server Developer's Guide.

There are two methods for specifying the cache criteria. The first method is by calling out from the JSP (using a custom tag) to a Java class. The Java class then makes a decision about whether the results should be returned from the JSP cache based on the parameters passed to it (the ServletRequest and Servlet). This is the cache criteria method used by the JSPCache.jsp sample. To exercise the JSPCache.jsp sample follow these steps:

1. Go to the http://<web server hostname>:<port>/NASApp/caching/index.html.
2. Press the "execute JSP test (check class)" button, which will make a request to the JSPCache.jsp.
3. The JSP will return a simple HTML page that contains a timestamp. Make a note of the timestamp.
4. Examine the KJS log. The last line of the KJS log should be "JSP not cached". This is the result of System.out.println statement with the JSP to let you know that the JSP executed (and was therefore not returned from the cache). Now that we have executed the JSP, the results should be stored in the cache stored in the KJS cache.
5. Press the reload button on your browser. You will notice that the timestamp on the page does not change. This indicates that the page has been returned from the JSP cache instead of executing again.
6. Examine the KJS log again. You will notice that that instead of instead of the "JSP not cached" message, there are now two debugging lines printed by the CachableChecker class. The first line is a message from the CachableChecker indicating that is allowing the JSP cache to return the cache results. The second line is the value of the inputtext parameter, which should be "iplanet". This is to demonstrate that the checker class has access to the HttpRequest.
7. If desired, experiment further by modifying the inputtext parameter in the URL or by making modifications to the CachableChecker class.

The second method of specifying cache criteria is via the ias:param custom JSP tag. In this approach the JSP cache engine will make the determination to return a cached result based on the parameter specified in that tag. This is the method used by the JSPCache2.jsp sample. To exercise the JSPCache2.jsp sample follow these steps:

1. Go to the http://<web server hostname>:<port>/NASApp/caching/index.html
2. Press the "execute JSP test (param tag provided)" button, which will make a request to the JSPCache2.jsp.
3. The JSP will return a simple HTML page that contains a timestamp. Make a note of the timestamp.
4. Press the reload button on your browser. You will notice that the timestamp does not change. Inspecting the KJS log (as you did for JSPCache.jsp) will also reveal that the JSP was only executed once.
5. Return to the application start page using the provided link.
6. Press the "execute JSP test (param tag not provided)" button. This will call the JSPCache2.jsp page again, but this time without the "usecache" parameter that is specified in the ias:param tag.
7. Make a note of the new timestamp.
8. Press the reload button a few times. Note that the timestamp changes each time. The JSP is not using the cache because the ias:param tag cache criterion has not been met.
9. Experiment further by trying some of the other ias:param options specified in the iPlanet Application Server Developer's Guide.

Copyright (c) 2001 Sun Microsystems, Inc.