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_startup()
int
web_cache_shutdown()
char *web_cache_get_id()
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.
web_cache_startup
retcode = web_cache_startup ()
int retcode;
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
web_cache_shutdown
retcode = web_cache_shutdown ()
int retcode;
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
web_cache_get_id
id = web_cache_get_id ()
char *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
web_cache_set
retcode = web_cache_set (id, val, len)
int retcode;
char *id;
void *val;
int 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
web_cache_get
val = web_cache_get (id, plen)
char *val;
char *id;
int *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
web_cache_remove
retcode = web_cache_remove (id)
int retcode;
char *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
web_cache_clean
retcode = web_cache_clean (age)
int retcode;
int 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