Oracle9iAS Portal Developer Kit (PDK)
An overview of Caching in PL/SQL portlets

Introduction

Oracle9iAS Portal provides functionality for caching of PL/SQL portlets. This functionality permits PL/SQL portlets to have their Web content cached by the middle tier. Subsequent requests for the content may be retrieved from the cache, with or without validation from the database, decreasing the database workload.

Oracle9iAS Portal provides two ways to enable caching in your PL/SQL portlets. You can either choose to use Validation based caching or Expiry based caching. The first method compares a key value to check whether the cache is still valid. If the key value doesn't change, it uses the cached content otherwise it makes a round trip to the Portal node to fetch the portlet content. The second method uses a given expiration period to use the cache for rendering the portlet.

Key Features

When a database provider issues a request for a portlet, the request is sent to the portlets’s show procedure. This procedure accepts the portlet_runtime_record as a parameter. This record structure contains fields that can be examined and set by the portlet to enable caching. Three fields of this record that are used for caching control are the following:

• caching_key: This is the value that gets communicated in the ETAG header for this request and returned back to the portlet provider in subsequent requests. Setting of this field enables Validation based caching.
• caching_period: This is to enable Expiry based caching. The value mentioned here is number of minutes the content should be cached. This mode overrides Validation based caching, if this value is present then the caching_key is ignored.
• caching_level: This defines whether the content is meant for general consumption or for a specific user. The valid values are 'SYSTEM' or 'USER'.

How to enable Caching

The general setup for enabling Caching can be described as follows:

1. Ask your Portal Administrator to enable Caching in the Gateway. You can do this if you have the privileges by access your Gateway Configuration Menu through http://host:port/pls/admin_/gateway.htm. Click on Cache Settings.
2. Under the PL/SQL Cache Settings, check the General Settings. Ensure that Enable PL/SQL Caching is set to 'Yes' and the Cache Direcrtory is a valid directory on the host where the Listener has read and write permissions. For example, you can give the complete path for a directory under your <Apache ORACLE_HOME>/Apache/modplsql/cache. Remember to create this directory if it does not exist.
3. Under the size settings and cleanup settings, give appropriate values based on the Portal installation guide. We have provided screenshots of examples below.
4. Similarly check values under the Session Cookie Cache Settings.

How to use Caching

The general model for using Caching can be described as follows:

1. Choose between using Validation based caching or Expiration based caching for your portlets. For this purpose review your portlet functionality. Check to see whether it makes more sense to use the cache for a given period of time always, which might be the case if you know that the portlet usually doesn't change for a given period. Otherwise choose to use Validation based caching when you can generate a key that can be used to check whether the content is now changed.
2. If you plan to use Expiry based caching, you can set the caching_period field of the portlet_runtime_record parameter that the show procedure of the portlet receives. It is very simple to enable Expiry based caching.
3. If you plan to use Validation based caching, you can use the caching_key field of the portlet_runtime_record parameter that the show procedure of the portlet receives. Add a check to compare the value of the current caching key with the value of the caching_key field of the portlet_runtime_record parameter. The first time, this show method is called, the key will be null and its value will have to be set.
4. Check to see whether you want to use System level caching or User level caching. Set your caching_level field of the portlet_runtime_record parameter accordingly.