Oracle9iAS Portal Developer Kit (PDK)
Implementing Expiry-based 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 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.

Assumptions

• You have already installed the Caching Example downloaded from the PDK and understand the steps required to display a PL/SQL portlet on an Oracle Portal page.
• You have read the A Primer on Caching document for an introduction to caching.
• You have read the 'How to build a PL/SQL portlet' document and understand how you can build your own portlet using the sample source code as a template.

How to use Caching

Before you can start using Caching, it must be enabled in your Portal installation. The section on 'How to Enable Caching' in the Primer on Caching document explains how this setup can be done.

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

Implementing Expiry-based Caching

1. From the downloaded Caching Example, review the expirycache_portlet.pkb file which is the package body for this portlet. An excerpt is provided below.
2. The Caching Level constants are provided aliases at the start. This code segment is highlighted below.
3. Scroll the file to the section that contains the procedure get_portlet_info. Observe that the portlet sets the values for this particular portlet, like its name, title, description etc. You would do this any time you create a new portlet. The article 'How to Build a PL/SQL Portlet' describes in detail, what you need to do when you use existing portlet source code to modify it to create your own portlet.

   CREATE OR REPLACE package body EXPIRYCACHE_PORTLET is -- Caching Constants -- CACHE_LEVEL_SYSTEM constant varchar2(10) := 'SYSTEM'; CACHE_LEVEL_USER constant varchar2(10) := 'USER'; function get_portlet_info ( p_provider_id in integer ,p_language in varchar2 ) return wwpro_api_provider.portlet_record is l_portlet wwpro_api_provider.portlet_record; begin l_portlet.id := cache_provider.PORTLET_EXPIRYCACHE; l_portlet.provider_id := p_provider_id; l_portlet.title := 'Expiry Based Caching'; l_portlet.name := 'Expiry_Cache'; l_portlet_descriptin := 'This portlet illustrates expiry based caching'; ... end EXPIRYCACHE_PORTLET; /

4. Scroll to the show procedure. Here the p_portlet_record, the IN parameter to the procedure has been changed to an IN OUT parameter, since here we also modify the portlet_runtime_record field values. A corresponding change needs to be made in the package specification for the procedure definition.
5. Additionally the portlet checks for security access to portlet, and if it is not available, it resets the caching fields to null values.
6. Set the value of the caching period in minutes in a temporary variable. In this case we set it to one minute.

   CREATE OR REPLACE package body EXPIRYCACHE_PORTLET is ... procedure show ( p_portlet_record in out wwpro_api_provider.portlet_runtime_record ) is l_portlet wwpro_api_provider.portlet_record; begin -- Perform the Security Check if not is_runnable(p_provider_id, null) then -- Set it to null so that cache does not get used even if exists p_portlet_record.caching_level := null; p_portlet_record.caching_period := null; raise wwpro_api_provider.PROVIDER_SECURITY_EXCEPTION; end if; -- Set the Caching Period to one minute l_cache_period := 1; ... end show; end EXPIRYCACHE_PORTLET; /

7. After setting your cache period to a temporary value, check your portlet_runtime_record parameter for its current values of the caching_level, and set your caching_period values accordingly. You can use this same piece of code for setting your caching_period values.

   CREATE OR REPLACE package body EXPIRYCACHE_PORTLET is ... procedure show ( p_portlet_record in out wwpro_api_provider.portlet_runtime_record ) ... -- Set the Caching Period to one minute l_cache_period := 1; -- SYSTEM CACHE is nothing but an empty portlet. The user has done -- nothing yet! if p_portlet_record.caching_level = CACHE_LEVEL_SYSTEM then -- Cache does not exist for the user, create it p_portlet_record.caching_level := CACHE_LEVEL_USER; p_portlet_record.caching_period := l_cache_period; elsif p_portlet_record.caching_level = CACHE_LEVEL_USER then -- Cache exists for the user, overwrite it p_portlet_record.caching_period := l_cache_period; elsif p_portlet_record.caching_level is null then if p_portlet_record.caching_period is not null then -- Cache does not exist for the user, create it p_portlet_record.caching_level := CACHE_LEVEL_USER; p_portlet_record.caching_period := l_cache_period; else -- Define a system cache. This can happen only once! -- the first time the portlet is rendered. p_portlet_record.caching_level := CACHE_LEVEL_SYSTEM; p_portlet_record.caching_period := l_cache_period; end if; else -- p_portlet_record.caching_level value is messed up! p_portlet_record.caching_level := CACHE_LEVEL_SYSTEM; p_portlet_record.caching_period := l_cache_period; end if; if (p_portlet_record.exec_mode = wwpro_api_provider.MODE_SHOW) then ... end show; ... end EXPIRYCACHE_PORTLET; /

8. This way by setting your cache period before rendering the portlet, you can enable Expiry based Caching for your portlets.

View Portlet functionality

1. Create a page and add the Expiry based Caching portlet to your page. Take note to view the change in the time displayed every time you reload the page. You will find that the if you reload within the one minute, the portlet still displays the old time. Only if you refresh the page after one minute, the time displayed is changed.
2. Additionally add the Validation based Caching portlet to the same page and compare how the caching on the two portlets works differently.