Cache Control Builder
In this topic ...
Quick Tips
- Do not cache the output of a Method or Action List that contains a processPage(..). Process page output goes directly back to the client and is not the output of the Method or Action List.
Specifying Inputs
The Cache Control builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor."
Input Name Description Name Enter a name for this builder call. The Designer displays this name in the Builder Call List. Action to Cache Select an action to cache in the list. Refresh Interval (seconds) Enter the time in seconds that the selected action output should be retained in the cache. For example, enter "3600" to retain the action output in the cache for 60 minutes. Keys Use the indirect reference picker to specify one or more keys that will be used to trigger a refresh of the action cache. We can select a variable, a method, an action etc. Note that If you cache a method with arguments, and no key action items are specified, method argument values are automatically used as cache keys. When these values change, the action cache is refreshed.
Background on Caching
Caching occurs at two levels within the Factory: at the model level and at the action level. This granularity allows you to maximize caching effectiveness and accommodate most model access scenarios.
High Level - Regenerated Model Cache
The highest level of caching in the Factory is regenerated model caching. Regenerated model caching is used to store pre-generated WebApps. Storing a pre-generated model allows the Factory to skip the WebApp generation process. By default, the model runtime is always cached.
When a user accesses a model, if the WebApp is not already in the cache the WebApp is generated and placed in the Regenerated WebApp Cache. The next time a user with the same custom profile requests the model, the cached model is used.
Low Level - Action Output Cache
This next level of caching is Action Output Caching. Action output caching relies on the regenerated model cache described above. In action output caching, a special output cache is stored within the regenerated model cache with the WebApp. This output cache stores the outputs from model actions, including: Page Actions, Methods, and Action Lists. You use the Cache Control builder to select the model actions you want to cache.
When two users belonging to the same profile run the model, the output from user A's session is cached. When user "B" runs the model he will get the exact results as user "A" without actually activating the model's Main function. This means that user B need not wait while the model and its output are regenerated.
Using the Cache Control Builder
You use the Cache Control builder to select and configure action output caching. This builder allows you to set the caching properties of a specified action within the WebApp. We can:
- Activate caching for a specific model action by selecting the action.
- Specify the length of the time action output is retained in the cache. Data is cleared from the action output cache once the time limit expires.
Specifying a Key
In the "Keys" input we can specify a method-type action or variable in your model as a cache key. This is useful when you have a method that does not take arguments, or the arguments that a method does take are not appropriate for use as a cache key. This might be the case if a method gets an input argument value from a variable or from another method. This builder allows you to use such alternatives to the arguments passed to the method.
You use an indirect reference picker in the "Keys" input to select one or more model actions. When the builder detects a difference in the value of a key, the cache will be refreshed.
A typical use case for a key is provided by a WSDL service call. Here an invoke method (that takes no arguments) is used to invoke the WSDL service. When the results of the service action need to be updated, a key that references values stored in variables fetched by this method can be used to initiate the cache update. When a value changes, the service is rerun to return a new result.
Action Output Caching Tips
Use these tips to determine when, and how best, to configure action output caching.
Deciding Which Actions to Cache
Use the following guidelines when deciding whether or not to cache a model action:
- Action caches are shared across all users that share a profile. Therefore, cache only results that are the same for all those users.
- Model data repositories (Variables, Service Outputs, etc.) are not shared. Never cache an action that writes to a Variable that you want to be available for another action. In general, avoid caching any actions that have important side effects.
- Try to cache the most time-consuming actions.
- Cache at the highest level we can. You will reap the biggest performance benefit by caching an entire method/Action List that returns a page. When a page is cached, the actual byte stream of the returned page is cached, which results in an extra performance win.
Setting Cache Time Out Values
The number of seconds you specify as the cache time out value depends on the application you are creating. Here are some rough guidelines:
- Low time out values - Use low time out values (500 seconds or less) for actions that have a high frequency of change. These might include stock tickers, business news feeds, and other real-time monitoring applications in which data is updated at frequent intervals.
- High time out values - Use high time out values (1800 seconds or more) for actions that have a do not occur with great frequency. These might include a weather report application, inventory update service, and customer information database update functionality.
Caching Methods with Input Arguments
For methods that have input arguments, there is a separate cache entry for every unique set of input values. This can be very effective if there is a relatively small number of different input values being used.
Service call inputs are not used to create separate cache entries. Therefore if the inputs to a particular service call will vary, that service call should not be cached.
Disabling Action Output Caching
We can disable all output caching for the server by including the following line in the ../config/bowstreet.properties file:
DISABLE_OUTPUT_CACHING=true
After you change this setting, restart the server for this change to take effect.
Getting Cache Statistics
An API exists used to to get cache statistics. The class com.bowstreet.util.cache.CacheManager is available to return cache data.
Refer to the JavaDoc on this class for information about using methods in the class. This class supports the following cache operations:
- Clear the entire cache. This will clear all the output cache data from all the Models in the Regenerated Model Cache.
- Clear the output cache of a specific model.
- Enable/Disable caching of action output for the entire Factory server.
- Get statistics about cache hit/miss rate.
Here is an example from a scripted method:
{
var cacheManager = app.getOutputCacheManager();
// Don't reset stat values
var tdData = manager.getCacheStatistics(false);
system.debugOut(tdData);
return tdData;
}
We can also use the following methods on the Cache Manager to manage the action output cache:
// Enable/Disable Output Caching for the server
public void enable(boolean enable)
// Clear the OutputCache for all of the cached models
public void clear()
// Clear the OutputCache for the specified model
public void clear(String strName)
Accessing Cache Statistics
We can view general cached output statistics in the server statistics log files. Here is an example:
Output Cache Hits: 4
Output Cache Misses: 1Hits represent the total hits from all the cached action outputs. Misses are the total number of times that an action had to put a new entry into the cache because either the value had not been cached yet or the cached value had expired.
We can get additional cache statistics using the getCacheStatistics() method. This method takes a boolean Variable called "resetCounters". If you set this Variable to true, the method will reset all of the individual cached action hit/miss values. The output of this method is an object containing all of the statistics for all the models in the cache that have action output caching enabled.
Here is an example of the XML output returned by this method:
<CacheStats>
<CachedModel>
<Name>com.bowstreet.service.ACacheTest</Name>
<ObjectCache>
<Entry>
<Name>TriggerAction:Main</Name>
<Hits>4</Hits>
<Misses>1</Misses>
<Created>Fri Apr 21 15:38:40 EDT 2002</Created>
<Expires>Fri Apr 21 15:48:40 EDT 2002</Expires>
</Entry>
</ObjectCache>
</CachedModel>
</CacheStats>