implementation("io.micronaut.cache:micronaut-cache-core")
Micronaut Cache
Cache support for Micronaut
Version:
1 Introduction
This project brings additional cache implementations to Micronaut.
To get started, you need to declare the following dependency:
<dependency>
<groupId>io.micronaut.cache</groupId>
<artifactId>micronaut-cache-core</artifactId>
</dependency>| The configuration implementations in this module require at least Micronaut version 1.3.0. Each implementation is a separate dependency. |
To use the BUILD-SNAPSHOT version of this library, check the
documentation to use snapshots.
2 Release History
For this project, you can find a list of releases (with release notes) here:
3 Cache Abstraction
Similar to Spring and Grails, Micronaut provides a set of caching annotations within the io.micronaut.cache package.
The CacheManager interface allows different cache implementations to be plugged in as necessary.
The SyncCache interface provides a synchronous API for caching, whilst the AsyncCache API allows non-blocking operation.
Cache Annotations
The following cache annotations are supported:
-
@Cacheable - Indicates a method is cacheable within the given cache name
-
@CachePut - Indicates that the return value of a method invocation should be cached. Unlike
@Cacheablethe original operation is never skipped. -
@CacheInvalidate - Indicates the invocation of a method should cause the invalidation of one or many caches.
By using one of the annotations the CacheInterceptor is activated which in the case of @Cacheable will cache the return result of the method.
If the return type of the method is a non-blocking type (either CompletableFuture or an instance of Publisher the emitted result will be cached.
In addition if the underlying Cache implementation supports non-blocking cache operations then cache values will be read from the cache without blocking, resulting in the ability to implement completely non-blocking cache operations.
Caching with Caffeine
To cache using Caffeine add the following dependency to your application:
| This module is built and tested with Caffeine {caffeineVersion} |
implementation("io.micronaut.cache:micronaut-cache-caffeine")<dependency>
<groupId>io.micronaut.cache</groupId>
<artifactId>micronaut-cache-caffeine</artifactId>
</dependency>Then configure one or many caches. For example with application.yml:
Cache Configuration Example
micronaut:
caches:
my-cache:
maximumSize: 20The above example will configure a cache called "my-cache" with a maximum size of 20.
micronaut:
caches:
my-cache:
listen-to-removals: true
listen-to-evictions: true
This example is a cache with the removal/eviction listeners. To be able to use them just implement the com.github.benmanes.caffeine.cache.RemovalListener interface as shown in the example.
@Singleton
public class RemovalListenerImpl implements RemovalListener<K, V> {
@Override
public void onRemoval(
@Nullable K key,
@Nullable V value,
@NonNull RemovalCause cause
) {
}
}|
Naming Caches
Names of caches under |
To configure a weigher to be used with the maximumWeight configuration, create a bean that implements com.github.benmanes.caffeine.cache.Weigher. To associate a given weigher with only a specific cache, annotate the bean with @Named(<cache name>). Weighers without a named qualifier will apply to all caches that don’t have a named weigher. If no beans are found, a default implementation will be used.
4 JCache API support
When there is a JSR 107 (JCache) implementation in the classpath (Ehcache, Hazelcast, Infinispan, etc), the caching abstraction will use the JCache API internally by default. If you want Micronaut to use the concrete implementation API, JCache needs to be disabled:
micronaut:
jcache:
enabled: false5 Redis Support
|
Using the CLI
If you are creating your project using the Micronaut CLI, supply the $ mn create-app my-app --features redis-lettuce |
If you wish to use Redis to cache results the Micronaut Redis module provides a CacheManager implementation that allows using Redis as a backing cache.
6 Ehcache Support
To use Ehcache as the caching implementation, add it as a dependency to your application:
| This module is built and tested with Ehcache {ehcacheVersion} |
implementation("io.micronaut.cache:micronaut-cache-ehcache:3.5.0")<dependency>
<groupId>io.micronaut.cache</groupId>
<artifactId>micronaut-cache-ehcache</artifactId>
<version>3.5.0</version>
</dependency>To have Micronaut create a cache, the minimum configuration is:
ehcache:
caches:
my-cache:
enabled: trueThen, you can use any of the caching annotations with my-cache as cache name.
See the configuration reference to check all possible configuration options.
Tiering options
Ehcache supports the concept of tiered caching. This library allows you to configure tiering caching options on a per-cache basis.
If no tier is explicitly configured, the cache will be configured with a heap tier of 100 entries maximum.
Heap tier
It can be sized by number of entries:
ehcache:
caches:
my-cache:
heap:
max-entries: 5000Or by size:
ehcache:
caches:
my-cache:
heap:
max-size: 200MbOff-heap tier
ehcache:
caches:
my-cache:
offheap:
max-size: 1GbDo not forget to define in the java options the -XX:MaxDirectMemorySize option, according to the off-heap size you
intend to use.
Disk tier
ehcache:
storage-path: /var/caches
caches:
my-cache:
disk:
max-size: 10GbClustered tier
Ehcache supports distributed caching with Terracotta
This is a complete example configuration:
ehcache:
cluster:
uri: terracotta://localhost/my-application
default-server-resource: offheap-1
resource-pools:
resource-pool-a:
max-size: 8Mb
server-resource: offheap-2
resource-pool-b:
max-size: 10Mb
caches:
clustered-cache:
clustered-dedicated:
server-resource: offheap-1
max-size: 8Mb
shared-cache-1:
clustered-shared:
server-resource: resource-pool-a
shared-cache-3:
clustered-shared:
server-resource: resource-pool-bMultiple tier setup
A cache can be configured with multiple tiers. Read the Ehcache documentation on the valid configuration options.
For example, to configure a heap + offheap + disk cache:
ehcache:
storage-path: /var/caches
caches:
my-cache:
heap:
max-size: 200Mb
offheap:
max-size: 1Gb
disk:
max-size: 10Gb7 Hazelcast Support
Hazelcast caching is supported. Micronaut will create a Hazelcast client instance to connect to an existing Hazelcast server cluster or create an standalone embedded Hazelcast member instance.
| This module is built and tested with Hazelcast {hazelcastVersion} |
Add the Micronaut Hazelcast module as a dependency:
implementation("io.micronaut.cache:micronaut-cache-hazelcast:3.5.0")<dependency>
<groupId>io.micronaut.cache</groupId>
<artifactId>micronaut-cache-hazelcast</artifactId>
<version>3.5.0</version>
</dependency>You can also add Hazelcast module to your project using cli feature as below:
Create a Micronaut application with Hazelcast module
$ mn create-app hello-world -f hazelcastThe minimal configuration to use Hazelcast is to simply declare hazelcast: with a network configuration for addresses of the
Hazelcast cluster (example below).
hazelcast:
network:
addresses: ['121.0.0.1:5701']If you provide a Hazelcast configuration file (ex.: hazelcast.xml, hazelcast.yml, hazelcast-client.xml, or hazelcast-client.yml) in the working directory or classpath, Micronaut will use this configuration file to configure Hazelcast instance.
When using the @Cacheable and other Cache Annotations, Micronaut will create the Hazelcast client and use the underlying IMap Cache Datastore on the server.
The full list of configurable options is below.
| Property | Type | Description |
|---|---|---|
|
java.util.Properties |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.util.Set |
|
|
java.util.concurrent.ConcurrentMap |
|
|
boolean |
|
|
int |
|
|
java.util.List |
|
|
boolean |
|
|
java.util.Collection |
|
|
java.util.Collection |
|
|
int |
|
|
int |
|
|
boolean |
|
|
boolean |
|
|
boolean |
|
|
int |
|
|
int |
For settings not in the above list, a BeanCreatedEventListener can be registered for HazelcastClientConfiguration or HazelcastMemberConfiguration. The listener will allow all properties to be set directly on the configuration instance.
@Singleton
public class HazelcastAdditionalSettings implements BeanCreatedEventListener<HazelcastClientConfiguration> {
@Override
public HazelcastClientConfiguration onCreated(BeanCreatedEvent<HazelcastClientConfiguration> event) {
HazelcastClientConfiguration configuration = event.getBean();
// Set anything on the configuration
return configuration;
}
}Alternatively, the HazelcastClientConfiguration or HazelcastMemberConfiguration bean may be replaced with your own implementation.
To disable Hazelcast:
hazelcast:
enabled: false8 Infinispan Support
Infinispan caching is supported. Micronaut will create an Infinispan client instance to connect to an existing Infinispan server using the HotRod protocol.
| This module is built and tested with Infinispan {infinispanVersion} |
To get started, add the Micronaut Infinispan module as a dependency:
implementation("io.micronaut.cache:micronaut-cache-infinispan:3.5.0")<dependency>
<groupId>io.micronaut.cache</groupId>
<artifactId>micronaut-cache-infinispan</artifactId>
<version>3.5.0</version>
</dependency>By default, Micronaut will setup a
RemoteCacheManager
over 127.0.0.1:11222. To define custom addresses:
infinispan:
client:
hotrod:
server:
host: infinispan.example.com
port: 10222Micronaut will attempt by default to read a /hotrod-client.properties file from the classpath, and if found, use it.
This file is expected to be in
Infinispan configuration format, for example:
# Hot Rod client configuration
infinispan.client.hotrod.server_list = 127.0.0.1:11222
infinispan.client.hotrod.marshaller = org.infinispan.commons.marshall.ProtoStreamMarshaller
infinispan.client.hotrod.async_executor_factory = org.infinispan.client.hotrod.impl.async.DefaultAsyncExecutorFactory
infinispan.client.hotrod.default_executor_factory.pool_size = 1
infinispan.client.hotrod.hash_function_impl.2 = org.infinispan.client.hotrod.impl.consistenthash.ConsistentHashV2
infinispan.client.hotrod.tcp_no_delay = true
infinispan.client.hotrod.tcp_keep_alive = false
infinispan.client.hotrod.request_balancing_strategy = org.infinispan.client.hotrod.impl.transport.tcp.RoundRobinBalancingStrategy
infinispan.client.hotrod.key_size_estimate = 64
infinispan.client.hotrod.value_size_estimate = 512
infinispan.client.hotrod.force_return_values = false
## Connection pooling configuration
maxActive = -1
maxIdle = -1
whenExhaustedAction = 1
minEvictableIdleTimeMillis=300000
minIdle = 1To read this file from a different classpath location:
infinispan:
client:
hotrod:
config-file: classpath:my-infinispan.properties| You can use both an Infinispan’s property file and Micronaut configuration properties. The latter will complement/override values from the former. |
The full list of configurable options via Micronaut properties is below.
| Property | Type | Description |
|---|---|---|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
int |
|
|
boolean |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
int |
|
|
boolean |
|
|
boolean |
|
|
int |
|
|
int |
|
|
java.lang.String |
|
|
int |
|
|
boolean |
|
|
boolean |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
int |
|
|
long |
|
|
int |
|
|
long |
|
|
int |
|
|
java.lang.Class |
|
|
boolean |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
boolean |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
char |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
char |
|
|
java.lang.String |
|
|
java.lang.String |
|
|
java.lang.String |
the configuration file location |
To disable Infinispan:
infinispan:
enabled: false9 MicroStream Support
To use MicroStream as the caching implementation, set up the Micronaut MicroStream module.
10 No Operation Cache Support
Dependent on the environment or when testing it might be undesirable to actually cache items. In such situations a no operation cache manager can be used that will simply accept any items into the cache without actually storing them.
Add the Micronaut no operation cache module as a dependency:
implementation("io.micronaut.cache:micronaut-cache-noop:3.5.0")<dependency>
<groupId>io.micronaut.cache</groupId>
<artifactId>micronaut-cache-noop</artifactId>
<version>3.5.0</version>
</dependency>The no operation cache manager needs to be enabled explicitly:
noop-cache.enabled: true11 Endpoint
The caches endpoint returns information about the caches in the application and permits invalidating them.
To use this endpoint, you need the following dependency:
implementation("io.micronaut.cache:micronaut-cache-management")<dependency>
<groupId>io.micronaut.cache</groupId>
<artifactId>micronaut-cache-management</artifactId>
</dependency>Also note it is disabled by default. To enable it:
endpoints:
caches:
enabled: trueTo get a collection of all caches by name with their configuration, send a GET request to /caches.
$ curl http://localhost:8080/cachesTo get the configuration of a particular cache, include the cache name in your GET request. For example, to access the configuration of the cache 'book-cache':
$ curl http://localhost:8080/caches/book-cacheTo invalidate a specific cache entry within a single cache, send a DELETE request to the named cache URL with the desired key.
This only works for caches which have keys of type String.
|
$ curl -X DELETE http://localhost:8080/caches/book-cache/keyTo invalidate all cached values within a single cache, send a DELETE request to the named cache URL.
$ curl -X DELETE http://localhost:8080/caches/book-cacheTo invalidate all caches, send a DELETE request to /caches.
$ curl -X DELETE http://localhost:8080/cachesConfiguration
To configure the caches endpoint, supply configuration through endpoints.caches.
Caches Endpoint Configuration Example
endpoints:
caches:
enabled: Boolean
sensitive: Boolean| See the section on Built-in endpoints in the user guide for more information. |
Customization
The caches endpoint is composed of a cache data collector and a cache data implementation. The cache data collector (CacheDataCollector) is responsible for returning a publisher that will return the data used in the response. The cache data (CacheData) is responsible for returning data about an individual cache.
To override the default behavior for either of the helper classes, either extend the default implementations (RxJavaRouteDataCollector, DefaultRouteData), or implement the relevant interface directly. To ensure your implementation is used instead of the default, add the @Replaces annotation to your class with the value being the default implementation.
12 Repository
You can find the source code of this project in this repository: