Chapter 7 Dynamic Results Caching Functions

The functions described in this chapter allow you to write a results caching plug-in for Sun Java System Web Server. A results caching plug-in, which is a Service SAF, caches data, a page, or part of a page in the web server address space, which the Web Server can refresh periodically on demand. An Init SAF initializes the callback function that performs the refresh.

A results caching plug-in can generate a page for a request in three parts:

• A header, such as a page banner, which changes for every request

• A body, which changes less frequently

• A footer, which also changes for every request

  Without this feature, a plug-in would have to generate the whole page for every request (unless an IFRAME is used, where the header or footer is sent in the first response along with an IFRAME pointing to the body; in this case the browser must send another request for the IFRAME).

  If the body of a page has not changed, the plug-in needs to generate only the header and footer and to call the dr_net_write function (instead of net_write) with the following arguments:

• header

• footer

• handle to cache

• key to identify the cached object

  The web server constructs the whole page by fetching the body from the cache. If the cache has expired, it calls the refresh function and sends the refreshed page back to the client.

  An Init SAF that is visible to the plug-in creates the handle to the cache. The Init SAF must pass the following parameters to the dr_cache_init function:

• RefreshFunctionPointer

• FreeFunctionPointer

• KeyComparatorFunctionPtr

• RefreshInterval

  The RefreshInterval value must be a PRIntervalTime type. For more information, see the NSPR reference at:

  http://www.mozilla.org/projects/nspr/reference/html/index.html

  As an alternative, if the body is a file that is present in a directory within the web server system machine, the plug-in can generate the header and footer and call the fc_net_write function along with the file name.

  This chapter lists the most important functions a results caching plug-in can use. For more information, see the following file:

  install_dir/include/drnsapi.h

This chapter has the following sections:

• Functions

• dr_cache_init

• dr_cache_refresh

• dr_net_write

• fc_net_write

Functions

This section describes the dynamic result cache functions.

dr_cache_destroy

The dr_cache_destroy function destroys and frees resources associated with a previously created and used cache handle. This handle cannot be used in subsequent calls to any of the above functions unless another dr_cache_init is performed.

Syntax

void dr_cache_destroy(DrHdl *hdl);

Parameters

DrHdl *hdl is a pointer to a previously initialized handle to a cache (see dr_cache_init).

Returns

void

Example

dr_cache_destroy(&myHdl);

dr_cache_init

The dr_cache_init function creates a persistent handle to the cache, or NULL on failure. It is called by an Init SAF.

Syntax

PRInt32 dr_cache_init(DrHdl *hdl, RefreshFunc_t ref, FreeFunc_t fre, 
                      CompareFunc_t cmp, PRUint32 maxEntries, 
                      PRIntervalTime maxAge);

Returns

1 if successful.

0 if an error occurs.

Parameters

The following table describes parameters for the dr_cache_init function.

Table 7–1 dr_cache_init parameters

Parameter	Description
DrHdl hdl	Pointer to an unallocated handle.
RefreshFunc_t ref	pointer to a cache refresh function. This can be NULL; see the DR_CHECK flag and DR_EXPIR return value for dr_net_write.
FreeFunc_t fre	Pointer to a function that frees an entry.
CompareFunc_t cmp	Pointer to a key comparator function.
PRUint32 maxEntriesp	Maximum number of entries possible in the cache for a given hdl.
PRIntervalTime maxAgep	The maximum amount of time that an entry is valid. If 0, the cache never expires.

Example

if(!dr_cache_init(&hdl, (RefreshFunc_t)FnRefresh, (FreeFunc_t)FnFree, 
  (CompareFunc_t)FnCompare, 150000, PR_SecondsToInterval(7200)))
{
    ereport(LOG_FAILURE, "dr_cache_init() failed");
    return(REQ_ABORTED);
}

dr_cache_refresh

The dr_cache_refresh function provides a way to refresh a cache entry when the plug-in requires it. This can be achieved by passing NULL for the ref parameter in dr_cache_init and by passing DR_CHECK in a dr_net_write call. If DR_CHECK is passed to dr_net_write and it returns with DR_EXPIR, the plug-in should generate new content in the entry and call dr_cache_refresh with that entry before calling dr_net_write again to send the response.

