Library that provides support for auto-configuration of Memcached cache in a Spring Boot application.
It provides implementation for the Spring Cache Abstraction, backed by the Xmemcached. Supports cache eviction per key, as well as clearing out of the entire cache region. Binaries are available from Maven Central.
To plug-in Memcached cache in your application follow the steps below:
-
Include library as a Gradle or Maven compile dependency:
-
Gradle
implementation('io.sixhours:memcached-spring-boot-starter:2.4.2')
-
Maven
<dependency> <groupId>io.sixhours</groupId> <artifactId>memcached-spring-boot-starter</artifactId> <version>2.4.2</version> </dependency>
As the default implementation is backed by Xmemcached if there is a requirement to use Spymemcached (i.e. its forked AWS version) following configuation should be applied:
-
Gradle
implementation('io.sixhours:memcached-spring-boot-starter:2.4.2') { exclude group: 'com.googlecode.xmemcached', module: 'xmemcached' } implementation('com.amazonaws:elasticache-java-cluster-client:1.1.2')
-
Maven
<dependency> <groupId>io.sixhours</groupId> <artifactId>memcached-spring-boot-starter</artifactId> <version>2.4.2</version> <exclusions> <exclusion> <groupId>com.googlecode.xmemcached</groupId> <artifactId>xmemcached</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>com.amazonaws</groupId> <artifactId>elasticache-java-cluster-client</artifactId> <version>1.1.2</version> </dependency>
-
-
Snapshot repository
If you want to use
SNAPSHOT
versions, add the snapshot-repohttps://oss.sonatype.org/content/repositories/snapshots
as shown in the example.
-
Configure
Memcached
key-value store in your properties file (application.yml
).Example
To manually connect to one or more cache servers (nodes), specify comma-separated list of hostname:port with the
static
provider:memcached.cache: servers: example1.com:11211,example2.com:11211 provider: static # default expiration is '1d' ('86400' seconds) and custom ones for cache_name1 and cache_name2 expiration: 1d expiration-per-cache: cache_name1: 1h cache_name2: 30h metrics-cache-names: cache_name1, cache_name2
To connect to a cluster with AWS Auto Discovery, specify cluster configuration endpoint in
memcached.cache.servers
property with theaws
provider:memcached.cache: servers: mycluster.example.com:11211 provider: aws expiration: 86400 # default expiration set to '86400' seconds i.e. 1 day
To connect to a cluster within Google App Engine memcached service, it is sufficient to specify the configuration property for provider with value
appengine
:memcached.cache: provider: appengine expiration: 86400 # default expiration set to '86400' seconds i.e. 1 day
-
Enable caching support by adding
@EnableCaching
annotation to one of your@Configuration
classes.import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.cache.annotation.EnableCaching; @SpringBootApplication @EnableCaching public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
Now you can add caching to an operation of your service:
import org.springframework.cache.annotation.Cacheable; import org.springframework.stereotype.Component; @Component public class BookService { @Cacheable("books") public Book findByTitle(String title) { // ... } }
For further details on using the Memcached cache in a Spring Boot application please look at the demo project.
Properties can be set in your application.yml
file or as a command line properties. Below is the
full list of supported properties:
# MEMCACHED CACHE
memcached.cache.servers: # Comma-separated list of hostname:port for memcached servers (default "localhost:11211")
memcached.cache.provider: # Memcached server provider (use one of following: "static", "aws" or "appengine"). Default provider is "static". Use "aws" for AWS node auto discovery, or "appengine" if running on Google Cloud Platform.
memcached.cache.expiration: # Default cache expiration if not configured per cache (default "0", meaning that cache will never expire). If unit not specified, seconds will be used.
memcached.cache.expiration-per-cache.cacheName: # To set expiration value for cache named "cacheName" {cache_name}:{number} e.g. "authors: 3600" or "authors: 1h". If unit not specified, seconds will be used.
memcached.cache.prefix: # Cache key prefix (default "memcached:spring-boot")
memcached.cache.protocol: # Memcached client protocol. Supports "text" and "binary" protocols (default is "text" protocol)
memcached.cache.operation-timeout: # Memcached client operation timeout (default "2500 milliseconds"). If unit not specified, milliseconds will be used.
memcached.cache.hash-strategy: # Memcached client hash strategy for distribution of data between servers. Supports "standard" (array based : "hash(key) mod server_count"), "libmemcached" (consistent hash), "ketama" (consistent hash), "php" (make easier to share data with PHP based clients), "election", "roundrobin", "random". Default is "standard".
memcached.cache.servers-refresh-interval: # Interval in milliseconds that refreshes the list of cache node hostnames and IP addresses for AWS ElastiCache. The default is 60000 milliseconds.
memcached.cache.metrics-cache-names: # Comma-separated list of cache names for which metrics will be collected.
memcached.cache.disabled-cache-names: # Comma-separated list of cache names for which caching will be disabled. The main purpose of this property is to disable caching for debugging purposes.
All of the values have sensible defaults and are bound to MemcachedCacheProperties class.
Duration properties such as expiration
and expiration-per-cache
by default are using unit of seconds if no unit is specified. For operation-timeout
property unit of milliseconds is the default one.
E.g. to specify an expiration
of 30 seconds, 30
, PT30S
(ISO-8601 format) and 30s
are all equivalent. An operation-timeout
of 500ms can be specified in any of the following form: 500
, PT0.5S
and 500ms
.
Supported units are:
-
ns
for nanoseconds -
us
for microseconds -
ms
for milliseconds -
s
for seconds -
m
for minutes -
h
for hours -
d
for days
Notice:
If different applications are sharing the same Memcached server, make sure to specify unique cache
prefix
for each application in order to avoid cache conflicts.
In order to build the project you will have to have Java 1.8+ and Docker installed. To build the project invoke the following command:
./gradlew clean build
To install the modules in the local Maven repository:
./gradlew clean build publishToMavenLocal
Memcached Spring Boot is an Open Source software released under the Apache 2.0 license.