A high performance, low-overhead, zero dependency, thread-safe ConcurrentMap implementation that expires entries. Features include:
- Expiration policies
- Variable expiration
- Expiration listeners
- Lazy entry loading
- Expiration Introspection
Supports Java 6+ though the documentation uses lambdas for simplicity.
ExpiringMap allows you to create a map that expires entries after a certain time period:
Map<String, Connection> map = ExpiringMap.builder()
.expiration(30, TimeUnit.SECONDS)
.build();
// Expires after 30 seconds
map.put("connection", connection);
Expiration can occur based on an entry's creation time or last access time:
Map<String, Connection> map = ExpiringMap.builder()
.expirationPolicy(ExpirationPolicy.ACCESSED)
.build();
We can also specify an expiration policy for individual entries:
map.put("connection", connection, ExpirationPolicy.CREATED);
And we can change policies on the fly:
map.setExpirationPolicy("connection", ExpirationPolicy.ACCESSED);
Entries can have individually variable expiration times and policies:
ExpiringMap<String, Connection> map = ExpiringMap.builder()
.variableExpiration()
.build();
map.put("connection", connection, ExpirationPolicy.ACCESSED, 5, TimeUnit.MINUTES);
Expiration times and policies can also be changed on the fly:
map.setExpiration(connection, 5, TimeUnit.MINUTES);
map.setExpirationPolicy(connection, ExpirationPolicy.ACCESSED);
Expiration listeners can be notified when an entry expires:
Map<String, Connection> map = ExpiringMap.builder()
.expirationListener((key, connection) -> connection.close())
.build();
Expiration listeners are called synchronously as entries expire, and write operations to the map are blocked until the listeners complete. Asynchronous expiration listeners can also be configured and are called in a separate thread pool without blocking map operations:
Map<String, Connection> map = ExpiringMap.builder()
.asyncExpirationListener((key, connection) -> connection.close())
.build();
Expiration listeners can also be added and removed on the fly:
ExpirationListener<String, Connection> connectionCloser = (key, connection) -> connection.close();
map.addExpirationListener(connectionCloser);
map.removeExpirationListener(connectionCloser);
Entries can be lazily loaded via an EntryLoader
when ExpiringMap.get
is called:
Map<String, Connection> connections = ExpiringMap.builder()
.expiration(10, TimeUnit.MINUTES)
.entryLoader(address -> new Connection(address))
.build();
// Loads a new connection into the map via the EntryLoader
connections.get("jodah.net");
Lazily loaded entries can also be made to expire at varying times:
Map<String, Connection> connections = ExpiringMap.builder()
.expiringEntry(address -> new ExpiringValue(new Connection(address), 5, TimeUnit.MINUTES))
.build();
ExpiringMap allows you to learn when an entry is expected to expire:
long expiration = map.getExpectedExpiration("jodah.net");
We can also reset the internal expiration timer for an entry:
map.resetExpiration("jodah.net");
And we can learn the configured expiration for individual entries:
map.getExpiration("jodah.net");
When variable expiration is disabled (default), put
and remove
operations have a constant O(1) time complexity. When variable expiration is enabled, put
and remove
operations have a time complexity of O(log n).
Google App Engine users must specify a ThreadFactory
prior to constructing an ExpiringMap
instance in order to avoid runtime permission errors:
ExpiringMap.setThreadFactory(com.google.appengine.api.ThreadManager.currentRequestThreadFactory());
ExpiringMap.create();
See the GAE docs on threads for more info.
JavaDocs are available here.
Copyright 2009-2016 Jonathan Halterman - Released under the Apache 2.0 license.