diff --git a/docs/src/reference/docbook/index.xml b/docs/src/reference/docbook/index.xml index 39c58c3a7..f319bd27e 100644 --- a/docs/src/reference/docbook/index.xml +++ b/docs/src/reference/docbook/index.xml @@ -16,6 +16,11 @@ Leau SpringSource + + Jennifer + Hickey + SpringSource + diff --git a/docs/src/reference/docbook/introduction/getting-started.xml b/docs/src/reference/docbook/introduction/getting-started.xml index 8384f623d..b769eaf62 100644 --- a/docs/src/reference/docbook/introduction/getting-started.xml +++ b/docs/src/reference/docbook/introduction/getting-started.xml @@ -3,7 +3,7 @@ Getting Started Learning a new framework is not always straight forward. In this section, we (the Spring Data team) - tried to provide, what we think is, an easy to follow guide for starting with Spring Data Key Value module. + tried to provide, what we think is, an easy to follow guide for starting with the Spring Data Redis module. Of course, feel free to create your own learning 'path' as you see fit and, if possible, please report back any improvements to the documentation that can help others. @@ -22,25 +22,25 @@ resource abstract or AOP infrastructure. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar. - These being said, the more knowledge one has about the Spring, the faster she will pick Spring Data Key Value. + That being said, the more knowledge one has about the Spring, the faster she will pick up Spring Data Redis. Besides the very comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework, there are a lot of articles, blog entries and books on the matter - take a look at the Spring framework home page for more information. In general, this should be the starting point for - developers wanting to try Spring DKV. + developers wanting to try Spring DR.
Knowing NoSQL and Key Value stores - NoSQL stores have taken the storage world by storm. It is a vast domain with a plethora of solutions, terms and patterns (to make things worth even the + NoSQL stores have taken the storage world by storm. It is a vast domain with a plethora of solutions, terms and patterns (to make things worse even the term itself has multiple meanings). - While some of the principles are common, it is crucial that the user is familiar to some degree with the stores supported by SDKV. - The best way to get acquainted to this solutions is to read their documentation and follow their examples - it usually doesn't take more then 5-10 minutes + While some of the principles are common, it is crucial that the user is familiar to some degree with the stores supported by SDR. + The best way to get acquainted with these solutions is to read their documentation and follow their examples - it usually doesn't take more then 5-10 minutes to go through them and if you are coming from an RDMBS-only background many times these exercises can be an eye opener.
Trying Out The Samples One can find various samples for key value stores in the dedicated example repo, at - http://github.com/SpringSource/spring-data-keyvalue-examples. For Spring Redis, + http://github.com/SpringSource/spring-data-keyvalue-examples. For Spring Data Redis, of interest is the retwisj sample, a Twitter-clone built on top of Redis which can be run locally or be deployed into the cloud. See its documentation, the following blog entry or the @@ -51,11 +51,11 @@
Need Help? - If you encounter issues or you are just looking for an advice, feel free to use one of the links below: + If you encounter issues or you are just looking for advice, feel free to use one of the links below:
Community Support - The Spring Data forum is a message board for all Spring Data (not just Key Value) users to + The Spring Data forum is a message board for all Spring Data (not just Redis) users to share information and help each other. Note that registration is needed only for posting.
@@ -76,11 +76,11 @@ You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Spring Community forums. If you encounter a bug or want to suggest an improvement, - please create a ticket on the Spring Data issue tracker. + please create a ticket on the Spring Data issue tracker. To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community Portal. Lastly, you can follow the SpringSource Data blog or the project team on Twitter - (Costin) + (Jennifer)
\ No newline at end of file diff --git a/docs/src/reference/docbook/introduction/why-sdr.xml b/docs/src/reference/docbook/introduction/why-sdr.xml index efd53144e..be1bedcbf 100644 --- a/docs/src/reference/docbook/introduction/why-sdr.xml +++ b/docs/src/reference/docbook/introduction/why-sdr.xml @@ -10,10 +10,10 @@ NoSQL storages provide an alternative to classical RDBMS for horizontal scalability and speed. In terms of implementation, Key Value stores represent one of the - largest (and oldest) member in the NoSQL space. + largest (and oldest) members in the NoSQL space. The Spring Data Redis (or SDR) framework makes it easy to write Spring applications that use the Redis key value store by eliminating the redundant - tasks and boiler place code required for interacting with the store through + tasks and boiler plate code required for interacting with the store through Spring's excellent infrastructure support. \ No newline at end of file diff --git a/docs/src/reference/docbook/reference/redis-messaging.xml b/docs/src/reference/docbook/reference/redis-messaging.xml index e51901f2d..1ed3a448b 100644 --- a/docs/src/reference/docbook/reference/redis-messaging.xml +++ b/docs/src/reference/docbook/reference/redis-messaging.xml @@ -3,7 +3,7 @@ Redis Messaging/PubSub Spring Data provides dedicated messaging integration for Redis, very similar in functionality and naming to the JMS integration in - Spring Framework; in fact, users familiar with the JMS support in Spring, should + Spring Framework; in fact, users familiar with the JMS support in Spring should feel right at home. Redis messaging can be roughly divided into two areas of functionality, namely @@ -12,7 +12,7 @@ RedisTemplate class is used for message production. For asynchronous reception similar to Java EE's message-driven bean style, Spring Data provides a dedicated message - listener containers that is used to create Message-Driven POJOs + listener container that is used to create Message-Driven POJOs (MDPs) and for synchronous reception, the RedisConnection contract. The package org.springframework.data.redis.connection and @@ -46,7 +46,7 @@ template.convertAndSend("hello!", "world");]]> On the receiving side, one can subscribe to one or multiple channels either by naming them directly or by using pattern matching. The latter approach is quite useful as it not only allows multiple subscriptions to be created with - one command but to also listen on channels not yet created at subscription time (as long as match the pattern). + one command but to also listen on channels not yet created at subscription time (as long as they match the pattern). At the low-level, RedisConnection offers subscribe and @@ -55,16 +55,16 @@ template.convertAndSend("hello!", "world");]]> whether it is listening or not, RedisConnection provides getSubscription and isSubscribed method. - Subscribing commands are synchronized and thus blocking. That is, calling subscribe on a connection will cause + When using Jedis, JRedis or RJC connectors, subscribing commands are synchronous and thus blocking. That is, calling subscribe on a connection will cause the current thread to block as it will start waiting for messages - the thread will be released only if the subscription - is canceled, that is an additional thread invokes unsubscribe respectively pUnsubscribe + is canceled, that is an additional thread invokes unsubscribe or pUnsubscribe on the same connection. See message listener container below - for a solution to these problem. + for a solution to this problem. - As mentioned above, one subscribed a connection starts waiting for messages - no other commands can be invoked on it except - for adding new subscriptions or modifying/canceling the existing ones, that is invoking anything else then subscribe, - pSubscribe, unsubscribe, pUnsubscribe or is illegal and will - through an exception. + As mentioned above, once subscribed a connection starts waiting for messages. No other commands can be invoked on it except + for adding new subscriptions or modifying/canceling the existing ones. That is, invoking anything other then subscribe, + pSubscribe, unsubscribe, or pUnsubscribe is illegal and will + throw an exception. In order to subscribe for messages, one needs to implement the MessageListener callback: each time a new message arrives, the callback gets invoked and the user code executed through onMessage method. @@ -82,18 +82,18 @@ template.convertAndSend("hello!", "world");]]> support in Spring Framework and its message-driven POJOs (MDPs) RedisMessageListenerContainer acts as a message listener container; it is used to receive messages from a - Redis channel and drive the MessageListener that are injected into + Redis channel and drive the MessageListeners that are injected into it. The listener container is responsible for all threading of message reception and dispatches into the listener for processing. A message listener container is the intermediary between an MDP and a messaging provider, and takes care of registering to receive messages, resource acquisition and release, - exception conversion and suchlike. This allows you as an application + exception conversion and the like. This allows you as an application developer to write the (possibly complex) business logic associated with receiving a message (and reacting to it), and delegates boilerplate Redis infrastructure concerns to the framework. - Further more, to minimize the application footprint, RedisMessageListenerContainer performs allows one connection and one thread + Furthermore, to minimize the application footprint, RedisMessageListenerContainer allows one connection and one thread to be shared by multiple listeners even though they do not share a subscription. Thus no matter how many listeners or channels an application tracks, the runtime cost will remain the same through out its lifetime. Moreover, the container allows runtime configuration changes so one can add or remove listeners while an application is running without the need for restart. Additionally, the container uses a lazy subscription approach, using a diff --git a/docs/src/reference/docbook/reference/redis-transactions.xml b/docs/src/reference/docbook/reference/redis-transactions.xml new file mode 100644 index 000000000..4f29e2f9b --- /dev/null +++ b/docs/src/reference/docbook/reference/redis-transactions.xml @@ -0,0 +1,22 @@ + +
+ Redis Transactions + Redis provides support for transactions through the multi, + exec, and discard commands. These operations are available on RedisTemplate, + however RedisTemplate is not guaranteed to execute all operations in the transaction using the same connection. + + + Spring Data Redis provides the SessionCallback interface for use when multiple operations need to be performed with the same connection, + as when using Redis transactions. For example: + + + () { + public Object execute(RedisOperations operations) throws DataAccessException { + operations.multi(); + operations.opsForValue().set("key", "value"); + List results = operations.exec(); + return null; + } +});]]> + \ No newline at end of file diff --git a/docs/src/reference/docbook/reference/redis.xml b/docs/src/reference/docbook/reference/redis.xml index ca2602022..f9f7554d9 100644 --- a/docs/src/reference/docbook/reference/redis.xml +++ b/docs/src/reference/docbook/reference/redis.xml @@ -10,18 +10,18 @@ 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 Redis 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. + Spring Data Redis provides easy configuration and access to Redis from Spring applications. It offers both low-level and + high-level abstractions for interacting with the store, freeing the user from infrastructural concerns.
Redis Requirements - Spring Redis requires Redis 2.0 or above and Java SE 5.0 or above . + Spring Redis requires Redis 2.2 or above and Java SE 6.0 or above . In terms of language bindings (or connectors), Spring Redis integrates with Jedis, JRedis, RJC, SRP and Lettuce, five 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. + If you are aware of any other connector that we should be integrating with, please send us feedback.
@@ -32,8 +32,8 @@ 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 + High-Level Abstractions - providing generified, user friendly template classes for interacting with Redis. + explains the abstraction built 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 or Spring 3.1 cache implementation backed by @@ -48,10 +48,10 @@ 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. - No matter the library one chooses, there only one set of Spring Redis API that one needs to use that behaves consistently + No matter the library one chooses, there is only one set of Spring Data Redis API that one needs to use that behaves consistently across all connectors, namely the org.springframework.data.redis.connection package and its - RedisConnection and RedisConnectionFactory interfaces for working respectively for retrieving active - connection to Redis. + RedisConnection and RedisConnectionFactory interfaces for working with and retrieving active + connections to Redis.
<interfacename>RedisConnection</interfacename> and <interfacename>RedisConnectionFactory</interfacename> @@ -64,12 +64,12 @@ 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 + Active RedisConnections are created through RedisConnectionFactory. In addition, the factories act as + PersistenceExceptionTranslators, meaning once declared, they allow one to do transparent exception translation. For example, exception translation 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). + Depending on the underlying configuration, the factory can return a new connection or an existing connection (in case a pool or shared native connection is used).
The easiest way to work with a RedisConnectionFactory is to configure the appropriate connector through the IoC container and @@ -78,8 +78,7 @@ 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 + Unfortunately, currently, not all connectors support all Redis features. 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. @@ -88,8 +87,8 @@
Configuring Jedis connector - Jedis is one of the connectors supported by the Key Value module through the - org.springframework.data.redis.connection.jedis package. In its simples form, the Jedis configuration looks as follow: + Jedis is one of the connectors supported by the Spring Data Redis module through the + org.springframework.data.redis.connection.jedis package. In its simplest form, the Jedis configuration looks as follow: Configuring JRedis connector - JRedis is another popular, open-source connector supported by Spring Redis through the + JRedis is another popular, open-source connector supported by Spring Data Redis through the org.springframework.data.redis.connection.jredis package. - Since JRedis itself does not support (yet) Redis 2.x commands, Spring Redis uses an updated fork available + Since JRedis itself did not support Redis 2.x commands at the time of SDR's first release, Spring Data Redis uses a fork available here. A typical JRedis configuration can looks like this: @@ -151,10 +150,10 @@
Configuring RJC connector - RJC is the third, open-source connector supported by Spring Redis through the + RJC is the third, open-source connector supported by Spring Data Redis through the org.springframework.data.redis.connection.rjc package. - Similar to the other connectors, a typical RJC configuration can looks like this: + Similar to the other connectors, a typical RJC configuration can look like this: Configuring SRP connector SRP (an acronym for Sam's Redis Protocol) is the forth, open-source connector supported by - Spring Redis through the org.springframework.data.redis.connection.srp package. + Spring Data Redis through the org.springframework.data.redis.connection.srp package. By now, its configuration is probably easy to guess: @@ -203,8 +202,8 @@
Configuring Lettuce connector - Lettuce is the fifth, open-source connector supported by - Spring Redis through the org.springframework.data.redis.connection.lettuce package. + Lettuce is the fifth open-source connector supported by + Spring Data Redis through the org.springframework.data.redis.connection.lettuce package. Its configuration is probably easy to guess: @@ -229,7 +228,7 @@ Most users are likely to use RedisTemplate and its coresponding package org.springframework.data.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 + The template offers a high-level abstraction for Redis interactions. While RedisConnection offers 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) @@ -302,12 +301,12 @@ 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 + 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.redis.serializer package - see for more information. Note that the template requires all keys to be non-null - values can be null as long as the underlying serializer accepts them; read the javadoc of each serializer for more information. - For cases where a certain template view is needed, one the view as a dependency and inject the template: the container will automatically perform the conversion + For cases where a certain template view is needed, declare the view as a dependency and inject the template: the container will automatically perform the conversion eliminating the opsFor[X] calls: @@ -346,10 +345,10 @@
String-focused convenience classes - Since it's quite the keys and values stored in Redis can be java.lang.String, the Redis modules provides two extensions to RedisConnection - and RedisTemplate respectively the StringRedisConnection (and its DefaultStringRedisConnection implementation) + Since it's quite common for the keys and values stored in Redis to be java.lang.String, the Redis modules provides two extensions to RedisConnection + and RedisTemplate, respectively the StringRedisConnection (and its DefaultStringRedisConnection implementation) and StringRedisTemplate as a convenient one-stop solution - for intensive String operations. In addition to be bound to String keys, the template and the connection use the + for intensive String operations. In addition to being bound to String keys, the template and the connection use 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: @@ -401,7 +400,7 @@ From the framework perspective, the data stored in Redis are just bytes. While Redis itself supports various types, for the most part these refer to the way the data is stored rather then what it represents. It is up to the user to decide whether the information gets translated into Strings or any other objects. The conversion between the user (custom) - types and raw data (and vice-versa) is handled in Spring Redis Redis through the RedisSerializer interface + types and raw data (and vice-versa) is handled in Spring Data Redis through the RedisSerializer interface (package org.springframework.data.redis.serializer) which as the name implies, takes care of the serialization process. Multiple implementations are available out of the box, two of which have been already mentioned before in this documentation: the StringRedisSerializer and the JdkSerializationRedisSerializer. However one can use OxmSerializer for Object/XML mapping through Spring 3 @@ -412,6 +411,8 @@ + +
Support Classes @@ -433,7 +434,7 @@ http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> - +