Panther Web Application Broker supports an external cache mechanism that can be used for server-side caching in place of the built-in file-based caching. This allows Panther Web application instances that are deployed in a distributed environment to share a single global server-side cache in cases where a common file-system is not globally accessible.
The sample source file, rdscache.c, which is provided in the webcache samples directory, is meant to illustrate the implementation of the required hook functions for use with Panther Web's external cache mechanism. This implementation uses Redis for the external cache, and requires the hiredis-vip client software for compiling and linking. At this time of this writing, the required client software is available for only Linux Operating Systems. However, the provided source code can easily be used as a template for implementing the required hook functions using client APIs for other external cache and Database technologies.
Panther Web's external cache mechanism works as follows:
When the option, "ExternalCache," is set to 1 in the [Prolifics Web] section of the INI file, a set of C functions are invoked to handle the web state caching:
int web_cache_set(char *id, void *val, int len)
void *web_cache_get(char *id, int *plen)
int web_cache_remove(char *id)
int web_cache_clean(int age_in_seconds)
The Jserver calls these functions using pointers to them that must be present on the PROTOTYPED FUNCTIONS list for the specific function names mentioned above. For convenience, the sample source file installs the hook functions in its initialization function, web_redis_init(). In order to use this sample code, application code should add a call to this function in jweb.c. Otherwise, application code should add functions to the PROTOTYPED FUNCTIONS list using code like the following:
static SMCONST struct fnc_data cachefuncs =
SM_INTFNC ("web_cache_startup()", web_cache_startup),
SM_INTFNC ("web_cache_shutdown()", web_cache_shutdown),
SM_STRFNC ("web_cache_get_id()", web_cache_get_id),
SM_INTFNC ("web_cache_set(s,s,i)", web_cache_set),
SM_ZROFNC ("web_cache_get(s,i)", web_cache_get),
SM_INTFNC ("web_cache_remove(s)", web_cache_remove),
SM_INTFNC ("web_cache_clean(i)", web_redis_clean)
static int pcount = sizeof (cachefuncs) / sizeof (struct fnc_data);
sm_install(PROTO_FUNC, (struct fnc_data *)cachefuncs, &pcount);
The following is generic documentation for the functionality that applications must implement for each hook function. For documentation that is specific to the sample code for Redis, rdscache.c, please read the comments in that source file.
retcode = web_cache_startup ()
This function is installed as "web_cache_startup()". The jserver calls it so that you can perform cache specific initialization,such as acquiring a connection to a database that will be reused.
The jserver does not do anything with the return code, so it doesn't matter if it is specific to a particular Database.
Some arbitrary value
retcode = web_cache_shutdown ()
This function is installed as "web_cache_shutdown()". The jserver calls this function to allow for the closing of any persistent connections to the cache or other cleanup to be performed. The return code is ignored by the Jserver.
Some arbitrary value
id = web_cache_get_id ()
This function is installed as "web_cache_get_id()". The Jserver calls this function to get a unique id. This id will be used as the leading part of the webid for the current web request, and it will be used as the keyname for which Panther will store its state information into the cache as a single blob value.
web_cahe_get_id() must return a unique key name for use in the cache, and it should be difficult for a hacker to guess. The value returned must be unique across all Jservers.
The webid used by the Jserver is actually not the id returned by this function. The Jserver tacks onto the end of this id its own timestamp, random number, and possibly additional information, in order to construct the final webid that is sent back to the client and available to the application as the webid property of the application.
A pointer to an sm_fmalloc'd buffer containing the id;
NULL if the id cannot be generated due to some failure
retcode = web_cache_set (id, val, len)
This function is installed as "web_cache_set(s,s,i)". The Jserver calls this function to save its state information for the present web request before cleaning up and returning data to the client.
The first parameter is an id that was previously obtained by the Jserver by calling web_cache_get_id(). It will be used as the key name for the single cache entry that will be made by this function.
The second parameter is a pointer to a buffer containing the state information in some custom binary format used by the Jserver. The buffer will contain all web saved globals, bundles, etc., as one blob.
The final parameter is the length of the data stored in the blob pointed to by val.
A non-zero error code;
Or 0 for no error
val = web_cache_get (id, plen)
This function is installed as "web_cache_get(s,i)". It is of no consequence that the prototype indicates an 'i' for 'int', though the function is actually passed a pointer to an int. The jserver uses the name and prototype only to look up the function in its function list. It, nevertheless, calls the function by its pointer on that function list using a pointer to an int as the second argument.
This function retrieves the blob of state information that had previously been assigned to the key name specified by the id parameter. If non-NULL, as is expected, the plen parameter is filled with length of the blob of data that is returned from this function.
A pointer to a blob of session state information for the id;
The length of the blob data in plen
retcode = web_cache_remove (id)
This function is installed as "web_cache_remove(s)". The jserver calls this function to remove the cache entry for the session state
information corresponding to the id given as the parameter. The jserver ignores the return code.
Some arbitrary value
retcode = web_cache_clean (age)
This function is installed as "web_cache_clean(i)". The Jserver calls this function to remove any cache entry older than the given age in seconds. The age is derived from the value for ExpireTime in the INI file.
Implementations may make this a no-op function if the target cache provides for some other means to specify an expiration time for cache entries.
Note that jserver ignores the return code from this function.
Some arbitrary value