Caching improves WebCenter Sites's performance in serving pages. Caching rendered content eliminates the need to render the content each time it is requested. This reduces the hardware requirements for the WebCenter Sites system, reduces the number of times clients make requests for uncached content, and ultimately improves response time.
The caching system has multiple layers, which allows regeneration of cached objects to be done on one cache level, while the client is being served cached content from another cache level. WebCenter Sites comprises the inner level of cache, and Satellite Server comprises the outer layer of cache.
This chapter describes how rendered object caching works in the WebCenter Sites platform. It describes how pages and blobs are cached, where they are cached, and how they are retrieved from cache on both WebCenter Sites and Satellite Server systems.
This chapter contains the following sections:
Both WebCenter Sites and Satellite Server cache pages, pagelets, and blobs. WebCenter Sites provides three different rendering engine caches: CS page cache, BlobServer cache, and SS cache. All the caches are controllable. They can be configured and emptied as follows:
Maximum cache size can be configured. For information and instructions, see Section 7.1.1, "Configuring Maximum Cache Size" WebCenter Sites cache, BlobServer cache, and Satellite Server cache.
Objects can be stored in the cache with expiration information, such that when the object has expired from cache it is removed. For information and instructions, see Section 7.1.2, "Setting Expiration Time for an Individual Entry" WebCenter Sites cache and BlobServer cache.
Objects can be explicitly removed from the cache either manually, or automatically by using CacheManager. For information and instructions, see Section 7.1.3, "Explicitly Removing Entries from Cache" WebCenter Sites cache, BlobServer cache, and Satellite Server cache.
There are two levels of caching for the WebCenter Sites page cache:
In the database.
In memory. Memory cache is a transparent subset of the database cache; however, it is independently configurable.
This section describes the main configuration settings for each cache and contains the following topics:
WebCenter Sites's database cache does not have a maximum size configuration option.
The memory subset of the page cache lets you specify the maximum number of entries present by using the cs.SystemPageCacheCSz property in the futuretense.ini file. Setting a positive integer specifies the maximum number of entries that will be allowed to exist in the cache (the cache uses a Least Recently Used (LRU) algorithm for identifying the entry to be pruned when the maximum size has been reached).
Note:
Setting a value of 0 will cause all entries to be added and then promptly removed. However, this should be avoided.
The cs.SystemPageCacheCSz property must not be set to -1.
The maximum size does not have anything to do with the aggregate number of bytes stored in cache.
The lifetime of an individual entry in the WebCenter Sites page cache is determined by the cscacheinfo setting for each entry. The CacheInfo object derives values, if not explicitly set in the cscacheinfo field, from the configuration file. For CacheInfo syntax, see Section 7.4, "CacheInfo String Syntax."
WebCenter Sites provides two ways of removing entries from cache: manually and automatically, using CacheManager.
You can manually remove an entry from the page cache, you can use the CacheServer servlet. The CacheServer provides two options:
Flushing the entire cache.
Forcing a flush of all pages at the moment they expire. In order to invoke the CacheServer flush all functionality, you must be logged in as a user with destroy privileges on the SiteCatalog table, and specify the parameter all=true when invoking the CacheServer servlet. If you do not specify a parameter, then all expired entries (those whose expiry date is in the past) will be cleared from the cache immediately. Entries that have not yet expired will not be cleared.
Note:
In no case will an expired entry be served from the cache, even if it is still in the database table. WebCenter Sites checks the expiry date of any page it retrieves from cache before serving the page. If WebCenter Sites attempts to serve a page that has expired, the page will be removed from the cache immediately and a new page will be generated.
CacheManager is a module that ties in very closely with the internals of the WebCenter Sites page and blob cache mechanisms. It is a tool that lets you manage the contents of all of the rendering caches based on the items loaded on a page, on the expiration of the pages, or on parameters passed into pages.
CacheManager itself could be the subject of an entirely independent document. However, an overview of its functionality is described herein. For detailed information about its methods and required arguments, consult the COM.FutureTense.Cache.CacheManager Javadoc.
A CacheManager is instantiated using one of two constructors. One constructor sets CacheManager with all of the currently registered Satellite Servers. The other constructor lets you specify which Satellite Servers this instance of CacheManager will actually manage.
Next, the CacheManager needs to be populated with pages and blobs. This is done by using one of the following methods:
setByCachedDate(ICS ics, boolean before, String timestamp) setByItemDate(ICS ics, boolean before, String timestamp) setPagesByArg(ICS ics, String paramName, String paramValue) setPagesByID(ICS ics, String[] ids)
The contents of the Page, Blob and Satellite caches are closely tied together. It is always the case, except as a result of a configuration error, that any object cached on Satellite Server will be present in the WebCenter Sites cache. This means that WebCenter Sites has a record of all entries in all rendering engine caches. CacheManager uses this record in order to be able to manage the contents of each of the caches, without having to directly interrogate each cache for the information explicitly.
setByCachedDate(ICS ics, boolean before, String timestamp)
This method lets you populate CacheManager based on the date an entry was last added to the cache. You can choose whether you want to populate it with all of the entries modified either before or after the date specified.
setByItemDate(ICS ics, boolean before, String timestamp)
This method lets you populate CacheManager based on the date an item on an entry was last modified. As with setByCachedDate(ICS, boolean, String), you can choose whether you want all entries whose items were modified before or after the date specified.
setPagesByArg(ICS ics, String paramName, String paramValue)
This method lets you populate CacheManager based on name-value pairs present in the cache key (including pagename).
setPagesByID(ICS ics, String[] ids)
This method lets you populate CacheManager based on the exact item IDs of the items stored on the pages or blobs in the cache.
Once fully populated, CacheManager is able to manage the contents of the caches. This is done using one of the four main service methods:
flushCSEngine(ICS ics, int mode)
This method flushes all of the pages and blobs currently populated in the CacheManager from the WebCenter Sites page and blob caches.
This method flushes all of the pages and blobs currently populated in the CacheManager from the Satellite Server cache. This is done by sending an HTTP request to the FlushServer servlet with the appropriate <page> and <blob> tags embedded in it. Satellite Server interprets these tags and converts them into a cache key, then flushes the corresponding pages from cache.
refreshCSEngine(ICS ics, int mode)
This method sends a request (using ICS.ReadPage or ICS.BlobServer) that regenerates the object and automatically re-populates the cache
refreshSSEngines(ICS ics)
This method sends a request via HTTP to Satellite Server to read the pages. The returned bytes are ignored, but the result is that the Satellite Server cache is re-populated.
Using these methods it is possible to take advantage of double-buffered caching, a tool that can enable extremely high performance dynamic sites. For more information about double-buffered caching, see Chapter 5, "Page Design and Caching."
The BlobServer cache is an all or nothing cache, entries are either globally cached or globally not cached.
BlobServer caching is disabled if security is enabled. Thus, if bs.security=true, caching is disabled.
This section contains the following topics:
The property bs.bCacheSize in futuretense.ini specifies the number of entries the blob cache will contain. If the size is set to a negative number, the blob cache will be allowed to grow indefinitely.
Blob Server does not support individual entry expiration for cached entries. All cached objects will reside in cache for the timeout determined by the bs.bCacheTimeout property in futuretense.ini. A negative timeout indicates that entries should not time out. A positive integer specifies the number of minutes an object will reside in cache.
BlobServer supports the flushing of both individual entries and all entries from the cache.
To manually remove an entry from cache, simply rename the blobtable parameter to flushblobtable. This will remove the entry corresponding to the rest of the parameters from the cache.
To manually remove all entries from the cache, there are two options. One is to invoke the BlobServer servlet with the parameter flushblobtables (notice the "s"). The other is to invoke the CacheServer servlet as described above. However, this will flush all pages and all blobs from the cache.
Because blob dependency items are recorded when blob links are generated, it is possible to invoke CacheManager to manage blobs as well as pages. (In fact, CacheManager always manages blobs and pages together). Refer to the sections about CacheManager and WebCenter Sites for details about using CacheManager.
Note:
Developers should check the asset status before serving BLOBs. This avoids issues such as the BlobServer serving a BLOB after an asset has been voided (this behavior occurs with basic assets only).
The generic Satellite Server cache configuration is done in the satellite.properties file; typically, however, cache configuration is overridden on an object-by-object basis.
This section describes configuring the maximum cache size and explicitly removing entries from cache (manual removal and automatic removal)
Configuring Maximum Cache Size
The maximum number of entries that can be stored in the cache at once is configurable using the cache_max property in the satellite.properties file. If the property is set to a negative integer, the cache will not be limited by size. Any positive integer will specify the maximum number of entries that can be stored in the cache.
Explicitly Removing Entries from Cache
Individual entries can be removed from the Satellite Server cache either manually or using CacheManager, as explained in this section.
Manual Removal: Satellite Server includes a servlet called FlushServer. By submitting a GET request to this servlet (specifying the username, password and reset parameters), it is possible to flush all of the contents of the Satellite Server cache. It is not possible to flush individual entries using GET.
Automatic Removal: As described above, it is possible to flush the Satellite Server cache using CacheManager. As described, CacheManager is only able to flush entries on Satellite Server if a corresponding object is cached on WebCenter Sites. This is the case because of the way WebCenter Sites tracks the contents of the Satellite Server cache.
As described above, it is possible to flush the Satellite Server cache by using CacheManager, as long as a corresponding object is cached on WebCenter Sites. The corresponding object is required because of the way WebCenter Sites tracks the contents of the Satellite Server cache.
The relevant CacheManager methods for dealing with the Satellite Server cache are flushSSEngines() and refreshSSEngines(). For information about the methods, see Section 7.1.3, "Explicitly Removing Entries from Cache."
The cscacheinfo and sscacheinfo fields of the SiteCatalog are populated with a CacheInfo string. This section describes the format of the string. It is a two-part, comma-separated string. The first part indicates whether the page will be cached. The second part describes the expiration.
Sample values:
false true true,* true,~4 true,@1987-06-05 04:32:10 true,#00:00:00 */*/* * (blank)
The first part in CacheInfo must be one of the following values:
false true (blank)*
If the value is false, then the page will not be cached.
If the value is true, then the page will be cached according to the information provided in the second element.
If the value is blank, then WebCenter Sites will consult the futuretense.ini property cs.alwaysusedisk. If this property is set to yes, then a blank value will be interpreted as having the same behavior as true. If the value is set to no (the default value), then a blank value will be interpreted as having the same behavior as false.
If the value is *, then it will be treated as blank.
The second part in CacheInfo describes when a page that is to be cached should be removed from cache. If the first element is false (or is interpreted as false), then the second element is ignored.
There are three ways of specifying the expiration of a page:
page timeout (in minutes) instant in time expiration cron-like TimePattern expiration
Legal values include:
~<number of minutes> @<date in JDBC format> #<COM.FutureTense.Util.TimePattern format> * (blank)
If the second element starts with the tilde symbol (~), then the value following the tilde symbol (~) must be an integer. The value of this integer is the number of minutes a page will remain in cache after it was first created. A negative value or "0" indicates that the page will never expire (it will remain in cache forever).
If the second element starts with the at symbol (@), then the value following the at symbol (@) must be a date expressed in the JDBC date string format, namely, YYYY-MM-DD HH:MM:SS. Once that date has passed, cached pages will be flushed from cache and the page will no longer be cached.
The TimePattern format is supported for describing page cache expiration. If the second element starts with the hashtag (#), then the value following the hashtag (#) must be a valid TimePattern string as defined by the public class COM.FutureTense.Util.TimePattern.
In general, the TimePattern syntax corresponds to the format used in most UNIX cron tables. It lets you specify expiration at a specific time or times every day, month, week, day of week, and year.
It is expected that the TimePattern format will become the most widely used format for page expiration.
If the second element is *, then the page will assume a timeout expiration behavior, as described in Timeout above. The timeout value will be read from the futuretense.ini file's cs.pgCacheTimeout property.
If the second element is blank, then it assumes the same behavior of *.