README.md

Memcached Spring Boot

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 Amazon's ElastiCache Clustered Client. Supports cache eviction per key, as well as clearing out of the entire cache region. Binaries are available from Maven Central and JCenter.

Usage

To plug-in Memcached cache in your application follow the steps below:

1. Include library as a Gradle or Maven compile dependency:

   • Gradle

     compile('io.sixhours:memcached-spring-boot-starter:1.3.0') 

   • Maven

     <dependency>
         <groupId>io.sixhours</groupId>
         <artifactId>memcached-spring-boot-starter</artifactId>
         <version>1.3.0</version>
     </dependency>

2. 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 mode:

    memcached.cache:
      servers: example1.com:11211,example2.com:11211
      mode: static
      expirations: 86400, cache_name1:3600, cache_name2:108000 # global expiration is '86400' and custom ones for cache_name1 and cache_name2

   To connect to a cluster with AWS Auto Discovery, specify cluster configuration endpoint in memcached.cache.servers property with the dynamic mode:

   memcached.cache:
       servers: mycluster.example.com:11211
       mode: dynamic
       expirations: 86400 # global expiration set to '86400'

3. 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

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.mode: # Memcached client mode (use one of following: "static", "dynamic"). Default mode is "static", use "dynamic" for AWS node auto discovery
memcached.cache.expirations: # Cache expirations in seconds (default "60"). To set new global expiration use value without colon: {number} e.g. "86400". To set value per cache name use format: {cache_name}:{number} e.g. "authors:3600"
memcached.cache.prefix: # Cache key prefix (default "memcached:spring-boot")
memcached.cache.namespace: # Cache eviction namespace key name (default "namespace")
memcached.cache.protocol: # Memcached client protocol. Supports "text" and "binary" protocols (default is "text" protocol)

All of the values have sensible defaults and are bound to MemcachedCacheProperties class.

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.

Build

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 install

License

Memcached Spring Boot is an Open Source software released under the Apache 2.0 license.