0
# Caffeine
1

2
Caffeine is a high-performance, near-optimal in-memory caching library for Java that provides a Google Guava-inspired API with significant performance improvements. The library offers flexible cache construction with optional features including automatic loading of entries, size-based eviction using frequency and recency algorithms, time-based expiration, asynchronous refresh capabilities, key/value reference wrapping, eviction notifications, write propagation, and comprehensive cache access statistics.
3

4
## Package Information
5

6
- **Package Name**: com.github.ben-manes.caffeine:caffeine
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.github.ben-manes.caffeine</groupId>
13
    <artifactId>caffeine</artifactId>
14
    <version>3.2.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.github.benmanes.caffeine.cache.*;
22
import com.github.benmanes.caffeine.cache.stats.*;
23

24
// Specific imports
25
import com.github.benmanes.caffeine.cache.Caffeine;
26
import com.github.benmanes.caffeine.cache.Cache;
27
import com.github.benmanes.caffeine.cache.LoadingCache;
28
import com.github.benmanes.caffeine.cache.AsyncCache;
29
import com.github.benmanes.caffeine.cache.AsyncLoadingCache;
30
import com.github.benmanes.caffeine.cache.CacheLoader;
31
```
32

33
## Basic Usage
34

35
```java
36
import com.github.benmanes.caffeine.cache.*;
37
import java.time.Duration;
38

39
// Create a simple cache
40
Cache<String, String> cache = Caffeine.newBuilder()
41
    .maximumSize(10_000)
42
    .expireAfterWrite(Duration.ofMinutes(10))
43
    .build();
44

45
// Manual cache operations
46
cache.put("key", "value");
47
String value = cache.getIfPresent("key");
48

49
// Create a loading cache
50
LoadingCache<String, String> loadingCache = Caffeine.newBuilder()
51
    .maximumSize(10_000)
52
    .expireAfterWrite(Duration.ofMinutes(10))
53
    .build(key -> fetchValueFromDatabase(key));
54

55
// Automatic loading
56
String loadedValue = loadingCache.get("key");
57
```
58

59
## Architecture
60

61
Caffeine is built around several key components:
62

63
- **Builder Pattern**: `Caffeine` class provides fluent configuration API with 30+ options
64
- **Cache Types**: Four main cache interfaces for different use cases (manual, loading, async variants)
65
- **Eviction Engine**: W-TinyLFU algorithm providing near-optimal cache hit rates
66
- **Reference Management**: Configurable weak/soft reference support for keys and values
67
- **Statistics System**: Comprehensive performance tracking and reporting
68
- **Policy System**: Runtime inspection and modification of cache behavior
69
- **Concurrency**: Thread-safe implementation with performance similar to ConcurrentHashMap
70

71
## Capabilities
72

73
### Cache Construction
74

75
Comprehensive builder API for configuring cache instances with size limits, expiration policies, reference strength, listeners, and statistics.
76

77
```java { .api }
78
// Static factory method
79
public static Caffeine<Object, Object> newBuilder()
80

81
// Terminal methods for cache creation
82
public <K1 extends K, V1 extends V> Cache<K1, V1> build()
83
public <K1 extends K, V1 extends V> LoadingCache<K1, V1> build(CacheLoader<? super K1, V1> loader)
84
public <K1 extends K, V1 extends V> AsyncCache<K1, V1> buildAsync()
85
public <K1 extends K, V1 extends V> AsyncLoadingCache<K1, V1> buildAsync(CacheLoader<? super K1, V1> loader)
86
```
87

88
[Cache Construction](./cache-construction.md)
89

90
### Synchronous Caching
91

92
Manual and loading cache interfaces for synchronous cache operations with automatic value computation.
93

94
```java { .api }
95
// Cache interface - manual operations
96
public interface Cache<K, V> {
97
    V getIfPresent(K key);
98
    V get(K key, Function<? super K, ? extends V> mappingFunction);
99
    void put(K key, V value);
100
    void invalidate(K key);
101
}
102

