Caching: Overview, strategy and implementation - akumina/AkuminaTraining GitHub Wiki

Applies to

Akumina Foundation 3.4 and above

Overview

The Akumina framework has a built in caching subsystem that is used in the front end framework. This article will detail how caching is used inside Akumina, the strategy surrounding using the cache, and the implementation of caching in your own widgets.

Note, this deals exclusively with front end caching; in other words, how components within JavaScript cache data and other objects.

Caching at its core will hold data in memory, removing the need to call a data source (which can be an resource expensive operation) for the time the data is is memory (the cache duration).

Technical details

For front end caching of widget data, views, etc., Akumina uses a feature of modern browsers called the localStorage. This is a persistent client side cache, that is used to store data. You can read more about the localStorage at the developer.mozilla.org documentation.

Since localStorage cache does not have the concept of expiration, we additionally leverage a wrapper component that provides this capability. So in this way we provide a timed caching mechanism that is used throughout the framework.

Caching levels

The Caching Strategy of the site determines how often the Akumina Framework cache is refreshed within a browser. The heavier the caching strategy, the less often a page needs to execute the entire page life cycle. Caching strategies are set via the Configuration Settings in the Site Creator. Caching strategies have a set list of names that correspond to specific Caching Intervals, which are listed in minutes. Use one of the following values when setting up your caching strategy.

off - 0 minutes
light - 1 minute
medium - 60 minutes
heavy - 360 minutes
extreme - 1440 minutes

Caching Strategy

The overall goal with caching is to make the site more performant while retaining the ability to deliver content to users in a timely manner. To this end, a properly executed caching strategy will be tuned to the data being shown.

As a general rule, all data should be cached. Data will have different caching needs, but this can be accomodated by making the cache values low, yet still greater than zero. The startegy depends on the data to be shown, and how often that is to be refreshed. Some examples:

Data	Change frequency	Strategy
Calendar	Hourly	A medium cache value, 60 minutes or greater.
News	Constant	A low cache value, 5 minutes or less.
Employee Spotlight	Daily	A high cache value, 24 hours

We can see here we target our cache values to match the frequency of the data. As that need changes we can address the cache duration over time.

Implementation: APIs

The Akumina framework provides a javascript wrapper to get and set caching keys; these are located in the Akumina.AddIn.Cache namespace. To set a cache key, you must provide the keyname, value and expiration (in minutes):

Akumina.AddIn.Cache.Set("keyname","value", Akumina.AddIn.Constants.MIN_CACHE_EXPIRATION);

You can obtain the value of a cache key via the Get method:

Akumina.AddIn.Cache.Get("keyname");

While the item is cached, it will return the value. After the expiration, a null is returned.

The system default value can be obtained via the ConfigurationContext:

Akumina.Digispace.ConfigurationContext.CachingStrategyInterval

Implementation: in custom widgets

All Akumina widgets support caching via the cacheinterval property; it is recommended that all custom widgets make use of cache as well. It is very easy to implement, in the widget code (usually in the Render method), there will be a call to get the cache value. If there is a value return it, if null, then get the data from the data source.

In pseudo code, this is shown as:

var data = Akumina.AddIn.Cache.Get(cacheKey);
if (data != null) {
    // skip to bind template method
    return;
} else {
    // get the data from the source
    Akumina.AddIn.Cache.Get(cacheKey, data, cacheExpiration);
}

Used in conjunction with a settable cacheinterval property, cache will speed up the display of the widget on the page. The property entry in the widget code would look like this:

    this.SetDefaultsProperties = function (requestIn) {
        var requestOut = requestIn
        ...
        requestOut.CacheInterval = _cur.GetPropertyValue(requestIn, "cacheinterval", "");
        ...
    };

In addition, you can have methods that help in getting and setting the cache propertly:

    // Gets a unique cache ID value for the control
    this.GetCacheKey = function () {
        return Akumina.Digispace.ConfigurationContext.getCacheKey(_cur.properties.SenderId);
    };
    // Gets the cache interval value for the control
    // If no value is set, or it is -1, then use the site setting
    this.GetCacheInterval = function () {
        var validCacheInterval =
            typeof (_cur.properties.CacheInterval != "undefined")
            && _cur.properties.CacheInterval != null
            && !isNaN(_cur.properties.CacheInterval);


        if (validCacheInterval) {
            if (_cur.properties.CacheInterval == -1) {
                return Akumina.Digispace.ConfigurationContext.CachingStrategyInterval;
            }
            else {
                return parseInt(_cur.properties.CacheInterval);
            }
        }
        else {
            return 0;
        }
    };

Implementation: Settings

Akumina caching values are set in 2 locations:

Globally - for the site as part of the global settings.
Per Control - a setting for each individual control

Cache is set globally for the site via the site creator and you can read more about this by referencing Caching Strategy (Part of Core Site). Look for "Caching Strategy (Part of Core Site)". Below is a screenshot of the setting inside the site creator:

Site Creator caching settings

Cache on the controls is set on a per control basis. You can see in the properties dialog below the property Cache Interval. When this value is either -1 or left unset, then the system default value is used.

Widget Properties

When set, this value will override the siste setting for this control ONLY.

Implementation: Diagnostics

The Akumina framework provides several diagnostic tools to assist a developer in optimizing the use of cache. In the framework debug panel, we provide a SP Call Count property. This value, shown below, corresponds to the number of times a call "leaks" through the cache.

SPCallCount

There are several implications of this value:

This number should be as low as possible.
This number will be higher on the first page load and lower subsequently.

We can tune this number by changing the cache values for the individual widgets, and on the widget properties screen we can also see how many minutes are left in the cache for a given widget: