This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

The Apprenda Distributed Caching API

When building applications for the cloud, it is important to remember that you might have no knowledge of where your application workloads will execute.  Therefore, it is generally safe practice to avoid local caching and storage, since a future request may channel through a different part of the "cloud".   To assist in building robust applications with reliable caching mechanisms, the Apprenda Platform provides a distributed caching service for all guest applications. The Apprenda cache is special in that it provides scoped storage and retrieval, allowing you to store and retrieve values for all applications on the Platform (platform scope), just the local application (application scope), or just Users within the same Organization (Tenant scope - for multi-tenant applications).

The cache is accessed via the Cache property of Apprenda's API contexts:

  • User Context - Use to store data scoped to the User level - the cached data is only visible within the same User context.
  • Application Context - Use to store data scoped to the application level - the cached data is only visible within the same application context.
  • Tenant Context - Use to store data scoped to the Tenant level - cached data is only visible within the same Tenant context (data is shared between Users and applications on a per-Tenant basis).
  • SaaSGrid Context - Use to store and share data across the entire Platform.

Inserting a Value into the Cache

In order to insert a value into the cache, you have to provide the following information to the Insert method:

  • Key of type string
  • Object to store
  • Time to expire for the cache entry

Example:

UserContext.Instance.Cache.Insert(cacheEntry.Key, cacheEntry.Value, TimeSpan.FromSeconds(cacheEntry.SecondsToExpireIn));

Retrieving a Value from the Cache

In order to retrieve a value from the cache, all you have to do is call the Find method under the context where you initially stored the value.

Example:

var val = UserContext.Instance.Cache.Find<string>(key);

Updating a Value in the Cache

Updating a value in the cache is very similar to inserting it. In order to update a value, use the Update method under the context where you initially stored the value and use the same key used to insert.

Example:

UserContext.Instance.Cache.Update(cacheEntry.Key, cacheEntry.Value, TimeSpan.FromSeconds(cacheEntry.SecondsToExpireIn));

Evicting a Value from the Cache

In order to evict a value from the cache, you can provide the key for the entry or a regular expression as a key in order to match and evict more than one entry.

Evict by Key

UserContext.Instance.Cache.Evict(cacheEntry.Key);

Evict using Regex

UserContext.Instance.Cache.Evict(cacheEntry.Key, true);

Caching Sample

The attached Visual Studio Solution is a simple MVC application that allows you to insert, retrieve, update and evict a cache value from the different contexts.

Caching API

The Caching API In Practice

One example of how you might use the Apprenda Caching API is to cache data that you might use to extend the properties of the default ITenantUser (UserContext) that the Apprenda Platform provides.  For example, your application might require that Users have properties that the Apprenda API doesn't supply, perhaps "DateOfBirth" and "FavoriteColor."  It would be quite expensive on every inbound request if your app code went to the database to retrieve those extra properties out of a custom table.  Instead, upon User login, you can retrieve the data once, and place the data into the UserContext cache, like this:

Retrieve the user's DateOfBirth and FavoriteColor from your custom database and then insert that data into the UserContext cache:

UserContext.Instance.Cache.Insert("DateOfBirth", "9-04-1979", TimeSpan.FromMinutes(30));
UserContext.Instance.Cache.Insert("FavoriteColor", "Blue", TimeSpan.FromMinutes(30));
On future requests, you simply retrieve the values from the cache rather than querying the database:
var dob = UserContext.Instance.Cache.Find<string>(DateOfBirth);