103
// LoadingCache interface - automatic loading
104
public interface LoadingCache<K, V> extends Cache<K, V> {
105
    V get(K key);
106
    Map<K, V> getAll(Iterable<? extends K> keys);
107
}
108
```
109

110
[Synchronous Caching](./synchronous-caching.md)
111

112
### Asynchronous Caching
113

114
Asynchronous cache interfaces returning CompletableFuture for non-blocking cache operations.
115

116
```java { .api }
117
// AsyncCache interface
118
public interface AsyncCache<K, V> {
119
    CompletableFuture<V> getIfPresent(K key);
120
    CompletableFuture<V> get(K key, Function<? super K, ? extends V> mappingFunction);
121
    void put(K key, CompletableFuture<V> valueFuture);
122
}
123

124
// AsyncLoadingCache interface
125
public interface AsyncLoadingCache<K, V> extends AsyncCache<K, V> {
126
    CompletableFuture<V> get(K key);
127
    CompletableFuture<Map<K, V>> getAll(Iterable<? extends K> keys);
128
}
129
```
130

131
[Asynchronous Caching](./asynchronous-caching.md)
132

133
### Cache Policies and Inspection
134

135
Runtime inspection and control of cache behavior including eviction, expiration, and refresh policies.
136

137
```java { .api }
138
public interface Policy<K, V> {
139
    boolean isRecordingStats();
140
    Optional<Eviction<K, V>> eviction();
141
    Optional<Expiration<K, V>> expireAfterAccess();
142
    Optional<Expiration<K, V>> expireAfterWrite();
143
    Optional<VarExpiration<K, V>> expireVariably();
144
}
145
```
146

147
[Cache Policies](./cache-policies.md)
148

149
### Statistics
150

151
Comprehensive cache performance tracking with immutable statistics snapshots and configurable counters.
152

153
```java { .api }
154
public final class CacheStats {
155
    public long requestCount();
156
    public long hitCount();
157
    public double hitRate();
158
    public long missCount();
159
    public double missRate();
160
    public long loadCount();
161
    public double averageLoadPenalty();
162
    public long evictionCount();
163
}
164
```
165

166
[Statistics](./statistics.md)
167

168
### Functional Interfaces
169

170
Key functional interfaces for cache value loading, removal listening, entry weighing, and custom expiration.
171

172
```java { .api }
173
@FunctionalInterface
174
public interface CacheLoader<K, V> {
175
    V load(K key) throws Exception;
176
}
177

178
@FunctionalInterface  
179
public interface RemovalListener<K, V> {
180
    void onRemoval(K key, V value, RemovalCause cause);
181
}
182

183
@FunctionalInterface
184
public interface Weigher<K, V> {
185
    int weigh(K key, V value);
186
}
187
```
188

189
[Functional Interfaces](./functional-interfaces.md)
190

191
### Object Interning
192

193
String interning functionality for any immutable type, providing memory-efficient canonical instance management.
194

195
```java { .api }
196
@FunctionalInterface
197
public interface Interner<E> {
198
    E intern(E sample);
199
}
200

201
// Static factory methods
202
public static <E> Interner<E> newStrongInterner();
203
public static <E> Interner<E> newWeakInterner();
204
```
205

206
## Types
207

208
### Core Enums
209

210
```java { .api }
211
public enum RemovalCause {
212
    EXPLICIT,    // Manual removal (wasEvicted() = false)
213
    REPLACED,    // Value replaced (wasEvicted() = false)
214
    COLLECTED,   // Garbage collected (wasEvicted() = true)
215
    EXPIRED,     // Time-based expiration (wasEvicted() = true)
216
    SIZE;        // Size-based eviction (wasEvicted() = true)
217
    
218
    public abstract boolean wasEvicted();
219
}
220
```
221

222
### Configuration Classes
223

224
```java { .api }
225
public class CaffeineSpec {
226
    public static CaffeineSpec parse(String spec);
227
    public Caffeine<Object, Object> toCaffeine();
228
}
229

230
@FunctionalInterface
231
public interface Ticker {
232
    long read();
233
    static Ticker systemTicker();
234
}
235

236
@FunctionalInterface  
237
public interface Scheduler {
238
    Future<?> schedule(Executor executor, Runnable command, long delay, TimeUnit unit);
239
    static Scheduler systemScheduler();
240
}
241
```