The plug-in may simply decide to replace the cached entry even if it has not expired (based on some other business logic). The dr_cache_refresh function is useful in this case. This way the plug-in does the cache refresh management actively by itself.

Syntax

PRInt32 dr_cache_refresh(DrHdl hdl, const char *key, 
                        PRUint32 klen, PRIntervalTime timeout, 
                        Entry *entry, Request *rq, Session *sn);

Returns

1 if successful.

0 if an error occurs.

Parameters

The following table describes parameters for the dr_cache_refresh function.

Table 7–2 dr_cache_refresh parameters

Parameter	Description
DrHdl hdl	Persistent handle created by the dr_cache_init function.
const char *key	Key to cache, search, or refresh.
PRUint32 klen	Length of the key in bytes.
PRIntervalTime timeout	Expiration time of this entry; if a value of 0 is passed, the maxAge value passed to dr_cache_init is used.
Entry *entry	The not NULL entry to be cached.
Request *rq	Pointer to the request.
Session *sn	Pointer to the session.

Example

Entry entry;
char *key = "MOVIES"
GenNewMovieList(&entry.data, &entry.dataLen);  // Implemented by
                                               // plugin developer
if(!dr_cache_refresh(hdl, key, strlen(key), 0, &entry, rq, sn))
{
    ereport(LOG_FAILURE, "dr_cache_refresh() failed");
    return REQ_ABORTED;
}

dr_net_write

The dr_net_write function sends a response back to the requestor after constructing the full page with hdr, the content of the cached entry as the body (located using the key), and ftr. The hdr, ftr, or hdl can be NULL, but not all of them can be NULL. If hdl is NULL, no cache lookup is done; the caller must pass DR_NONE as the flag.

By default, this function refreshes the cache entry if it has expired by making a call to the ref function passed to dr_cache_init. If no cache entry is found with the specified key, this function adds a new cache entry by calling the ref function before sending out the response. However, if the DR_CHECK flag is passed in the flags parameter and if either the cache entry has expired or the cache entry corresponding to the key does not exist, dr_net_write does not send any data out. Instead, it returns with DR_EXPIR.

If ref (passed to dr_cache_init) is NULL, the DR_CHECK flag is not passed in the flags parameter, and the cache entry corresponding to the key has expired or does not exist, then dr_net_write fails with DR_ERROR. However, dr_net_write refreshes the cache if ref is not NULL and DR_CHECK is not passed.

If ref (passed to dr_cache_init) is NULL and the DR_CHECK flag is not passed but DR_IGNORE is passed and the entry is present in the cache, dr_net_write sends out the response even if the entry has expired. However, if the entry is not found, dr_net_write returns DR_ERROR.

If ref (passed to dr_cache_init) is not NULL and the DR_CHECK flag is not passed but DR_IGNORE is passed and the entry is present in the cache, dr_net_write sends out the response even if the entry has expired. However, if the entry is not found, dr_net_write calls the ref function and stores the new entry returned from ref before sending out the response.

Syntax

PRInt32 dr_net_write(DrHdl hdl, const char *key, PRUint32 klen, const char *hdr, 
                    const char *ftr, PRUint32 hlen, PRUint32 flen, 
                    PRIntervalTime timeout, PRUint32 flags, 
                    Request *rq, Session *sn);

Returns

IO_OKAY if successful.

IO_ERROR if an error occurs.

DR_ERROR if an error in cache handling occurs.

DR_EXPIR if the cache has expired.

Parameters

The following table describes parameters for the dr_net_write function.

Table 7–3 dr_net_write parameters

Parameter	Description
DrHdl hdl	Persistent handle created by the dr_cache_init function.
const char *key	Key to cache, search, or refresh.
PRUint32 klen	Length of the key in bytes.
const char *hdr	Any header data (which can be NULL).
const char *ftr	Any footer data (which can be NULL).
PRUint32 hlen	Length of the header data in bytes (which can be 0).
PRUint32 flen	Length of the footer data in bytes (which can be 0).
PRIntervalTime timeout	Timeout before this function aborts.
PRUint32 flags	ORed directives for this function (see the Flags table, below).
Request *rq	Pointer to the request.
Session *sn	Pointer to the session.

Flags

The following table describes flags for dr_net_write.

Table 7–4 Flags for dr_net_write

