Package Overview

This package provides APIs for handle caching in Ballerina. It consists of a default implementation based on the LRU eviction algorithm.

The cache:AbstractCache object has the common APIs for the caching functionalities. Custom implementations of the cache can be done with different data storages like file, database, etc. with the structural equivalency to the cache:AbstractCacheObject object.

1public type AbstractCache object {
2 public function put(string key, any value, int maxAgeInSeconds) returns Error?;
3 public function get(string key) returns any|Error;
4 public function invalidate(string key) returns Error?;
5 public function invalidateAll() returns Error?;
6 public function hasKey(string key) returns boolean;
7 public function keys() returns string[];
8 public function size() returns int;
9 public function capacity() returns int;

The Ballerina Cache package provides the cache:Cache class, which is a map data structure based implementation of the cache:AbstractCache object. It is not recommended to insert () as the value of the cache since it doesn't make sense to cache a nil.

While initializing the cache:Cache, you need to pass the following parameters as the cache configurations.

  • capacity - Maximum number of entries allowed for the cache
  • evictionFactor - The factor by which the entries will be evicted once the cache is full
  • evictionPolicy - The policy which is used to evict entries once the cache is full
  • defaultMaxAgeInSeconds - Freshness time of all the cache entries in seconds. This value can be overwritten by the

maxAgeInSeconds property when inserting an entry to the cache. '-1' means the entries are valid forever.

  • cleanupIntervalInSeconds - The interval time of the timer task, which cleans the cache entries

This is an optional parameter.

For a better user experience, the above-mentioned configuration is initialized with the below default values:

1public type CacheConfig record {|
2 int capacity = 100;
3 float evictionFactor = 0.25;
4 EvictionPolicy evictionPolicy = LRU;
5 int defaultMaxAgeInSeconds = -1;
6 int cleanupIntervalInSeconds?;

There are 2 mandatory scenarios and 1 optional scenario in which a cache entry gets removed from the cache and maintains the freshness of the cache entries. The 2 independent factors (i.e., eviction policy and freshness time of the cache entry) governs the 3 scenarios.

  1. When using the get API, if the returning cache entry has expired, it gets removed.
  2. When using the put API, if the cache size has reached its capacity, the number of entries get removed based on the 'eviction policy' and the 'eviction factor'.
  3. If cleanupIntervalInSeconds (optional property) is configured, the timer task will remove the expired cache entries based on the configured interval.

The main benefit of using the cleanupIntervalInSeconds (optional) property is that the developer can optimize the memory usage while adding some additional CPU costs and vice versa. The default behaviour is the CPU-optimized method.

For information on the operations, which you can perform with the cache package, see the below Functions. For examples on the usage of the operations, see Cache Example




The cache:Cache object, which is used for all the cache-related operations.


The cache:LinkedList object consists operations of LinkedList data structure which are related to LRU eviction algorithm

Object types



The cache:AbstractCache object is used for custom implementations of the Ballerina cache.




Represents configurations for the cache:Cache object.


Represents a structure to keep data and references to the adjacent nodes of the linked list.




Possible types of eviction policy that can be passed into the EvictionPolicy




Represents Cache related errors.