dotCMS logodotCMS logo

Dotcache Viewtool

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:

    <tool>
        <key>dotcache</key>
        <scope>application</scope>
        <class>com.dotcms.rendering.velocity.viewtools.dotcache.DotCacheTool</class>
    </tool>

Usage#

CommandResult
$dotcache.get("foo") or $dotcache.foo 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.clearClears all objects from the cache memory associated with this viewtool

Purge#

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.

Examples#

Check for Cached Data Before Operation#

#set($testing = $dotcache.get("my-cache-key"))
#if(!$testing)
    #set($testing = $json.fetch("https://demo.dotcms.com/api/content/render/false/query/+contentType:Activity%20+deleted:false%20+working:true/orderby/modDate%20desc/limit/4"))
    ## cache for 5 minutes
    $dotcache.put("my-cache-key", $testing, 600)
    ## or cache forever by using this instead:
    ## $dotcache.put("my-cache-key", $testing)
#end
<ul>
    #foreach($con in $testing.contentlets)
       <li>$con.title</li> 
    #end
</ul>

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))
#if(!$rateCheck)
    #set($rateCheck = 1)
#elseif($rateCheck < 3)
    #set($rateCheck = $rateCheck+1)
#else
    ## Too many requests!
    ## Inexpensive code goes here
    $response.sendError(429)
    #stop
#end

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