Plum DEV Reference Manual

Plum DEV v. 3.0

© 2013 Plum Group, Inc. All rights reserved.

7. How Caching Works

7.1 Plum's Caching Approach

The caching feature of Plum DEV and Plum i.o.n. systems operates like a proxy cache. This is enabled by default for developers using Plum DEV. However, you must enable this feature for Plum i.o.n. systems or nothing will be cached. For more information on how to enable this please see the Operations Documentation that comes with your Plum i.o.n. system.

When a file is requested from the proxy cache, the proxy cache first checks to see whether the file is currently stored locally. If the file is currently stored locally, it then checks when the local copy of the file is set to expire. If the local copy has not expired, it is immediately sent back to the platform. If the local copy has expired, the proxy cache requests only the status of the file from the source site. If the source copy has not been changed, the local copy of the file is sent back to the platform. If the source copy has been changed, the proxy requests the contents of the file from the source site and refreshes the local copy. The following block diagram summarizes how this works:

For script pages, the Plum caching feature only caches in static file formats such as .vxml and .xml, which are usually flagged by the source web server as cacheable. Thus, for dynamic file formats such as .php files, the script pages will never be cached, as most web servers will flag these dynamic files as non-cacheable. See Section 7.2 for more details.

The Plum caching system follows standard proxy caching rules. The behavior of the proxy cache can be modified in two ways. First, the maxage attribute of any of the tags that make web requests can be set to a number of seconds that will override the expiration time for the local copy of the file. If, for instance, maxage is set to "0", the proxy cache will always check the status of the file from the source site.

Second, the maxstale attribute can be set to a number of seconds to extend the "life" of a cached file. If the cached file would have expired 120 seconds ago, but maxstale is set to "300", the local cached file will be sent back to the platform without first verifying the status of the file from the source site.

7.2 Typical Web Server Behavior

General Notes:

To Force Start Page to be Flushed from the Cache:

Change your web server to respond to all document requests with headers that tell the requesting client not to cache the document (see Global Properties and Setting Files to Never Cache).

Cache expiration is based on two possible numbers -- either the expiration time sent by your web server or the age of your file multiplied by 0.1. An expiration time sent by your web server will always override any other behavior. If the initial fetch of your start page had a higher expiration time in it set by your server, it may very well be "stuck" until you clear it out with a prologue page.

To set up a prologue page, you can type a <goto> tag with a maxage value of "0", which will always fetch a fresh copy of the document. See Example 1 of Section 7.3 for more details.

Global Properties and Setting Files to Never Cache:

In VoiceXML, global properties cannot be declared before the root document is loaded. Any cache settings in the root document will not apply to the way the root document itself is loaded.

To work around this limitation, make the root document generated by a script instead of storing it as a static file which forces the web server to send flags back to the IVR to never cache the file (since it was dynamically generated). Alternatively, you can go into your web server configuration and see if there's a global setting that will force the web server to tell the client to never cache files.

For Apache servers, try setting the ExpiresDefault directive to ExpiresDefault "now". Similarly, ExpiresDefault "access" also forces the web server to tell the client to never cache files. For more information on setting the Apache server, go here.

For Microsoft IIS, try changing the setting of the IIS Cache Control:

For more information on settings in IIS, go here.

For further information on cache settings for web servers, go here.

7.3 Examples of Maxage/Maxstale Usage

Flowchart of fetching a resource from the cache:

1. <goto next="myvxml.vxml" maxage="0" maxstale="0"/>, age of cached resource = 110 seconds old

Here is an example of when maxage equals zero and maxstale equals zero. According to the flowchart of fetching a resource from the cache, since the age of the cached resource is greater than the value of maxage, it would fetch "myvxml.vxml" from the server using GET. Thus, when maxage equals zero, the file would always be fetched from the server as long as it is in the cache.

2. <goto next="myvxml.vxml" maxage="150" maxstale="25"/>, age of cached resource = 110 seconds old, expiration time = 100 seconds

Here is an example of when maxage has a value of 150 seconds and maxstale has a value of 25 seconds. For simplicity, let's say the expiration time of "myvxml.vxml" is when it is 100 seconds old. According to the flowchart of fetching a resource from the cache, since the age of the cached resource is less than the value of maxage (110 < 150), it would check the expiration time of "myvxml.vxml." Since the age of the cached resource is greater than the expiration time (110 > 100), a maxstale check is done. Since the maxstale value is provided, the cache engine then checks if the cached copy has exceeded the expiration time by no more than maxstale seconds. Since the cached copy has only exceeded the expiration time by 10 seconds (110 - 100 = 10) and this time is less than the maxstale value (10 < 25), the cache engine fetches "myvxml.vxml" from the server using GET.

Now, for this same example, let's say the value of maxstale was 5 seconds. From this change in maxstale value, since the cached copy has exceeded the expiration time by 10 seconds and this time is greater than the maxstale value (10 < 5), then the cache engine just uses the cached copy of "myvxml.vxml."

Another possible case for this example is if there was no value provided for maxstale. In this case, the cache engine fetches "myvxml.vxml" from the server using GET.

3. <goto next="myvxml.vxml" maxage="150" maxstale="25"/>, age of cached resource = 110 seconds old, expiration time = 120 seconds

Here is another example of when maxage has a value of 150 seconds and maxstale has a value of 25 seconds. However, let's say the expiration time of "myvxml.vxml" is when it is 120 seconds old. According to the flowchart of fetching a resource from the cache, since the age of the cached resource is less than the value of maxage (110 < 150), it would check the expiration time of "myvxml.vxml." Since the age of the cached resource is less than the expiration time (110 < 120), the cache engine just uses the cached copy of "myvxml.vxml."

4. <goto next="myvxml.vxml" maxstale="25"/>, age of cached resource = 110 seconds old, expiration time = 100 seconds

Here is an example of when maxage is not provided and maxstale has a value of 25 seconds. Let's say the expiration time of "myvxml.vxml" is when it is 100 seconds old. According to the flowchart of fetching a resource from the cache, since maxage is not provided, the cache engine then checks the expiration time of "myvxml.vxml." Since the age of the cached resource is greater than the expiration time (110 > 100), a maxstale check is done. Since the maxstale value is provided, the cache engine then checks if the cached copy has exceeded the expiration time by no more than maxstale seconds. Since the cached copy has only exceeded the expiration time by 10 seconds (110 - 100 = 10) and this time is less than the maxstale value (10 < 25), the cache engine fetches "myvxml.vxml" from the server using GET.

Now, for this same example, let's say the value of maxstale was 5 seconds. From this change in maxstale value, since the cached copy has exceeded the expiration time by 10 seconds and this time is greater than the maxstale value (10 > 5), then the cache engine just uses the cached copy of "myvxml.vxml."

Another possible case for this example is if there was no value provided for maxstale. In this case, the cache engine fetches "myvxml.vxml" from the server using GET.