Dynamic Result Cache Functions

                                                                                                                                                                                                                                                                                                                                      Back to [Book]     [Topic]

Dynamic Result Cache Functions

This section describes the following dynamic result cache functions:

dr_cache_destroy() Function

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 Parameters Returns 
void dr_cache_destroy(DrHdl *hdl);
DrHdl *hdl is a pointer to a previously initialized handle to a cache. For more information, see dr_cache_init() Function. void

Example

dr_cache_destroy(&myHdl);

dr_cache_init() Function

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

Syntax Parameters Returns 
PRInt32 dr_cache_init(DrHdl *hdl, RefreshFunc_t ref, FreeFunc_t fre, 
                      CompareFunc_t cmp, PRUint32 maxEntries, 
                      PRIntervalTime maxAge);
DrHdl hdl — Pointer to an unallocated handle.
RefreshFunc_t ref — Pointer to a cache refresh function. This value 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. 		1 if successful.
0 if an error occurs.

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() Function

The dr_cache_refresh function provides a way to refresh a cache entry when the plug-in requires it. This refresh 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.

You can use the plug-in 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. The plug-in then does the cache refresh management actively.

Syntax Parameters Returns 
PRInt32 dr_cache_refresh(DrHdl hdl, const char *key, 
                        PRUint32 klen, PRIntervalTime timeout, 
                        Entry *entry, Request *rq, Session *sn);
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. 		1 if successful.
0 if an error occurs.

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() Function

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, the function returns with DR_EXPIR.

If ref which is 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 which is 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 which is 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 Parameters Returns 
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);
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 Flags.
Request *rq — Pointer to the request
Session *sn — Pointer to the session 		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.

Flags

This section describes the flags for dr_net_write function.

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() Function

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 a read operation is required, that might 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 Parameters Returns 
PRFileDesc *fc_open(const char *fileName, FcHdl *hDl,
                    PRUint32 flags, Session *sn, Request *rq);
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. 		Pointer to PRFileDesc, or NULL on failure.

fc_close() Function

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

Syntax Parameters Returns 
void fc_close(PRFileDesc *fd, FcHdl *hDl;
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. 		void

fc_net_write() Function

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

Syntax Parameters Returns 
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);
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 Flags.
PRIntervalTime timeout — Timeout before this function aborts
Request *rq — Pointer to the request
Session *sn — Pointer to the session 		IO_OKAY if successful.
IO_ERROR if an error occurs.
FC_ERROR if an error in file handling occurs.

Flags

This section describes the flags for fc_net_write() function.

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;
}

Labels

java java Delete
server server Delete
sun sun Delete
webserver webserver Delete
application application Delete
system system Delete
webtier webtier Delete
guide guide Delete
webserver70 webserver70 Delete
sunjava sunjava Delete
nsapi nsapi Delete
nsapidevelopersguide nsapidevelopersguide Delete
developers developers Delete
web web Delete
+nsapiguide +nsapiguide Delete
nsapiguide nsapiguide Delete
developersguide developersguide Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Sign up or Log in to add a comment or watch this page.


The individuals who post here are part of the extended Sun Microsystems community and they might not be employed or in any way formally affiliated with Sun Microsystems. The opinions expressed here are their own, are not necessarily reviewed in advance by anyone but the individual authors, and neither Sun nor any other party necessarily agrees with them.

Copyright 1994-2009 Sun Microsystems, Inc.
Powered by Atlassian Confluence Sun Guidelines on Public Discourse Privacy Policy Terms of Use Trademarks Site Map Employment Investor Relations Contact