Spring Cache<\/code> and Couchbase<\/code> as a backing store manager.<\/p>\nTable of Contents<\/strong>
\n<\/p>\n\n- A Word Of Introduction<\/a><\/li>\n
- The
Cache<\/code> Abstraction<\/a><\/li>\n- The Couchbase Implementation<\/a><\/li>\n
- Getting
couchbase-spring-cache<\/code> and Putting it to Work<\/a>\n\n- Downloading and building the
couchbase-spring-cache<\/code> project<\/a><\/li>\n- Starting a Tutorial Project<\/a><\/li>\n
- Add Book Management Entity and Repository<\/a><\/li>\n
- The Main
Spring Boot<\/code> Application<\/a><\/li>\n- Adding Caching Capabilities<\/a><\/li>\n
- Activate Caching in
SimpleBookRepository<\/code><\/a><\/li>\n- Seeing the Data in Couchbase<\/a><\/li>\n<\/ul>\n<\/li>\n
- Conclusion<\/a>
\n<\/li>\n<\/ul>\nA Word Of Introduction<\/h2>\n
There was a lot of work related to Spring<\/code> lately! We’ve been busy working on the Spring Data Couchbase<\/a><\/code> connector to upgrade it to the 2.x generation of the Java SDK, bringing along a host of new features and improvements<\/a> (but more on that in a later blog post)…<\/p>\nAlong the way, it came to our attention that there are a few classes in the project that are not really related directly to Spring Data<\/code> and as such didn’t need to adhere to its formal “Release Train” release cycle: the cache<\/code> package<\/strong>.<\/p>\nSo we started a new simple Spring Boot Cache example project to host the 2.x<\/code> generation of the Couchbase Spring Cache<\/code> implementation<\/strong> on github (couchbaselabs\/couchbase-spring-cache<\/code><\/a>).<\/p>\nLet’s have a look at how it can be leveraged to easily introduce Couchbase-backed caching into a Spring project!<\/p>\n
The Cache<\/code> Abstraction<\/h2>\nSpring Framework comes with a lightweight abstraction of a Cache<\/code> that developers can automatically use by annotating methods in their classes (eg. in a @Repository<\/code> stereotype).<\/p>\nIn order to make use of Spring\u2019s boot caching mechanisms, you simply annotate your methods with a handful of cache-related annotations:<\/p>\n
\n@Cacheable<\/code> will let the first invocation of the annotated method with a particular set of input parameters execute, but the result will be cached and subsequent invocations (with the same set) will be served transparently from the cache.<\/li>\n@CachePut<\/code> will always invoke the method and cache its result (unlike @Cacheable<\/code> it doesn’t optimize the invocation flow).<\/li>\n@CacheEvict<\/code> will compute a cache key from the annotated method’s parameters and remove it from the cache when the method is executed (eg. because invoking this method makes an entry stale).<\/li>\n@Caching<\/code> allows to regroup behavior from the previous annotation into a single one.<\/li>\n@CacheConfig<\/code> allows us to have common cache parameters set on a whole class.<\/li>\n<\/ul>\nThe Couchbase Implementation<\/h2>\n
The abstract mechanism is put in place by the framework, but an actual backing implementation must be chosen. Spring comes with a few of them (in memory Map<\/code>, EhCache<\/code>, Gemfire<\/code>…), but it is absolutely possible to define custom ones, simply by implementing a Cache<\/code> and a CacheManager<\/code> and making it visible in the Spring context<\/strong>.<\/p>\nThat’s the focus of couchbase-spring-cache<\/code>.<\/p>\nEach cache has a name, and each value in the cache has a cache key. The Couchbase implementation will translate that into a document key that reflects that…<\/p>\n
\n- this is a
Cache<\/code> related document (by default using the prefix “cache:<\/code>“)<\/li>\n- it relates to a particular
Cache<\/code> (by adding the CACHE_NAME<\/code> to the prefix above)<\/li>\n- it stores a particular cache value under
CACHE_KEY<\/code> (so all in all “cache:CACHE_NAME:CACHE_KEY<\/code><\/strong>“).<\/li>\n<\/ul>\nFor now the values must be Serializable<\/code> and are stored as a SerializableDocument<\/code> from the 2.x<\/code> Java SDK, but alternative transcoding could be offered in the future, eg. JSON<\/code>\/JsonDocument<\/code>…<\/p>\nGetting couchbase-spring-cache<\/code> and Putting it to Work<\/h2>\nNote:<\/p>\n
As of this writing the project is currently in 1.0-SNAPSHOT<\/code> version so it is not available on Maven Central<\/code> yet. You’ll have to manually build the jar and add it to your local Maven repository.<\/p><\/blockquote>\nDownloading and building the couchbase-spring-cache<\/code> project<\/h2>\nStart by cloning the project from github:<\/p>\n
git clone https:\/\/github.com\/couchbaselabs\/couchbase-spring-cache.git\r\ncd couchbase-spring-cache<\/code><\/pre>\nThen build and install it locally using Maven:<\/p>\n
mvn clean install<\/code><\/pre>\nYou should see a success message indicating the version built and where it was installed:<\/p>\n
[INFO] Installing \/path\/to\/couchbase-spring-cache\/target\/couchbase-spring-cache-1.0-SNAPSHOT.jar<\/span>\r\n\r\nto \/path\/to\/.m2\/repository\/<\/span>com\/couchbase\/client\/couchbase-spring-cache\/1.0-SNAPSHOT\/couchbase-spring-cache-1.0-SNAPSHOT.jar<\/span>\r\n\r\n[INFO] Installing \/path\/to\/couchbase-spring-cache\/pom.xml\r\n\r\nto \/path\/to\/.m2\/repository\/com\/couchbase\/client\/couchbase-spring-cache\/1.0-SNAPSHOT\/couchbase-spring-cache-1.0-SNAPSHOT.pom\r\n\r\n[INFO] ------------------------------------------------------------------------\r\n\r\n[INFO] BUILD SUCCESS\r\n\r\n[INFO] ------------------------------------------------------------------------\r\n\r\n<\/pre>\nStarting a Tutorial Project<\/h2>\n
We’ll build a Spring Cache example project using Maven and Spring Boot<\/code> as a base.
\nStart by creating the following directory structure for the project in a root directory of your choosing (we’ll use cbcache<\/code> here):<\/p>\n cbcache\r\n \u2514\u2500\u2500 src\r\n \u2514\u2500\u2500 main\r\n \u2514\u2500\u2500 java\r\n \u2514\u2500\u2500 com\r\n \u2514\u2500\u2500 couchbase\r\n \u2514\u2500\u2500 demo<\/code><\/pre>\nFor instance, use the following command:<\/p>\n
mkdir -p cbcache\/src\/main\/java\/com\/couchbase\/demo\/\r\ncd cbcache<\/code><\/pre>\nThen initiate the POM at the cbcache root in pom.xml<\/code> with the following content:<\/p>\n\r\n\r\n 4.0.0\r\n\r\n com.couchbase.demo\r\n cbcache\r\n 0.1.0\r\n\r\n \r\n org.springframework.boot\r\n spring-boot-starter-parent\r\n 1.3.0.RELEASE\r\n \r\n\r\n \r\n 1.8\r\n \r\n\r\n \r\n \r\n org.springframework.boot\r\n spring-boot-starter\r\n \r\n \r\n org.springframework\r\n spring-context\r\n \r\n \r\n \r\n com.couchbase.client\r\n couchbase-spring-cache\r\n 1.0-SNAPSHOT\r\n \r\n \r\n\r\n \r\n \r\n \r\n org.springframework.boot\r\n spring-boot-maven-plugin\r\n \r\n \r\n \r\n\r\n<\/code><\/pre>\nAdd Book Management Entity and Repository<\/h2>\n
We’ll use the example of a Book<\/code> repository (as found in the “GETTING STARTED – Caching Data with Spring<\/a>” official guide from Spring.io).<\/p>\nCreate the Book<\/code> entity class in src\/main\/java\/com\/couchbase\/demo\/Book.java<\/code>:<\/p>\nimport java.io.Serializable;\r\n\r\npublic class Book implements Serializable {\r\n\r\n private static final long serialVersionUID = -7674163614777124381L;\r\n\r\n private String isbn;\r\n private String title;\r\n\r\n public Book(String isbn, String title) {\r\n this.isbn = isbn;\r\n this.title = title;\r\n }\r\n\r\n public String getIsbn() {\r\n return isbn;\r\n }\r\n\r\n public void setIsbn(String isbn) {\r\n this.isbn = isbn;\r\n }\r\n\r\n public String getTitle() {\r\n return title;\r\n }\r\n\r\n public void setTitle(String title) {\r\n this.title = title;\r\n }\r\n\r\n @Override\r\n public String toString() {\r\n return \"Book{\" + \"isbn='\" + isbn + ''' + \", title='\" + title + ''' + '}';\r\n }\r\n}<\/code><\/pre>\nNote the Book<\/code> class is Serializable<\/code>, this is important for now for Couchbase storage.<\/p><\/blockquote>\nCreate a simple repository interface and a naive implementation that simulates a delay:<\/p>\n
in src\/main\/java\/com\/couchbase\/demo\/BookRepository.java<\/code>:<\/p>\npackage com.couchbase.demo;\r\n\r\npublic interface BookRepository {\r\n\r\n Book getByIsbn(String isbn);\r\n\r\n}<\/code><\/pre>\nin src\/main\/java\/com\/couchbase\/demo\/SimpleBookRepository.java<\/code>:<\/p>\npackage com.couchbase.demo;\r\n\r\nimport org.slf4j.Logger;\r\nimport org.slf4j.LoggerFactory;\r\n\r\nimport org.springframework.stereotype.Component;\r\n\r\n@Component\r\npublic class SimpleBookRepository implements BookRepository {\r\n\r\n private static final Logger log = LoggerFactory.getLogger(SimpleBookRepository.class);\r\n\r\n @Override\r\n public Book getByIsbn(String isbn) {\r\n simulateSlowService();\r\n Book result = new Book(isbn, \"Some book\");\r\n log.info(\"Actual fetch of \" + isbn);\r\n return result;\r\n }\r\n\r\n \/\/ Don't do this at home\r\n private void simulateSlowService() {\r\n try {\r\n long time = 5000L;\r\n Thread.sleep(time);\r\n } catch (InterruptedException e) {\r\n throw new IllegalStateException(e);\r\n }\r\n }\r\n\r\n}<\/code><\/pre>\nThe Main Spring Boot<\/code> Application<\/h2>\nFinally, create an Application that uses the repository in src\/main\/java\/com\/couchbase\/demo\/Application.java<\/code>:<\/p>\npackage com.couchbase.demo;\r\n\r\nimport org.slf4j.Logger;\r\nimport org.slf4j.LoggerFactory;\r\n\r\nimport org.springframework.beans.factory.annotation.Autowired;\r\nimport org.springframework.boot.CommandLineRunner;\r\nimport org.springframework.boot.SpringApplication;\r\nimport org.springframework.boot.autoconfigure.SpringBootApplication;\r\nimport org.springframework.stereotype.Component;\r\n\r\n@SpringBootApplication\r\npublic class Application {\r\n\r\n private static final Logger log = LoggerFactory.getLogger(Application.class);\r\n\r\n @Component\r\n static class Runner implements CommandLineRunner {\r\n @Autowired\r\n private BookRepository bookRepository;\r\n\r\n @Override\r\n public void run(String... args) throws Exception {\r\n long start;\r\n log.info(\".... Fetching books\");\r\n fetchAndLog(\"isbn-1234\");\r\n fetchAndLog(\"isbn-1234\");\r\n fetchAndLog(\"isbn-1234\");\r\n fetchAndLog(\"isbn-8888\");\r\n fetchAndLog(\"isbn-8888\");\r\n }\r\n\r\n private void fetchAndLog(String isbn) {\r\n long start = System.currentTimeMillis();\r\n Book book = bookRepository.getByIsbn(isbn);\r\n long time = System.currentTimeMillis() - start;\r\n log.info(isbn + \" --> \" + book + \" in \" + time + \"ms\");\r\n }\r\n }\r\n\r\n public static void main(String[] args) {\r\n SpringApplication.run(Application.class, args);\r\n }\r\n}<\/code><\/pre>\nIf you run the Application<\/code>‘s main<\/code> method in your IDE (or if you invoke “mvn spring-boot:run<\/code>” from the command line), you’ll notice that all the calls are indeed quite slow:<\/p>\n[...] .... Fetching books\r\n[...] Actual fetch of isbn-1234\r\n[...] isbn-1234 --> Book{isbn='isbn-1234', title='Some book'} in 5001ms\r\n[...] Actual fetch of isbn-1234\r\n[...] isbn-1234 --> Book{isbn='isbn-1234', title='Some book'} in 5004ms\r\n[...] Actual fetch of isbn-1234\r\n[...] isbn-1234 --> Book{isbn='isbn-1234', title='Some book'} in 5004ms\r\n[...] Actual fetch of isbn-8888\r\n[...] isbn-8888 --> Book{isbn='isbn-8888', title='Some book'} in 5003ms\r\n[...] Actual fetch of isbn-8888\r\n[...] isbn-8888 --> Book{isbn='isbn-8888', title='Some book'} in 5003ms<\/code><\/pre>\nAdding Spring Boot Caching Capabilities<\/h2>\n
In order to enable caching, you must take a few steps: first you must offer Spring a CacheManager<\/code> @Bean<\/code>…<\/p>\nSince we’ll be using the CouchbaseCacheManager<\/code> (of course), we’ll need to connect to a Cluster<\/code> and use a Bucket<\/code> reference (the storage unit where couchbase will store cache documents).
\nSo the CouchbaseCacheManager<\/code> needs a mapping between Cache<\/code> names and the corresponding Bucket<\/code> to use, passed as a Map<String, Bucket><\/code>.<\/p>\nIn src\/main\/java\/com\/couchbase\/demo\/Application.java<\/code>, add the following bean declarations:<\/p>\n public static final String BOOK_CACHE = \"books\";\r\n\r\n @Bean(destroyMethod = \"disconnect\")\r\n public Cluster cluster() {\r\n \/\/this connects to a Couchbase instance running on localhost\r\n return CouchbaseCluster.create();\r\n }\r\n\r\n @Bean(destroyMethod = \"close\")\r\n public Bucket bucket() {\r\n \/\/this will be the bucket where every cache-related data will be stored\r\n \/\/note that the bucket \"default\" must exist\r\n return cluster().openBucket(\"default\", \"\");\r\n }\r\n\r\n @Bean\r\n public CacheManager cacheManager() {\r\n Map<String, Bucket> mapping = new HashMap<String, Bucket>();\r\n \/\/we'll make this cache manager recognize a single cache named \"books\"\r\n mapping.put(BOOK_CACHE, bucket());\r\n return new CouchbaseCacheManager(mapping);\r\n }<\/code><\/pre>\nYou then want to activate the scanning of cache-related annotations and associated proxying by putting the @EnableCaching<\/code> annotation on the Application<\/code> class.<\/p>\nActivate Caching in SimpleBookRepository<\/code><\/h2>\nLet’s see how to activate actual caching on our SimpleBookRepository<\/code> and verify how the application behaves after that.<\/p>\nTo make getByIsbn<\/code> automatically cache on first invocation and serve subsequent invocations with data from the cache, simply annotate it like so:<\/p>\n @Override\r\n @Cacheable(Application.BOOK_CACHE) \/\/using the name of the cache we declared earlier\r\n public Book getByIsbn(String isbn) {\r\n simulateSlowService();\r\n Book result = new Book(isbn, \"Some book\");\r\n log.info(\"Actual fetch of \" + isbn);\r\n return result;\r\n }<\/code><\/pre>\nLet’s run the application again and see how it behaves now:<\/p>\n
[...] .... Fetching books\r\n[...] Actual fetch of isbn-1234\r\n[...] isbn-1234 --> Book{isbn='isbn-1234', title='Some book'} in 5022ms\r\n[...] isbn-1234 --> Book{isbn='isbn-1234', title='Some book'} in 3ms\r\n[...] isbn-1234 --> Book{isbn='isbn-1234', title='Some book'} in 1ms\r\n[...] Actual fetch of isbn-8888\r\n[...] isbn-8888 --> Book{isbn='isbn-8888', title='Some book'} in 5007ms\r\n[...] isbn-8888 --> Book{isbn='isbn-8888', title='Some book'} in 1ms<\/code><\/pre>\nWow! This is much better for invocations past the first one, looks like it is indeed cached :-)<\/p>\n
Seeing the Data in Couchbase<\/h2>\n
Let’s have a quick look at the webconsole to verify that these great timings can be attributed to Couchbase:<\/p>\n
\n- open a new tab in your browser and navigate to
https:\/\/localhost:8091<\/code><\/a>.<\/li>\n- connect to the web console.<\/li>\n
- go to the
Data Buckets<\/code> tab and click on the Documents<\/code> button for the bucket you elected to use (“default”).<\/li>\n<\/ul>\nWhat you see in this screen (quick link<\/a> for the lazies) should be similar to this:<\/p>\n![\"Spring](\"https:\/\/www.couchbase.com\/blog\/wp-content\/uploads\/2015\/12\/cacheddocs.png\")
<\/p>\n