Caching is like coffee for your Java application—it keeps things running faster and smoother. And when it comes to caching libraries, Caffeine is the double espresso of the Java world. Built to replace Guava Cache, Caffeine is a high-performance, flexible caching solution with a Java-friendly API and thoughtful design choices.

In this blog post, we’ll dive into the nuts and bolts of Caffeine and show you how to configure it with practical examples.

What is Caffeine?

Caffeine is a Java caching library modeled after Google’s Guava Cache but optimized for higher performance. It employs efficient algorithms, supports asynchronous loading, and offers extensive configuration options.

Key Features of Caffeine:

  1. Flexible expiration policies (e.g., time-based, size-based, or custom policies).
  2. Write-ahead caching to handle expensive computations.
  3. Efficient eviction policies, ensuring cache stays performant as it grows.
  4. Integration-friendly with frameworks like Spring.

Why Use Caffeine?

Java applications often use caching to:

  • Reduce the load on databases or external APIs.
  • Minimize computation overhead.
  • Improve response times.

However, managing a cache isn’t just about storing objects. It’s about managing their lifecycle, such as when to evict old entries, how to size the cache, and what happens when something isn’t cached.

Caffeine excels in these areas by providing clear APIs and sensible defaults.

Setting Up Caffeine in Your Java Project

First, add Caffeine to your project dependencies:

For Maven:

<dependency>
    <groupId>com.github.ben-manes.caffeine</groupId>
    <artifactId>caffeine</artifactId>
    <version>3.1.8</version> <!-- Use the latest version -->
</dependency>

For Gradle:

implementation 'com.github.ben-manes.caffeine:caffeine:3.1.8'

Configuring a Cache with Caffeine

Here’s how to create a cache in Caffeine and configure it with some common policies.

import com.github.benmanes.caffeine.cache.Cache;
import com.github.benmanes.caffeine.cache.Caffeine;

import java.time.Duration;
import java.util.concurrent.TimeUnit;

public class CaffeineExample {
    public static void main(String[] args) {
        Cache<String, String> cache = Caffeine.newBuilder()
                .initialCapacity(20) // Sets the initial size of the cache
                .maximumSize(200)    // Restricts the cache to 200 entries
                .expireAfterAccess(Duration.ofHours(1)) // Evict entries 1 hour after last access
                .expireAfterWrite(24, TimeUnit.HOURS)   // Evict entries 24 hours after creation
                .build();

        // Store something in the cache
        cache.put("key1", "value1");

        // Retrieve it later
        String value = cache.getIfPresent("key1");
        System.out.println("Cached Value: " + value);

        // Simulate eviction after 24 hours
        cache.cleanUp(); // Manual cleanup (if needed)
    }
}

Configuration Breakdown

  1. initialCapacity(20)
    Pre-allocates space for 20 entries, avoiding frequent memory reallocation when the cache grows.

  2. maximumSize(200)
    Limits the cache to 200 entries. Once the cache reaches this size, older entries are evicted based on the eviction policy (usually least recently used, or LRU).

  3. expireAfterAccess(Duration.ofHours(1))
    Removes an entry if it hasn’t been accessed in the last hour. Useful for caches where the freshness of data depends on usage.

  4. expireAfterWrite(24, TimeUnit.HOURS)
    Removes an entry 24 hours after it’s created, regardless of how often it’s accessed. Great for ensuring data doesn’t go stale.

  5. build()
    Finalizes and creates the cache instance.

Real-World Use Case: API Response Caching

Imagine you’re building a microservice that fetches weather data from an external API. You don’t want to hit the API every time a user requests the weather. Here’s how Caffeine can help:

import com.github.benmanes.caffeine.cache.Cache;
import com.github.benmanes.caffeine.cache.Caffeine;

import java.util.concurrent.TimeUnit;

public class WeatherCache {
    private final Cache<String, String> cache = Caffeine.newBuilder()
            .maximumSize(100)
            .expireAfterWrite(1, TimeUnit.HOURS)
            .build();

    public String getWeather(String city) {
        return cache.get(city, this::fetchWeatherFromApi);
    }

    private String fetchWeatherFromApi(String city) {
        // Simulate an API call
        System.out.println("Fetching weather for: " + city);
        return "Sunny in " + city;
    }

    public static void main(String[] args) {
        WeatherCache weatherCache = new WeatherCache();

        // Fetch and cache data
        System.out.println(weatherCache.getWeather("Miami"));
        System.out.println(weatherCache.getWeather("Miami")); // Cached response
    }
}

Best Practices When Using Caffeine

  1. Understand your eviction policies
    Don’t combine size-based and time-based policies unnecessarily, as it can lead to unintended evictions.

  2. Monitor your cache
    Use Caffeine’s built-in statistics tracking to observe hit/miss ratios:

    cache.stats().hitRate();

  3. Choose the right cache size
    Start small and profile your application’s performance before scaling up.

  4. Use async APIs if your cache stores expensive computations

    AsyncLoadingCache<String, String> asyncCache = Caffeine.newBuilder()
        .maximumSize(100)
        .buildAsync(key -> fetchExpensiveValue(key));

Final Thoughts

Caffeine is a powerful, easy-to-use caching library that fits seamlessly into modern Java applications. With its robust configuration options, you can fine-tune the cache behavior to your application’s needs, whether it’s minimizing database load, improving response times, or handling expensive computations.

Pro Tip: Use Caffeine in conjunction with application metrics to ensure you’re caching the right things and keeping your application performant.