Dotcache Viewtool

Last Updated: Oct 20, 2023
documentation for the dotCMS Content Management System

The $dotcache Velocity Viewtool allows temporary storage of generic object data.

Introduced in version 23.01, $dotcache grew out of the older #dotcache directive, and provides an easy way to store data from, e.g., a third-party system.

This viewtool is mapped in toolbox.xml file as follows:



$dotcache.get("foo") or $ or $dotcache["foo"] or $dotcache[$foo]Four equivalent ways to retrieve the object stored with cache key foo — in the last case after the declaration of #set($foo = "foo")
$dotcache.put("foo", "bar"[, 60])Stores the value bar behind the cache key foo, with an (optional) expiration of 60 seconds; if a third argument is not set, the data will be cached forever. (Strictly speaking, it's about 68 years, but who's gonna check?)
$dotcache.putDebounce("foo", "bar"[, 60])Identical to .put(), but with a one-second debounce added before taking effect; this can lessen system overhead in cases where immediate reading of stored data is not necessary
$dotcache.remove("foo")Removes data stored in cache memory behind the cache key foo
$dotcache.clear()Clears all objects from the cache memory associated with this viewtool


A complete purge of the cache used by $dotcache — and the #dotcache directive — can be achieved by visiting the Maintenance panel under System → Maintenance, and navigating to the Cache tab. There, use the dropdown menu to select the Block Directive cache, and then click the Flush button.


Check for Cached Data Before Operation

#set($testing = $dotcache.get("my-cache-key"))
    #set($testing = $json.fetch(""))
    ## cache for 5 minutes
    $dotcache.put("my-cache-key", $testing, 600)
    ## or cache forever by using this instead:
    ## $dotcache.put("my-cache-key", $testing)
    #foreach($con in $testing.contentlets)

Simple IP-Based Rate Limit

This works in tandem with the Request object to obtain a user's IP address, which is used as a cache key. The following code permits no more than three consecutive accesses without a 10-second gap.

#set($cacheKey = "$!{request.getRemoteAddr()}")
#set($rateCheck = $dotcache.get($cacheKey))
    #set($rateCheck = 1)
#elseif($rateCheck < 3)
    #set($rateCheck = $rateCheck+1)
    ## Too many requests!
    ## Inexpensive code goes here

$dotcache.put($cacheKey, $rateCheck, 10)
## Expensive code goes here

Note that this is a simple example that may not work properly in cases where $request cannot retrieve an accurate end-user IP, such as in certain configurations behind a load balancer.

On this page


We Dig Feedback

Selected excerpt: