3
Caching

Caching can improve performance of your PL/SQL Web applications. You can cache Web content generated by PL/SQL procedures in the middle-tier and decrease the database workload.

3.1 The PL/SQL Gateway Cache

Refer to the Caching Overview diagram above during the discussion of caching. It illustrates the different techniques used in caching. For example:

• Validation Technique - An application asks the server if the page has been modified since it was last presented.

• Expires Technique - Based upon a specific time period the PL/SQL application determines if the page will be cached or should be generated again.

• System or User-level Caching - Valid whether you are using the Validation Technique or the Expires Technique. The level of caching is determined by whether a page is cached for a particular user or for every user in the system.

These techniques and levels are implemented using owa_cache packages located inside the PL/SQL Web Toolkit, represented in the diagram by the toolkit in the database.

3.2 Validation Technique

In general, the validation technique basically asks the server if the page has been modified since it was last presented. If it has not been modified, the cached page will be presented to the user. If the page has been modified, a new copy will be retrieved, presented to the user and then cached.

There are two methods which use the Validation Technique, Last-Modified method and the Entity Tag method. The next two sections show how these techniques are used in the HTTP protocol. Although the PL/SQL Gateway does not use the HTTP protocol, many of the same are principles are used.

3.2.1 Last-Modified

Using the HTTP protocol, when a Web page is generated, it contains a Last-Modified Response Header. This header indicates the date (relative to the server) of the content that was requested. Browsers save this date information along with the content. When subsequent requests are made for the URL of the Web page, the browser:

1. Determines if it has a cached version.

2. Extracts the date information.

3. Generates the Request Header If-Modified-Since.

4. Sends the request the server.

Cache-enabled servers look for the If-Modified-Since header and compare it to their content's date. If the two match, an HTTP Response status header such as "HTTP/1.1 304 Not Modified" is generated, and no content is streamed. Upon receipt of this status code, the browser can reuse its cache entry because it has been validated.

If the two don't match, an HTTP Response header such as "HTTP/1.1 200 OK" is generated and the new content is streamed, along with a new Last-Modified Response header. Upon receipt of this status code, the browser must replace its cache entry with the new content and new date information.

3.2.2 Entity Tag Method

Another validation method provided by the HTTP protocol is the ETag (Entity Tag) Response and Request header. The value of this header is a string that is opaque to the browser. Servers generate this string based on their type of application. This is a more generic validation method than the If-Modified-Since header, which can only contain a date value.

The ETag method works very similar to the Last Modified method. Servers generate the ETag as part of the Response Header. The browser stores this opaque header value along with the content that is steamed back. When the next request for this content arrives, the browser passes the If-Match header with the opaque value that it stored to the server. Because the server generated this opaque value, it is able to determine what to send back to the browser. The rest is exactly like the Last-Modified validation method as described above.

3.2.3 Using the Validation Technique for PL/SQL Gateway

Using HTTP validation caching as a framework, the following is the Validation Model for the PL/SQL Gateway.

PL/SQL applications that want to control the content being served should use this type of caching. This technique offers some moderate performance gains. One example of this would be an application that serves dynamic content that can change at any given time. In this case, the application needs full control over what is being served. Validation caching always asks the application whether the cached content is stale or not before serving it back to the browser.

1. The Oracle HTTP Server receives a PL/SQL procedure request from a client server. The Oracle HTTP Server routes the request to the PL/SQL Gateway.

2. PL/SQL Gateway prepares the request.

3. PL/SQL Gateway invokes the PL/SQL procedure in the application. The PL/SQL Gateway passes the usual Common Gateway Interface (CGI) environment variables to the application.

4. The PL/SQL procedure generates content to pass back. If the PL/SQL procedure decides that the generated content is cacheable, it calls the
   owa_cache procedure from the PL/SQL Web Toolkit to set the tag and cache level:

   owa_cache.set_cache(p_etag, p_level);

   Table 3-1 Validation Model Parameters

   Parameter	Description
   set_cache procedure	Sets up the headers to notify mod_plsql that the content being streamed back can be cached. Then, the mod_plsql caches the content on the local file system along with the tag and caching level information as it is streamed back to the browser.
   p_etag	The string that the procedure generates to tag the content.
   p_level	The caching level ("SYSTEM" for system level or "USER" for user level).

5. The HTML is returned to the PL/SQL Gateway.

6. The PL/SQL Gateway stores the cacheable content in its file system for the next request.

7. The Oracle HTTP Server sends the response to the client browser.

3.2.4 Second Request using the Validation Technique

Using the same validation model explained above, a second request is made by the client browser for the same PL/SQL procedure.

1. PL/SQL Gateway detects that it has a cached content for the request.

2. The PL/SQL Gateway forwards the same tag and caching level information (from the first request) to the PL/SQL procedure as part of the CGI environment variables.

3. The PL/SQL procedure uses these caching CGI environment variables to check if the content has changed. It does so by calling the following owa_cache functions from the PL/SQL Web Toolkit:

   owa_cache.get_etag;

   owa_cache.get_level;

   These owa functions get the tag and caching level.

4. The application sends the caching information to the PL/SQL Gateway.

5. Based on that information determines whether the content needs to be regenerated or can be served from the cache.
   1. If the content is still the same, the procedure calls the owa_cache.set_not_modified procedure and generates no content. This PL/SQL Gateway to use its cached content. The cached content is directly streamed back to the browser.

   2. If the content has changed, it generates the new content along with a new tag and caching level. PL/SQL Gateway replaces its stale cached copy with a new one and updates the tag and caching level information. The newly generated content is streamed back to the browser.

