Maps API for JavaScript Developer's Guide

H.util.Cache

Class Summary

Implements: H.util.ICache

The cache represents an in-memory LRU-cache with a fixed size. Once the elements held in the cache reach the maximum permitted size, the cache drops the elements with the oldest retrieval time stamp to bring the size of the cached data within bounds. Data elements held in the cache are stored with their IDs and size to facilitate retrieval.

[ For full details, see the Class Details ]

Method Summary

Table 1. Methods
Methods

setMaxSize (maxSize) : {H.util.Cache}

This method sets the maximum size of the cache. If the existing contents of the cache exceed the new size, the least recently used data elements are dropped.

getMaxSize () : {number}

This method retrieves the maximum size of the cache.

getCurrentSize () : {number}

This method retrieves the current size of this cache.

add (id, data, size) : {boolean}

This method adds an element to the cache.

get (id, opt_noUpdate) : {*}

This method retrieves an element from the cache.

drop (id)

This method explicitly removes an element from the cache.

forEach (callback, opt_ctx, opt_matcher)

This method executes a callback function on each entry in the cache. If the optional match predicate is specified, the callback is executed only on those entries for which the predicate returns true.

removeAll (opt_matcher)

This method removes all data elements from the cache. The caller can provide an optional match predicate to narrow down the selection of data elements to be removed.

registerOnDrop (callback)

This method registers a callback to be called each time an entry is dropped from the cache.

Class Description

The cache represents an in-memory LRU-cache with a fixed size. Once the elements held in the cache reach the maximum permitted size, the cache drops the elements with the oldest retrieval time stamp to bring the size of the cached data within bounds. Data elements held in the cache are stored with their IDs and size to facilitate retrieval.

Constructor Details

H.util.Cache(maxSize, opt_onDrop, opt_filter)

Parameters:
 
maxSize:
{number}
 
A value indicating the maximum size of the cache
opt_onDrop:
{function(string, ?, number)=} [optional]
 
A callback to be invoked when a data element is dropped from the cache
opt_filter:
{(function(string, ?, number) : boolean)=} [optional]
 
A function to filter data elements that are not to be cached
Throws:
 
{H.lang.InvalidArgumentError}
 
The constructor throws an error if the 'maxSize' argument is not a positive number, the opt_onDrop argument was set but is not a function or if the opt_filter argument was set but is not a function.

Method Details

setMaxSize (maxSize) : {H.util.Cache}

This method sets the maximum size of the cache. If the existing contents of the cache exceed the new size, the least recently used data elements are dropped.

Parameters:
 
maxSize:
{number}
 
A value indicating the new maximum size of the cache
Returns:
 
{H.util.Cache}
An object representing the cache

getMaxSize () : {number}

This method retrieves the maximum size of the cache.

Returns:
 
{number}
A value indicating the maximum size of the cache

getCurrentSize () : {number}

This method retrieves the current size of this cache.

Returns:
 
{number}
A value indicating the current size of the cache

add (id, data, size) : {boolean}

This method adds an element to the cache.

Parameters:
 
id:
{*}
 
The identifier of this data element, the value is converted to a string.
data:
{*}
 
the actual data to be stored
size:
{number}
 
The size of the data element
Returns:
 
{boolean}
A Boolean value indicating whether the data was successfully added (true)
Throws:
 
{Error}
 
Throws an error if the 'size' argument is not a positive number.

get (id, opt_noUpdate) : {*}

This method retrieves an element from the cache.

Parameters:
 
id:
{string}
 
The ID of the data element to be retrieved.
opt_noUpdate:
{boolean=} [optional]
 
An optional flag to indicate if the retrieved object should not be marked as 'most recently used' (true)
Returns:
 
{*}
The data corresponding to the ID or undefined if the data element is not in the cache

drop (id)

This method explicitly removes an element from the cache.

Parameters:
 
id:
{*}
 
the id of the item to drop

forEach (callback, opt_ctx, opt_matcher)

This method executes a callback function on each entry in the cache. If the optional match predicate is specified, the callback is executed only on those entries for which the predicate returns true.

Parameters:
 
callback:
{function(string, ?, number)}
 
The callback to be invoked for each entry
opt_ctx:
{Object=} [optional]
 
An optional context object to be used as this within the callback
opt_matcher:
{(function(string, ?, number) : boolean)=} [optional]
 
An optional match predicate to filter the entries on which the callback operates

removeAll (opt_matcher)

This method removes all data elements from the cache. The caller can provide an optional match predicate to narrow down the selection of data elements to be removed.

Parameters:
 
opt_matcher:
{(function(string, ?, number) : boolean)=} [optional]
 
An optional function that receives data entry IDs, data and sizes and returns true or false to remove or leave an entry in the cache, respectively

registerOnDrop (callback)

This method registers a callback to be called each time an entry is dropped from the cache.

Parameters:
 
callback:
{(function(string, ?, number))}
 
The callback to be invoked for each removed entry