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.


Initializes new `cache:Cache` instance.
```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 will be replaced by the newly-provided value.
```ballerina
check 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 a `cache:Error` if a `()` value is inserted to the cache.


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



Key of the cached value, which should be retrieved


The cached value associated with the provided key or a `cache: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
check cache.invalidate(key);
```



invalidate

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


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


Discards all the cached values from the cache.
```ballerina
check cache.invalidateAll();
```



invalidateAll

`()` if successfully discarded all the values from the cache or a `cache: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

## Overview

This module provides APIs for in-memory caching by using a semi-persistent mapping from keys to values. Cache entries are added to the cache manually and are stored in the cache until either evicted or invalidated manually.

This is based on the Least Recently Used (LRU) eviction algorithm by using a `map` data structure and defining the most basic operations on a collection of cache entries, which entails basic reading, writing, and deleting individual cache items. 
It does not allow the `()` as a key or value of the cache and entries can be accessed safely by multiple concurrent threads as it is thread-safe.

The cache can be defined with optional configurations as follows:
```ballerina
cache:Cache cache = new (capacity = 10, evictionFactor = 0.2, defaultMaxAge = 0.5, cleanupInterval = 1);
```

The Cache entries will be evicted in case of the following scenarios:

- When using the `get` API, if the returning cache entry has expired, it gets removed.
- When using the `put` API, if the cache size has reached its capacity, the number of entries that get removed will be based on the `eviction policy` and the `eviction factor`.
- If `cleanupInterval` (optional property) is configured, the recurrence task will remove the expired cache entries based on the configured interval. The main benefit of this property is that you can optimize the memory usage while adding some additional CPU costs and vice versa. The default behaviour is the CPU-optimized method.

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.


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


AbstractCache

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 max-age in seconds which all the cache entries are valid. '-1' means, the entries are
valid forever. This will be overwritten by the `maxAge` property set when inserting item into
the cache


defaultMaxAge

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


cleanupInterval

This module provides APIs for in-memory caching by using a semi-persistent mapping from keys to values. Cache entries are added to the cache manually and are stored in the cache until either evicted or invalidated manually.


Errors