Flag	Description
DR_NONE	Specifies that no cache is used, so the function works as net_write does; DrHdl can be NULL.
DR_FORCE	Forces the cache to refresh, even if it has not expired.
DR_CHECK	Returns DR_EXPIR if the cache has expired; if the calling function has not provided a refresh function and this flag is not used, DR_ERROR is returned.
DR_IGNORE	Ignores cache expiration and sends out the cache entry even if it has expired.
DR_CNTLEN	Supplies the Content-Length header and does a PROTOCOL_START_RESPONSE.
DR_PROTO	Does a PROTOCOL_START_RESPONSE.

Example

if(dr_net_write(Dr, szFileName, iLenK, NULL, NULL, 0, 0, 0, 
                DR_CNTLEN | DR_PROTO, rq, sn) == IO_ERROR)
{
    return(REQ_EXIT);
}

fc_open

The fc_open function returns a pointer to PRFileDesc that refers to an open file (fileName). The fileName must be the full path name of an existing file. The file is opened in read mode only. The application calling this function should not modify the currency of the file pointed to by the PRFileDesc * unless the DUP_FILE_DESC is also passed to this function. In other words, the application (at minimum) should not issue a read operation based on this pointer that would modify the currency for the PRFileDesc *. If such a read operation is required (that may change the currency for the PRFileDesc * ), then the application should call this function with the argument DUP_FILE_DESC.

On a successful call to this function, a valid pointer to PRFileDesc is returned and the handle 'FcHdl' is properly initialized. The size information for the file is stored in the 'fileSize' member of the handle.

Syntax

PRFileDesc *fc_open(const char *fileName, FcHdl *hDl,PRUint32 flags, Session *sn, Request *rq);

Returns

Pointer to PRFileDesc, or NULL on failure.

Parameters

const char *fileName is the full path name of the file to be opened.

FcHdl*hDl is a valid pointer to a structure of type FcHdl.

PRUint32 flags can be 0 or DUP_FILE_DESC.

Session *sn is a pointer to the session.

Request *rq is a pointer to the request.

fc_close

The fc_close function closes a file opened using fc_open. This function should only be called with files opened using fc_open.

Syntax

void fc_close(PRFileDesc *fd, FcHdl *hDl;

Returns

void

Parameters

PRFileDesc *fd is a valid pointer returned from a prior call to fc_open.

FcHdl *hDl is a valid pointer to a structure of type FcHdl. This pointer must have been initialized by a prior call to fc_open.

fc_net_write

The fc_net_write function is used to send a header and/or footer and a file that exists somewhere in the system. The fileName should be the full path name of a file.

Syntax

PRInt32 fc_net_write(const char *fileName, const char *hdr, 
                    const char *ftr, PRUint32 hlen,
                    PRUint32 flen, PRUint32 flags, 
                    PRIntervalTime timeout, Session *sn, Request *rq);

Returns

IO_OKAY if successful.

IO_ERROR if an error occurs.

FC_ERROR if an error in file handling occurs.

Parameters

The following table describes parameters for the fc_net_write function.

Table 7–5 fc_net_write parameters

Parameter	Description
const char *fileName	File to be inserted.
const char *hdr	Any header data (which can be NULL).
const char *ftr	Any footer data (which can be NULL).
PRUint32 hlen	Length of the header data in bytes (which can be 0).
PRUint32 flen	Length of the footer data in bytes (which can be 0).
PRUint32 flags	ORed directives for this function (see the Flags table, below).
PRIntervalTime timeout	Timeout before this function aborts.
Request *rq	Pointer to the request.
Session *sn	Pointer to the session.

Flags

The following table describes flags for fc_net_write.

Table 7–6 Flags for fc_net_write

Flag	Description
FC_CNTLEN	Supplies the Content-Length header and does a PROTOCOL_START_RESPONSE.
FC_PROTO	Does a PROTOCOL_START_RESPONSE.

Example

const char *fileName = "/docs/myads/file1.ad";
char *hdr = GenHdr(); // Implemented by plugin
char *ftr = GenFtr(); // Implemented by plugin

if(fc_net_write(fileName, hdr, ftr, strlen(hdr), strlen(ftr),
    FC_CNTLEN, PR_INTERVAL_NO_TIMEOUT, sn, rq) != IO_OKEY)
{
    ereport(LOG_FAILURE, "fc_net_write() failed");
    return REQ_ABORTED;
}