ExpiringMap Documentation

You can control whether an entry expires based on when it was first created or when it was last accessed.

• ExpirationPolicy.CREATED: The entry expires after the specified duration from its creation time.
• ExpirationPolicy.ACCESSED: The entry expires after the specified duration from its last access (e.g., via get()).

You can set a global policy via the builder or override it for specific entries and keys.

// Set global policy
Map<String, Connection> map = ExpiringMap.builder()
  .expirationPolicy(ExpirationPolicy.ACCESSED)
  .build(); 

// Set policy for a specific entry during put
map.put("connection", connection, ExpirationPolicy.CREATED);

// Change policy for an existing key on the fly
map.setExpirationPolicy("connection", ExpirationPolicy.ACCESSED);

By default, ExpiringMap uses a constant expiration time for all entries. If you enable .variableExpiration() in the builder, you can specify unique expiration times and policies for every entry.

Note on Performance: When variable expiration is enabled, put and remove operations have a time complexity of O(log n). When disabled (default), they are O(1).

ExpiringMap<String, Connection> map = ExpiringMap.builder()
  .variableExpiration()
  .build();

// Put entry with specific policy and duration
map.put("connection", connection, ExpirationPolicy.ACCESSED, 5, TimeUnit.MINUTES);

// Update expiration/policy for an existing key
map.setExpiration(connection, 5, TimeUnit.MINUTES);
map.setExpirationPolicy(connection, ExpirationPolicy.ACCESSED);

Use ExpiringMap.builder() to create a thread-safe ConcurrentMap that expires entries based on a fixed time duration or a maximum size. This is useful for managing caches or connection pools where you want to prevent memory leaks by automatically removing old data.

Map<String, Connection> map = ExpiringMap.builder()
  .maxSize(123)
  .expiration(30, TimeUnit.SECONDS)
  .build();
  
// Expires after 30 seconds or as soon as a 124th element is added
map.put("connection", connection);

If running on Google App Engine (GAE), you must set a custom ThreadFactory before creating the map to avoid runtime permission errors. Use the GAE ThreadManager to provide the factory.

ExpiringMap.setThreadFactory(com.google.appengine.api.ThreadManager.currentRequestThreadFactory());
ExpiringMap.create();

The ExpiringMap API provides methods to inspect when an entry is scheduled to expire or to manually reset its timer.

// Get the timestamp when the entry is expected to expire
long expiration = map.getExpectedExpiration("jodah.net");

// Reset the internal expiration timer for a key
map.resetExpiration("jodah.net");

// Get the configured expiration duration for a key
long expiration = map.getExpiration("jodah.net");

You can configure the map to automatically load values when get(key) is called for a missing key using an EntryLoader.

• Use .entryLoader(Function) to provide a standard loader.
• Use .expiringEntry(Function) to provide a loader that returns an object containing both the value and its specific expiration settings.

// Standard lazy loading
Map<String, Connection> connections = ExpiringMap.builder()
  .expiration(10, TimeUnit.MINUTES)
  .entryLoader(address -> new Connection(address))
  .build();
  
connections.get("jodah.net"); // Loads connection via EntryLoader

// Lazy loading with variable expiration per entry
Map<String, Connection> connections = ExpiringMap.builder()
  .expiringEntry(address -> new ExpiringValue(new Connection(address), 5, TimeUnit.MINUTES))
  .build();