From b41e3b055da26a7ad7716b6e302371dc40a7e1cc Mon Sep 17 00:00:00 2001 From: Costin Leau Date: Mon, 13 Dec 2010 13:01:47 +0200 Subject: [PATCH] + replace tabs with spaces (for better code rendering) + wrap up docs --- src/docbkx/reference/redis.xml | 558 +++++++++++++++++---------------- 1 file changed, 284 insertions(+), 274 deletions(-) diff --git a/src/docbkx/reference/redis.xml b/src/docbkx/reference/redis.xml index 1b844a7f4..9ac5b7482 100644 --- a/src/docbkx/reference/redis.xml +++ b/src/docbkx/reference/redis.xml @@ -4,314 +4,324 @@ Redis support - One of the key value stores supported by SDKV is Redis. - To quote the project home page: - - Redis is an advanced key-value store. It is similar to memcached but the dataset is not volatile, and values can be strings, - exactly like in memcached, but also lists, sets, and ordered sets. All this data types can be manipulated with atomic operations - to push/pop elements, add/remove elements, perform server side union, intersection, difference between sets, and so forth. - Redis supports different kind of sorting abilities. - - Spring Data Key Value provides easy configuration and access to Redis from Spring application. Offers both low-level and - high-level abstraction for interacting with the store, freeing the user from infrastructural concerns. - - -
- Redis Requirements - SDKV requires Redis 2.0 or above (work is underway to support the upcoming (at the time this document was written) 2.2) and - Java SE 6.0 or above. - In terms of language bindings (or connectors), SDKV integrates with Jedis and - JRedis, two popular open source Java libraries for Redis. If you are aware of - any other connector that we should be integrating is, please send us feedback. - -
- -
- Redis Support High Level View - - The Redis support provides several components (in order of dependencies): - - Low-Level Abstractions - for configuring and handling communication with Redis through the various connector libraries supported as - described in . - High-Level Abstractions - providing a generified, user friendly template classes for interacting with Redis. - explains the abstraction builds on top of the low-level Connection API to handle the - infrastructural concerns and object conversion. - Support Classes - that offer reusable components (built on the aforementioned abstractions) such as - java.util.Collection backed by Redis as documented in - - - For most tasks, the high-level abstractions and support services are the best choice. Note that at any point, one can move between layers - for example, it's very - easy to get a hold of the low level connection (or even the native libray) to communicate directly with Redis. -
+ One of the key value stores supported by SDKV is Redis. + To quote the project home page: + + Redis is an advanced key-value store. It is similar to memcached but the dataset is not volatile, and values can be strings, + exactly like in memcached, but also lists, sets, and ordered sets. All this data types can be manipulated with atomic operations + to push/pop elements, add/remove elements, perform server side union, intersection, difference between sets, and so forth. + Redis supports different kind of sorting abilities. -
- Connecting to Redis - - One of the first tasks when using Redis and Spring is to connect to the store through the IoC container. To do that, a Java connector (or binding) is required; - currently SDKV has support for Jedis and JRedis. No matter the library one chooses, there only one set of SDKV API that one needs to use that behaves consistently - across all connectors, namely the org.springframework.data.keyvalue.redis.connection package and its - RedisConnection and RedisConnectionFactory interfaces for working respectively for retrieving active - connection to Redis. - -
- <interfacename>RedisConnection</interfacename> and <interfacename>RedisConnectionFactory</interfacename> - - RedisConnection provides the building block for Redis communication as it handles the communication with the Redis back-end. - It also automatically translates the underlying connecting library exceptions to Spring's consistent DAO exception - hierarchy so one can switch the connectors - without any code changes as the operation semantics remain the same. - - For the corner cases where the native library API is required, RedisConnection provides a dedicated method - getNativeConnection which returns the raw, underlying object used for communication. - - Active RedisConnection are created through RedisConnectionFactory. In addition, the factories act as - PersistenceExceptionTranslator meaning once declared, allow one to do transparent exception translation for example through the use of the - @Repository annotation and AOP. For more information see the dedicated - section in Spring Framework documentation. - - Depending on the underlying configuration, the factory can return a new connection or an existing connection (in case a pool is used). -
- - The easiest way to work with a RedisConnectionFactory is to configure the appropriate connector through the IoC container and - inject it into the using class. - - - Connector features - - Unfortunately, currently, not connectors support all of Redis features - in particular JRedis does not have support for hashes yet though this is currently being worked on. - When invoking a method on the Connection API that is unsupported by the underlying library, a UnsupportedOperationException - is thrown. - This situation is likely to be fixed in the future, as the various connectors mature. - - - -
- Configuring Jedis connector - - Jedis is one of the connectors supported by the Key Value module through the - org.springframework.data.keyvalue.redis.connection.jedis package. In its simples form, the Jedis configuration looks as follow: - - + Spring Data Key Value provides easy configuration and access to Redis from Spring application. Offers both low-level and + high-level abstraction for interacting with the store, freeing the user from infrastructural concerns. + + +
+ Redis Requirements + SDKV requires Redis 2.0 or above (work is underway to support the upcoming (at the time this document was written) 2.2) and + Java SE 6.0 or above. + In terms of language bindings (or connectors), SDKV integrates with Jedis and + JRedis, two popular open source Java libraries for Redis. If you are aware of + any other connector that we should be integrating is, please send us feedback. + +
+ +
+ Redis Support High Level View + + The Redis support provides several components (in order of dependencies): + + Low-Level Abstractions - for configuring and handling communication with Redis through the various connector libraries supported as + described in . + High-Level Abstractions - providing a generified, user friendly template classes for interacting with Redis. + explains the abstraction builds on top of the low-level Connection API to handle the + infrastructural concerns and object conversion. + Support Classes - that offer reusable components (built on the aforementioned abstractions) such as + java.util.Collection backed by Redis as documented in + + + For most tasks, the high-level abstractions and support services are the best choice. Note that at any point, one can move between layers - for example, it's very + easy to get a hold of the low level connection (or even the native libray) to communicate directly with Redis. +
+ +
+ Connecting to Redis + + One of the first tasks when using Redis and Spring is to connect to the store through the IoC container. To do that, a Java connector (or binding) is required; + currently SDKV has support for Jedis and JRedis. No matter the library one chooses, there only one set of SDKV API that one needs to use that behaves consistently + across all connectors, namely the org.springframework.data.keyvalue.redis.connection package and its + RedisConnection and RedisConnectionFactory interfaces for working respectively for retrieving active + connection to Redis. + +
+ <interfacename>RedisConnection</interfacename> and <interfacename>RedisConnectionFactory</interfacename> + + RedisConnection provides the building block for Redis communication as it handles the communication with the Redis back-end. + It also automatically translates the underlying connecting library exceptions to Spring's consistent DAO exception + hierarchy so one can switch the connectors + without any code changes as the operation semantics remain the same. + + For the corner cases where the native library API is required, RedisConnection provides a dedicated method + getNativeConnection which returns the raw, underlying object used for communication. + + Active RedisConnection are created through RedisConnectionFactory. In addition, the factories act as + PersistenceExceptionTranslator meaning once declared, allow one to do transparent exception translation for example through the use of the + @Repository annotation and AOP. For more information see the dedicated + section in Spring Framework documentation. + + Depending on the underlying configuration, the factory can return a new connection or an existing connection (in case a pool is used). +
+ + The easiest way to work with a RedisConnectionFactory is to configure the appropriate connector through the IoC container and + inject it into the using class. + + + Connector features + + Unfortunately, currently, not connectors support all of Redis features - in particular JRedis does not have support for hashes yet though this is currently being worked on. + When invoking a method on the Connection API that is unsupported by the underlying library, a UnsupportedOperationException + is thrown. + This situation is likely to be fixed in the future, as the various connectors mature. + + + +
+ Configuring Jedis connector + + Jedis is one of the connectors supported by the Key Value module through the + org.springframework.data.keyvalue.redis.connection.jedis package. In its simples form, the Jedis configuration looks as follow: + + - + ]]> - For intense use however, one might want to enable connection pooling or set a certain host or password: + For intense use however, one might want to enable connection pooling or set a certain host or password: - + - + ]]> - -
+ +
-
- Configuring JRedis connector - - JRedis is another popular, open-source connector supported by SDKV through the - org.springframework.data.keyvalue.redis.connection.jredis package. - Since JRedis itself does not support (yet) Redis 2.x commands, SDKV uses an updated fork available - here. - - A typical JRedis configuration can looks like this: +
+ Configuring JRedis connector + + JRedis is another popular, open-source connector supported by SDKV through the + org.springframework.data.keyvalue.redis.connection.jredis package. + Since JRedis itself does not support (yet) Redis 2.x commands, SDKV uses an updated fork available + here. + + A typical JRedis configuration can looks like this: - + - + ]]> - As one can note, the configuration is quite similar to the Jedis one. - - Currently, JRedis does not have support for binary keys. This forces the JredisConnection to perform encoding internally - (through base64 schema). In practice, this means it's safe to read/write arbitrary data however - the Redis key stored values will differ from the decoded ones, even in the simplest cases, since everything (no matter the format) is encoded. This will not be - the case for Redis values. - This issue is currently being addressed in the JRedis project and once fixed, will be incorporated by Spring Data Redis. - - -
- -
- -
- Working with Objects through <classname>RedisTemplate</classname> - - Most users are likely to use RedisTemplate and its coresponding package org.springframework.data.keyvalue.redis.core - the - template is in fact the central class of the Redis module due to its rich feature set. - The template offers a high-level abstraction for Redis interaction - while RedisConnection offer low level methods that accept and return - binary values (byte arrays), the template takes care of serialization and connection management, freeing the user from dealing with such details. - - Moreover, the template provides operations views (following the grouping from Redis command reference) - that offer rich, generified interfaces for working against a certain type or certain key (through the KeyBound interfaces) as described below: - - - Operational views - - - - - - - - Interface - Description - - - - - - - - ValueOperations - Redis string (or value) operations - - - ListOperations - Redis list operations - - - SetOperations - Redis set operations - - - ZSetOperations - Redis zset (or sorted set) operations - - - HashOperations - Redis hash operations - - - - - - BoundValueOperations - Redis string (or value) key bound operations - - - BoundListOperations - Redis list key bound operations - - - BoundSetOperations - Redis set key bound operations - - - BoundZSetOperations - Redis zset (or sorted set) key bound operations - - - BoundHashOperations - Redis hash key bound operations - - - -
- - Once configured, the template is thread-safe and can be reused across multiple instances. - - Out of the box, RedisTemplate uses a Java-based serializer for most of its operations. This means that any object written or read by the template will be - serializer/deserialized through Java. The serialization mechanism can be easily changed on the template and the Redis module offers several implementations available in the - org.springframework.data.keyvalue.redis.serializer package. - - Since it's quite the keys and values stored in Redis can be java.lang.String, the Redis modules provides StringRedisTemplate, - a convenient provides a one-stop solution for intensive operations operations. In addition to be bound to String keys, the template uses the - StringRedisSerializer underneath which means the stored keys and values are human readable (assuming the same encoding is used both in Redis and your code). - For example: - - - + As one can note, the configuration is quite similar to the Jedis one. + + Currently, JRedis does not have support for binary keys. This forces the JredisConnection to perform encoding internally + (through base64 schema). In practice, this means it's safe to read/write arbitrary data however + the Redis key stored values will differ from the decoded ones, even in the simplest cases, since everything (no matter the format) is encoded. This will not be + the case for Redis values. + This issue is currently being addressed in the JRedis project and once fixed, will be incorporated by Spring Data Redis. + + +
+ +
+ +
+ Working with Objects through <classname>RedisTemplate</classname> + + Most users are likely to use RedisTemplate and its coresponding package org.springframework.data.keyvalue.redis.core - the + template is in fact the central class of the Redis module due to its rich feature set. + The template offers a high-level abstraction for Redis interaction - while RedisConnection offer low level methods that accept and return + binary values (byte arrays), the template takes care of serialization and connection management, freeing the user from dealing with such details. + + Moreover, the template provides operations views (following the grouping from Redis command reference) + that offer rich, generified interfaces for working against a certain type or certain key (through the KeyBound interfaces) as described below: + + + Operational views + + + + + + + + Interface + Description + + + + + + + + ValueOperations + Redis string (or value) operations + + + ListOperations + Redis list operations + + + SetOperations + Redis set operations + + + ZSetOperations + Redis zset (or sorted set) operations + + + HashOperations + Redis hash operations + + + + + + BoundValueOperations + Redis string (or value) key bound operations + + + BoundListOperations + Redis list key bound operations + + + BoundSetOperations + Redis set key bound operations + + + BoundZSetOperations + Redis zset (or sorted set) key bound operations + + + BoundHashOperations + Redis hash key bound operations + + + +
+ + Once configured, the template is thread-safe and can be reused across multiple instances. + + Out of the box, RedisTemplate uses a Java-based serializer for most of its operations. This means that any object written or read by the template will be + serializer/deserialized through Java. The serialization mechanism can be easily changed on the template and the Redis module offers several implementations available in the + org.springframework.data.keyvalue.redis.serializer package. + + Since it's quite the keys and values stored in Redis can be java.lang.String, the Redis modules provides StringRedisTemplate, + a convenient provides a one-stop solution for intensive operations operations. In addition to be bound to String keys, the template uses the + StringRedisSerializer underneath which means the stored keys and values are human readable (assuming the same encoding is used both in Redis and your code). + For example: + + + - - - + + + - ... + ... ]]> - - - As with the other Spring templates, RedisTemplate and StringRedisTemplate allow the developer to talk directly to Redis through - the RedisCallback interface: this gives complete control to the developer as it talks directly to the RedisConnection. - - - () { - - public Object doInRedis(RedisConnection connection) throws DataAccessException { - Long size = connection.dbSize(); - ... - } - }); + As with the other Spring templates, RedisTemplate and StringRedisTemplate allow the developer to talk directly to Redis through + the RedisCallback interface: this gives complete control to the developer as it talks directly to the RedisConnection. + + + () { + + public Object doInRedis(RedisConnection connection) throws DataAccessException { + Long size = connection.dbSize(); + ... + } + }); }]]> -
- -
- Support Classes - - Package org.springframework.data.keyvalue.redis.support offers various reusable components that rely on Redis as a backing store. Curently the package contains - various JDK-based interface implementations on top of Redis such as atomic - counters and JDK Collections. - - The atomic counters make it easy to wrap Redis key incrementation while the collections allow easy management of Redis keys with minimal storage exposure or API leakage: in particular - the RedisSet and RedisZSet interfaces offer easy access to the set operations supported by Redis such as - intersection and union while RedisList implements the List, - Queue and Deque contracts (and their equivalent blocking siblings) on top of Redis, exposing the storage as a - FIFO (First-In-First-Out), LIFO (Last-In-First-Out) or capped collection with minimal configuration: - - +
+ +
+ Support Classes + + Package org.springframework.data.keyvalue.redis.support offers various reusable components that rely on Redis as a backing store. Curently the package contains + various JDK-based interface implementations on top of Redis such as atomic + counters and JDK Collections. + + The atomic counters make it easy to wrap Redis key incrementation while the collections allow easy management of Redis keys with minimal storage exposure or API leakage: in particular + the RedisSet and RedisZSet interfaces offer easy access to the set operations supported by Redis such as + intersection and union while RedisList implements the List, + Queue and Deque contracts (and their equivalent blocking siblings) on top of Redis, exposing the storage as a + FIFO (First-In-First-Out), LIFO (Last-In-First-Out) or capped collection with minimal configuration: + + - - - - - + + + + + ]]> - queue; + // injected + private Deque queue; - public void addTag(String tag) { - queue.push(tag); - } + public void addTag(String tag) { + queue.push(tag); + } }]]> -
+ + As shown in the example above, the consuming code is decoupled from the actual storage implementation - in fact there is no indication that Redis is used underneath. This makes moving from + development to production environments transparent and highly increases testability (the Redis implementation can just as well be replaced with an in-memory one). +
+ +
+ Roadmap ahead + + Spring Data Redis project is in its early stages. We are interested in feedback, knowing what your use cases are, what are the common patters you encounter so that the Redis module + better serves your needs. Do contact us using the channels mentioned above, we are interested in hearing from you! +
\ No newline at end of file