From 632895d153d40c83be32652fd6ffcb2248b04638 Mon Sep 17 00:00:00 2001 From: Oleg Zhurakousky Date: Thu, 25 Aug 2011 15:47:27 -0400 Subject: [PATCH 1/2] INT-2079 added initial documentation for Redis module --- docs/src/reference/docbook/index.xml | 3 +- docs/src/reference/docbook/redis.xml | 204 +++++++++++++++++++++++++++ 2 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 docs/src/reference/docbook/redis.xml diff --git a/docs/src/reference/docbook/index.xml b/docs/src/reference/docbook/index.xml index 2b678aa1c0..61e54ad8c8 100644 --- a/docs/src/reference/docbook/index.xml +++ b/docs/src/reference/docbook/index.xml @@ -127,7 +127,8 @@ - + + diff --git a/docs/src/reference/docbook/redis.xml b/docs/src/reference/docbook/redis.xml new file mode 100644 index 0000000000..d9159b0516 --- /dev/null +++ b/docs/src/reference/docbook/redis.xml @@ -0,0 +1,204 @@ + + + Redis Support + + Since version 2.1 Spring Integration introduces support for Redis database - "an open source advanced key-value store" + This support comes in the form of Redis-based MessageStore as well implementation of Publish-Subscribe Messaging paradigm + supported by Redis via SUBSCRIBE, UNSUBSCRIBE and PUBLISH commands. + +
+ Introduction + + To download, install and run Redis please refer to Redis documentation + +
+ +
+ Connecting to Redis + + To begin interacting with Redis you first need to connect to it. Spring Integration uses support provided by another Spring project - + Spring Data Redis which uses an all familiar Spring's ConnectionFactory and Template + abstraction to simplify integration with several Redis-client Java APIs. Currently Spring-Data-Redis supports + jedis, jredis and rjc + + RedisConnectionFactory + + + To connect to Redis you would use one of the implementations of RedisConnectionFactory interface + + + + + Example below shows how to create JedisConnectionFactory + + In Java: + + + + Or as Spring configuration:: + + +]]> + + + + As you can see implementations of RedisConnectionFactory provide a set of properties such as port, host etc., that could be set if needed. + Once an instance of RedisConnectionFactory is created all you need is create an instance of RedisTemplate injecting it with RedisConnectionFactory. + + + RedisTemplate + + + Similar to other template classes in Spring (e.g., JdbcTemplate, JmsTemplate) RedisTemplate is a helper class that simplifies Redis data access code. + For more information about RedisTemplate and its variations (e.g., StringRedisTemplate) please refer to + Spring-Data-Redis documentation + + + The code below shows how to create an instance of RedisTemplate: + + + In Java: + (); +rt.setConnectionFactory(redisConnectionFactory);]]> + + + Or as Spring configuration:: + + +]]> + +
+ +
+ Messaging with Redis + + As mentioned in introduction Redis provides support for Publish-Subscribe messaging paradigm via SUBSCRIBE, UNSUBSCRIBE and PUBLISH + commands and similar to JMS and AMQP Spring Integration provides Messaging Channels and adapters for sending and receiving messages via Redis. + + +
+ Redis Publish/Subscribe channel + + + Similar to the JMS there are cases where both the producer and consumer are intended to be part of the same application, running + within the same process. This could be accomplished by using a pair of inbound and outbound Channel Adapters, + however just like with JMS there is a simpler approach to address this use case. + + ]]> + + + The publish-subscribe-channel (above) will behave much like a normal <publish-subscribe-channel/> element from the main Spring Integration namespace. + It can be referenced by both input-channel and output-channel attributes of any endpoint. The difference is that this channel is backed by a + Redis topic name - a String value described in topic-name element. However unlike JMS this topic doesn't have to be created in advance or even auto-created by + Redis. In Redis topics are simple String values that could be looked at as an address and all the producer and consumer have to do to communicate is use the same String value for topic name. + A simple subscription to this channel means that asynchronous pub-sub messaging is possible between the producing and consuming endpoints, but unlike the simpler asynchronous Message Channels + created by adding a <queue/> sub-element within a non-JMS <channel/> element, the Messages are not just stored in an in-memory queue. Instead those Messages are + passed through Redis allowing you to rely on Redis persistence support, clustering as well as interoperability with other non-java platforms. + +
+ +
+ Redis Inbound Channel Adapter + + Redis-based Inbound Channel Adapter adapts incoming Redis messages into Spring Integration Messages by doing the same thing as other inbound adapters + do which is receiving a platform-specific message (Redis in this case) and converting it to Spring Integration Message using MessageConverter strategy. + + + + + + + +]]> + + + Above is a simple but complete configuration of Redis Inbound Channel Adapter. Note that the above configuration relies on the + familiar Spring paradigm of auto-discovering certain beans. In this case its redisConnectionFactory which is implicitly injected into the adapter. + You can of course specify it explicitly using connection-factory attribute. + + + + Also, note that above configuration injects the adapter with custom MessageConverter. The approach is similar to JMS where MessageConverters are used to convert between + Redis Messages and the Spring Integration Message payloads. Default is a SimpleMessageConverter. + + + Inbound adapters can subscribe to multiple topic names hence the coma-delimited set of values in the topics attribute. +
+ +
+ Redis Outbound Channel Adapter + + Redis-based Outbound Channel Adapter adapts outgoing Spring Integration messages into Redis messages by doing the same thing as + other outbound adapters do which is receiving Spring Integration messages and converting it to platform-specific message (Redis in this case) using MessageConverter strategy. + + + + + + + + +]]> + + + As you can see the configuration is similar to Redis Inbound Channel Adapter. The adapter implicitly injected with RedisConnectionFactory + as redisConnectionFactory bean as well as MessageConverter as testConverter. + +
+
+ + +
+ Redis Message Store + + + As described in the EIP MessageStore allows you to persist Messages which can be very useful when dealing + with components that have capability to buffer messages (QueueChannel, Aggregator, Resequencer) if reliability is a concern as well as patterns such as + ClaimCheck + + + + Spring Integration Redis module provides RedisMessageStore which is the implementation of both MessageStore strategy + (mainly used by QueueChannel and ClaimCheck patterns) as well as MessageGroupStore strategy + (mainly used by Aggregator and Resequencer patterns) + + + + + + + + + + + +]]> + + + Above is a sample RedisMessageStore configuration as well as its usage (QueueChannel and Aggregator). As you can see it is a simple + bean configuration injected with RedisConnectionFactory via constructor. + + + By default RedisMessageStore will use Java serialization to serialize the Message, however if you want to use different serialization technique (e.g., JSON) + you can provide your own serializer via valueSerializer property of RedisMessageStore. +
+ + \ No newline at end of file From 90f23842a3030ec8c0ec2dbe72d1c0d9d00bdb20 Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Wed, 31 Aug 2011 11:49:34 -0400 Subject: [PATCH 2/2] polishing --- docs/src/reference/docbook/index.xml | 20 +-- docs/src/reference/docbook/redis.xml | 181 +++++++++++++++------------ 2 files changed, 110 insertions(+), 91 deletions(-) diff --git a/docs/src/reference/docbook/index.xml b/docs/src/reference/docbook/index.xml index 61e54ad8c8..9306eb97b0 100644 --- a/docs/src/reference/docbook/index.xml +++ b/docs/src/reference/docbook/index.xml @@ -118,26 +118,26 @@ by Spring Integration to support Message-based communication with external systems. + + - - + - - + + + - + - - - - - + + + Appendices diff --git a/docs/src/reference/docbook/redis.xml b/docs/src/reference/docbook/redis.xml index d9159b0516..b6508e8b72 100644 --- a/docs/src/reference/docbook/redis.xml +++ b/docs/src/reference/docbook/redis.xml @@ -1,31 +1,36 @@ + Redis Support + - Since version 2.1 Spring Integration introduces support for Redis database - "an open source advanced key-value store" - This support comes in the form of Redis-based MessageStore as well implementation of Publish-Subscribe Messaging paradigm - supported by Redis via SUBSCRIBE, UNSUBSCRIBE and PUBLISH commands. + Since version 2.1 Spring Integration introduces support for Redis: + "an open source advanced key-value store". + This support comes in the form of a Redis-based MessageStore as well as Publish-Subscribe Messaging adapters that + are supported by Redis via its PUBLISH, SUBSCRIBE and UNSUBSCRIBE commands. +
Introduction - To download, install and run Redis please refer to Redis documentation + To download, install and run Redis please refer to the Redis documentation.
- +
Connecting to Redis - To begin interacting with Redis you first need to connect to it. Spring Integration uses support provided by another Spring project - - Spring Data Redis which uses an all familiar Spring's ConnectionFactory and Template - abstraction to simplify integration with several Redis-client Java APIs. Currently Spring-Data-Redis supports + To begin interacting with Redis you first need to connect to it. Spring Integration uses support provided by another Spring project, + Spring Data Redis, which provides typical Spring constructs: + ConnectionFactory and Template. Those abstractions + simplify integration with several Redis-client Java APIs. Currently Spring-Data-Redis supports jedis, jredis and rjc - + RedisConnectionFactory - + - To connect to Redis you would use one of the implementations of RedisConnectionFactory interface + To connect to Redis you would use one of the implementations of the RedisConnectionFactory interface: - Example below shows how to create JedisConnectionFactory + The example below shows how to create a JedisConnectionFactory. In Java: - Or as Spring configuration:: + Or in Spring's XML configuration: ]]> - As you can see implementations of RedisConnectionFactory provide a set of properties such as port, host etc., that could be set if needed. - Once an instance of RedisConnectionFactory is created all you need is create an instance of RedisTemplate injecting it with RedisConnectionFactory. + The implementations of RedisConnectionFactory provide a set of properties such as port and host that can be set if needed. + Once an instance of RedisConnectionFactory is created, you can create an instance of RedisTemplate and inject it with the RedisConnectionFactory. - - RedisTemplate + + RedisTemplate - - Similar to other template classes in Spring (e.g., JdbcTemplate, JmsTemplate) RedisTemplate is a helper class that simplifies Redis data access code. - For more information about RedisTemplate and its variations (e.g., StringRedisTemplate) please refer to - Spring-Data-Redis documentation - - - The code below shows how to create an instance of RedisTemplate: - - + + As with other template classes in Spring (e.g., JdbcTemplate, JmsTemplate) + RedisTemplate is a helper class that simplifies Redis data access code. + For more information about RedisTemplate and its variations (e.g., StringRedisTemplate) + please refer to the Spring-Data-Redis documentation + + + The code below shows how to create an instance of RedisTemplate: + In Java: (); rt.setConnectionFactory(redisConnectionFactory);]]> - Or as Spring configuration:: + Or in Spring's XML configuration:: ]]> @@ -81,38 +86,43 @@ rt.setConnectionFactory(redisConnectionFactory);]]>
Messaging with Redis + - As mentioned in introduction Redis provides support for Publish-Subscribe messaging paradigm via SUBSCRIBE, UNSUBSCRIBE and PUBLISH - commands and similar to JMS and AMQP Spring Integration provides Messaging Channels and adapters for sending and receiving messages via Redis. + As mentioned in the introduction Redis provides support for Publish-Subscribe messaging via its PUBLISH, SUBSCRIBE and UNSUBSCRIBE + commands. As with JMS and AMQP, Spring Integration provides Message Channels and adapters for sending and receiving messages via Redis. - +
Redis Publish/Subscribe channel - + Similar to the JMS there are cases where both the producer and consumer are intended to be part of the same application, running within the same process. This could be accomplished by using a pair of inbound and outbound Channel Adapters, - however just like with JMS there is a simpler approach to address this use case. - + however just like with Spring Integration's JMS support, there is a simpler approach to address this use case. ]]> + - The publish-subscribe-channel (above) will behave much like a normal <publish-subscribe-channel/> element from the main Spring Integration namespace. - It can be referenced by both input-channel and output-channel attributes of any endpoint. The difference is that this channel is backed by a - Redis topic name - a String value described in topic-name element. However unlike JMS this topic doesn't have to be created in advance or even auto-created by - Redis. In Redis topics are simple String values that could be looked at as an address and all the producer and consumer have to do to communicate is use the same String value for topic name. - A simple subscription to this channel means that asynchronous pub-sub messaging is possible between the producing and consuming endpoints, but unlike the simpler asynchronous Message Channels - created by adding a <queue/> sub-element within a non-JMS <channel/> element, the Messages are not just stored in an in-memory queue. Instead those Messages are - passed through Redis allowing you to rely on Redis persistence support, clustering as well as interoperability with other non-java platforms. + The publish-subscribe-channel (above) will behave much like a normal <publish-subscribe-channel/> element from the + main Spring Integration namespace. It can be referenced by both input-channel and output-channel attributes of + any endpoint. The difference is that this channel is backed by a Redis topic name - a String value specified by the topic-name + attribute. However unlike JMS this topic doesn't have to be created in advance or even auto-created by Redis. In Redis topics are simple + String values that play the role of an address, and all the producer and consumer need to do to communicate is use the same String value + as their topic name. A simple subscription to this channel means that asynchronous pub-sub messaging is possible between the producing and + consuming endpoints, but unlike the asynchronous Message Channels created by adding a <queue/> sub-element within + a simple Spring Integration <channel/> element, the Messages are not just stored in an in-memory queue. Instead those + Messages are passed through Redis allowing you to rely on its support for persistence and clustering as well as its interoperability with + other non-java platforms.
- +
Redis Inbound Channel Adapter - Redis-based Inbound Channel Adapter adapts incoming Redis messages into Spring Integration Messages by doing the same thing as other inbound adapters - do which is receiving a platform-specific message (Redis in this case) and converting it to Spring Integration Message using MessageConverter strategy. - + The Redis-based Inbound Channel Adapter adapts incoming Redis messages into Spring Integration Messages in the same way as other + inbound adapters. It receives platform-specific messages (Redis in this case) and converts them to Spring Integration Messages using + a MessageConverter strategy. + message-converter="testConverter" /> - + ]]> + - Above is a simple but complete configuration of Redis Inbound Channel Adapter. Note that the above configuration relies on the - familiar Spring paradigm of auto-discovering certain beans. In this case its redisConnectionFactory which is implicitly injected into the adapter. - You can of course specify it explicitly using connection-factory attribute. + Above is a simple but complete configuration of a Redis Inbound Channel Adapter. Note that the above configuration relies on the + familiar Spring paradigm of auto-discovering certain beans. In this case the redisConnectionFactory is implicitly + injected into the adapter. You can of course specify it explicitly using the connection-factory attribute instead. - + - Also, note that above configuration injects the adapter with custom MessageConverter. The approach is similar to JMS where MessageConverters are used to convert between - Redis Messages and the Spring Integration Message payloads. Default is a SimpleMessageConverter. + Also, note that the above configuration injects the adapter with a custom MessageConverter. + The approach is similar to JMS where MessageConverters are used to convert between + Redis Messages and the Spring Integration Message payloads. The default is a SimpleMessageConverter. - - Inbound adapters can subscribe to multiple topic names hence the coma-delimited set of values in the topics attribute. + + Inbound adapters can subscribe to multiple topic names hence the comma-delimited set of values in the + topics attribute.
- -
+ +
Redis Outbound Channel Adapter - Redis-based Outbound Channel Adapter adapts outgoing Spring Integration messages into Redis messages by doing the same thing as - other outbound adapters do which is receiving Spring Integration messages and converting it to platform-specific message (Redis in this case) using MessageConverter strategy. + The Redis-based Outbound Channel Adapter adapts outgoing Spring Integration messages into Redis messages in the same way as + other outbound adapters. It receives Spring Integration messages and converts them to platform-specific messages (Redis in this case) + using a MessageConverter strategy. - - @@ -158,31 +171,33 @@ rt.setConnectionFactory(redisConnectionFactory);]]> ]]> - As you can see the configuration is similar to Redis Inbound Channel Adapter. The adapter implicitly injected with RedisConnectionFactory - as redisConnectionFactory bean as well as MessageConverter as testConverter. + As you can see the configuration is similar to the Redis Inbound Channel Adapter. The adapter is implicitly injected with + a RedisConnectionFactory which was defined with 'redisConnectionFactory' as its bean name. + This example also includes the optional, custom MessageConverter (the 'testConverter' bean).
- - +
Redis Message Store - As described in the EIP MessageStore allows you to persist Messages which can be very useful when dealing - with components that have capability to buffer messages (QueueChannel, Aggregator, Resequencer) if reliability is a concern as well as patterns such as - ClaimCheck + As described in EIP, a Message Store allows you to persist Messages. + This can be very useful when dealing with components that have a capability to buffer messages + (QueueChannel, Aggregator, Resequencer, etc.) if reliability is a concern. + In Spring Integration, the MessageStore strategy also provides the foundation for the + ClaimCheck pattern, described in EIP as well. - + - Spring Integration Redis module provides RedisMessageStore which is the implementation of both MessageStore strategy - (mainly used by QueueChannel and ClaimCheck patterns) as well as MessageGroupStore strategy - (mainly used by Aggregator and Resequencer patterns) - - + Spring Integration's Redis module provides the RedisMessageStore which is an implementation of both the + MessageStore strategy (mainly used by the QueueChannel and ClaimCheck patterns) and + the MessageGroupStore strategy (mainly used by Aggregator and Resequencer patterns). + + - + @@ -191,14 +206,18 @@ rt.setConnectionFactory(redisConnectionFactory);]]> ]]> - - - Above is a sample RedisMessageStore configuration as well as its usage (QueueChannel and Aggregator). As you can see it is a simple - bean configuration injected with RedisConnectionFactory via constructor. - - - By default RedisMessageStore will use Java serialization to serialize the Message, however if you want to use different serialization technique (e.g., JSON) - you can provide your own serializer via valueSerializer property of RedisMessageStore. + + + + Above is a sample RedisMessageStore configuration that shows its usage by a QueueChannel + and an Aggregator. As you can see it is a simple bean configuration, and it expects a + RedisConnectionFactory as a constructor argument. + + + By default the RedisMessageStore will use Java serialization to serialize the Message. + However if you want to use a different serialization technique (e.g., JSON), you can provide your own serializer via + the valueSerializer property of the RedisMessageStore. +
\ No newline at end of file