Represents Cache related errors. This will be returned if an error occurred while doing any of the cache operations.


Error

The `cache:Cache` object, which is used for all the cache-related operations. It is not recommended to insert `()`
as the value of the cache since it doesn't make any sense to cache a nil.


AbstractCache

Called when a new `cache:Cache` object is created.
```ballerina
cache:Cache cache = new({capacity: 10, evictionFactor: 0.2});
```



init

Configurations for the `cache:Cache` object


cacheConfig

CacheConfig

Adds the given key value pair to the cache. If the cache previously contained a value associated with the
provided key, the old value wil be replaced by the newly-provided value.
```ballerina
cache:Error? result = cache.put("Hello", "Ballerina");
```



string

Value to be cached. Value should not be `()`


value

The time in seconds for which the cache entry is valid. If the value is '-1', the entry is
valid forever.


maxAge

decimal

`()` if successfully added to the cache or `Error` if a `()` value is inserted to the cache.


Returns the cached value associated with the provided key.
```ballerina
any|cache:Error value = cache.get(key);
```



Key of the cached value, which should be retrieved


The cached value associated with the provided key or an `Error` if the provided cache key is not
exisiting in the cache or any error occurred while retrieving the value from the cache.


Discards a cached value from the cache.
```ballerina
cache:Error? result = cache.invalidate(key);
```



invalidate

Key of the cache value, which needs to be discarded from the cache


`()` if successfully discarded the value or an `Error` if the provided cache key is not present in the
cache


Discards all the cached values from the cache.
```ballerina
cache:Error? result = cache.invalidateAll();
```



invalidateAll

`()` if successfully discarded all the values from the cache or an `Error` if any error occurred while
discarding all the values from the cache.


Checks whether the given key has an associated cached value.
```ballerina
boolean result = cache.hasKey(key);
```



hasKey

`true` if a cached value is available for the provided key or `false` if there is no cached value
associated for the given key


boolean

Returns a list of all the keys from the cache.
```ballerina
string[] keys = cache.keys();
```



keys

Returns the size of the cache.
```ballerina
int result = cache.size();
```



size

Returns the capacity of the cache.
```ballerina
int result = cache.capacity();
```



capacity

Cache

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



LinkedList

## 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.

```ballerina
public type AbstractCache object {
    public function put(string key, any value, int maxAgeInSeconds) returns Error?;
    public function get(string key) returns any|Error;
    public function invalidate(string key) returns Error?;
    public function invalidateAll() returns Error?;
    public function hasKey(string key) returns boolean;
    public function keys() returns string[];
    public function size() returns int;
    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:

```ballerina
public type CacheConfig record {|
    int capacity = 100;
    float evictionFactor = 0.25;
    EvictionPolicy evictionPolicy = LRU;
    int defaultMaxAgeInSeconds = -1;
    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](https://ballerina.io/learn/by-example/cache.html)


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


EvictionPolicy

The `cache:AbstractCache` object is used for custom implementations of the Ballerina cache.
Any custom cache implementation should be object-wise similar.


Adds the given key value pair to the cache. If the cache previously contained a value associated with the key, the
old value is replaced by the new value.



The time in seconds during which the cache entry is valid. '-1' means, the entry is valid forever


`()` if successfully added to the cache or `Error` if any error occurred while inserting the entry
to the cache


Returns the cached value associated with the provided key.



The key used to retrieve the cached value


The cached value associated with the given key or an `Error` if the provided cache key is not
available or if any error occurred while retrieving from the cache


Discards a cached value from the cache.



Key of the cache entry which needs to be discarded


`()` if successfully discarded or an `Error` if the provided cache key is not available or if any
error occurred while discarding from the cache


Discards all the cached values from the cache.



`()` if successfully discarded all or  an `Error` if any error occurred while discarding all from the
cache


Checks whether the given key has an associated cache value.



`true` if an associated cache value is available for the provided key or `false` if there is not a
cache value associated with the provided key


Represents configurations for the `cache:Cache` object.



Maximum number of entries allowed in the cache


The factor by which the entries will be evicted once the cache is full


evictionFactor

float

The policy which is used to evict entries once the cache is full


evictionPolicy

The default value in seconds which all the cache entries are valid. '-1' means, the entries are
valid forever. This will be overwritten by the the `maxAge` property set when inserting item to
the cache


defaultMaxAge

Interval (in seconds) of the timer task, which will clean up the cache


cleanupInterval

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



Value to be stored in the linked list node


Errors