3.3 Using the Expires Technique

In the validation model, the PL/SQL Gateway always asks the PL/SQL procedure if it can serve the content from the cache. In the expires model, the procedure preestablishes the content validity period. Therefore, the PL/SQL Gateway can serve the content from its cache without asking the procedure. This further improves performance because no interaction with the database is required.

This caching technique offers the best performance. Use if your PL/SQL application is not sensitive to serving stale content. One example of this is an application that generates news daily. The news can be set to be valid for 24 hours. Within the 24 hours, the cached content is served back without contacting the application. This is essentially the same as serving a file. After 24 hours, the PL/SQL Gateway will again fetch new content from the application.

Assume the same scenario described above for the Validation model, except the procedure uses the Expires model for caching.

1. The Oracle HTTP Server receives a PL/SQL Server Page request from a client server. The Oracle HTTP Server routes the request to the PL/SQL Gateway.

2. The request is forwarded by PL/SQL Gateway to the Oracle Database.

3. The PL/SQL Gateway invokes the PL/SQL procedure in the application and passes the usual Common Gateway Interface (CGI) environment variables to the application.

4. The PL/SQL procedure generates content to pass back. If the PL/SQL procedure decides that the generated content is cacheable, it calls the
   owa_cache procedure from the PL/SQL Web Toolkit to set the validity period and cache level:

   owa_cache.set_expires(p_expires, p_level);

   Table 3-2 Expires Model Parameters

   Parameter	Description
   set_expires procedure	Sets up the headers to notify mod_plsql that Expires caching is being used. Mod_plsql then caches the content to the file system along with the validity period and caching level information.
   p_expires	Number of minutes that the content is valid.
   p_level	Caching level.

5. The HTML is returned to the PL/SQL Gateway.

6. The PL/SQL Gateway stores the cacheable content in its file system for the next request.

7. The Oracle HTTP Server send s the response to the client browser.

3.3.1 Second Request using the Expires Technique

Using the same expires model explained above, a second request is made by the client browser for the same PL/SQL procedure.

1. The PL/SQL Gateway detects that it has a cached copy of the content that is expires-based.

2. The PL/SQL Gateway checks the content's validity by taking the difference between the current time and the time this cache file was created.
   1. If this difference is within the validity period, the cached copy is still fresh and will be used without any database interaction. The cached content is directly streamed back to the browser.

   2. If the difference is not within the validity period, the cached copy is stale. The PL/SQL Gateway invokes the PL/SQL procedure and generates new content. The procedure then decides whether to use expires-based caching again. If so, it also determines the validating period for this new content. The newly generated content is streamed back to the browser.

3.4 System- and User-level Caching

A PL/SQL procedure determines whether generated content is system-level content or user-level. This helps the PL/SQL Gateway cache to store less redundant files if more than one user is looking at the same content. It decides this by:

• For system-level content, the procedure passes the string "SYSTEM" as the caching level parameter to the owa_cache functions (set_cache for validation model or set_expires for expires model). This is for every user that shares the cache.
  By using system-level caching, you can save both space in your file system and time for all users in the system. One example of this would be an application that generates content that is intended for everybody using the application. By caching the content with the system-level setting, only one copy of the content is cached in the file system. Furthermore, every user on that system benefits since the content is served directory from the cache.

• For user-level content, it passes the string "USER" as the parameter for the caching level. This is for a specific user that is logged in. The stored cache is unique for that user. Only that user can use the cache.The type of user is determined by the authentication mode. Refer to the table below for the different types of users. For more information, refer to "Securing applications through the PL/SQL Gateway".

  Table 3-3 Type of user determined by Authentication Mode

  Authentication Mode	Type of User
  Single Sign On (SSO)	Lightweight user
  Basic	Database user
  Custom	Remote user

For example, if no user customizes a PL/SQL Web application, then the output can be stored in a system-level cache. There will be only one cache copy for every user on the system. User information is not used since the cache can be used by multiple users.

However, if a user customizes the application, a user-level cache is stored for that user only. All other users still use the system level cache. For a user-level cache hit, the user information is a criteria. A user-level cache always overrides a system-level cache.

3.4.1 PL/SQL Web Toolkit functions (owa_cache package)

Your decision whether to use the Validation technique or the Expires technique determines which owa_cache functions to call.

The owa_cache package contains procedures to set and get special caching headers and environment variables. These allow developers to use the PL/SQL Gateway cache more easily. This package should already be installed in your database.

These are the primary functions to call:

Table 3-4 Primary owa_cache functions

owa Functions	Purpose
owa_cache.set_cache (p_etag IN varchar2, p_level IN varchar2)	Validation Model - Sets up the headers. p_etag parameter tags the generated content. p_level parameter is the caching level to use.
owa_cache.set_not_modified	Validation Model - Sets up the headers to notify mod_plsql to use the cached content. Only used when a validation -based cache hit occurs.
owa_cache.get_level	Validation Model - Gets the caching level, "USER" or "SYSTEM". Returns null if the cache is not hit.
owa_cache.get_etag	Validation Model - Gets the tag associated with the cached content. Returns null if the cache is not hit.
owa_cache.set_expires( p_expires IN number, p_level IN varchar2)	Expires Model - Sets up the headers. p_expires parameter is the number of minutes the content is valid. p_level parameter is the caching level to use.