Client API: How to Setup Aggressive Caching

Standard Cache Configuration

The RavenDB client provides a caching mechanism out of the box. The default caching configuration is to cache all requests.

The size of cache can be configured by changing MaxHttpCacheSize convention.

The client utilizes the notion of the 304 Not Modified server's response and will serve the data from the cache if available.

Aggressive Mode

The aggressive caching feature goes even further. Enabling it means that the client doesn't need to ask the server. It will simply return the response directly from a local cache without any usage of 304 Not Modified status. Results will be returned very fast.

Here's how it works: The client subscribes to server notifications. By taking advantage of them, he is able to invalidate cached documents when they are changed. The client knows when it can serve the response from the cache, and when it has to send the request to get the up-to-date result.

We can activate this mode globally from the store or per session.

To activate this mode globally from the store we just need to add one of the following lines:

documentStore.aggressivelyCacheFor(Duration.ofMinutes(5));

documentStore.aggressivelyCache(); // Defines the cache duration for 1 day

If we want to activate this mode only in the session we need to add this in the session:

try (CleanCloseable cacheScope = session.advanced().getDocumentStore()
        .aggressivelyCacheFor(Duration.ofMinutes(5))) {
    Order user = session.load(Order.class, "orders/1");
}

If there is a value in the cache for orders/1 that is at most 5 minutes old and we haven't got any change notification about it, we can directly return it. The same mechanism works on queries as well:

try (CleanCloseable cacheScope = session.advanced().getDocumentStore()
        .aggressivelyCacheFor(Duration.ofMinutes(5))) {
    List<Order> orders = session.query(Order.class)
        .toList();
}

The usage of the notification system means that you can set an aggressive cache duration to a longer period. The document store exposes the method:

try (CleanCloseable cacheScope = session
    .advanced().getDocumentStore().aggressivelyCache()) {

}

which is equivalent to:

try (CleanCloseable cacheScope = session
    .advanced().getDocumentStore().aggressivelyCacheFor(Duration.ofDays(1))) {

}

Disable Aggressive Mode

We can disable the aggressive mode by simply using documentStore.disableAggressiveCaching(). In that way we will disable the aggressive caching globally in the store. But what if we need to disable the aggressive caching only for a specific call, or to manually update the cache, just like before we can use disableAggressiveCaching() per session?

try (CleanCloseable cacheScope = session.advanced().getDocumentStore()
        .disableAggressiveCaching()) {
    Order order = session.load(Order.class, "orders/1");
}