Spring/spring-data-redis
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add docs on StringConnection/Template and the serializers

Browse Source
This commit is contained in:
Costin Leau
2011-02-01 20:17:45 +02:00
parent 1234372729
commit d2d59a17e5
1 changed files with 66 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
src/docbkx/reference/redis.xml
View File

@@ -4,7 +4,7 @@
<chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="redis">
<title>Redis support</title>
<para>One of the key value stores supported by SDKV is <ulink url="http://code.google.com/p/redis/">Redis</ulink>.
<para>One of the key value stores supported by SDKV is <ulink url="http://redis.io">Redis</ulink>.
To quote the project home page:
<quote>
Redis is an advanced key-value store. It is similar to memcached but the dataset is not volatile, and values can be strings,
@@ -18,8 +18,7 @@
<section id="redis:requirements">
<title>Redis Requirements</title>
<para>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.
<para>SDKV requires Redis 2.0 or above (Redis 2.2 is recommended) and Java SE 6.0 or above.
In terms of language bindings (or connectors), SDKV integrates with <ulink url="http://github.com/xetorthio/jedis">Jedis</ulink> and
<ulink url="http://github.com/alphazero/jredis">JRedis</ulink>, 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.
@@ -67,7 +66,7 @@
<para>Active <interfacename>RedisConnection</interfacename> are created through <interfacename>RedisConnectionFactory</interfacename>. In addition, the factories act as
<interfacename>PersistenceExceptionTranslator</interfacename> meaning once declared, allow one to do transparent exception translation for example through the use of the
<literal>@Repository</literal> annotation and AOP. For more information see the dedicated
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-exception-translation">section</ulink> in Spring Framework documentation.</para>
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-exception-translation">section</ulink> in Spring Framework documentation.</para>
<note>Depending on the underlying configuration, the factory can return a new connection or an existing connection (in case a pool is used).</note>
</section>
@@ -101,7 +100,7 @@
<bean id="jedisConnectionFactory" class="org.springframework.data.keyvalue.redis.connection.jedis.JedisConnectionFactory"/>
</beans>]]></programlisting>
<para>For intense use however, one might want to enable connection pooling or set a certain host or password:</para>
<para>For production use however, one might want to tweak the settings such as the host or password:</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
@@ -111,7 +110,7 @@
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="jedisConnectionFactory" class="org.springframework.data.keyvalue.redis.connection.jedis.JedisConnectionFactory"
p:host-name="server" p:port="6379" p:use-pool="true"/>
p:host-name="server" p:port="6379"/>
</beans>]]></programlisting>
</section>
@@ -134,7 +133,7 @@
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="jredisConnectionFactory" class="org.springframework.data.keyvalue.redis.connection.jredis.JredisConnectionFactory"
p:host-name="server" p:port="6379" p:use-pool="true"/>
p:host-name="server" p:port="6379"/>
</beans>]]></programlisting>
<para>As one can note, the configuration is quite similar to the Jedis one.</para>
@@ -158,7 +157,7 @@
The template offers a high-level abstraction for Redis interaction - while <interfacename>RedisConnection</interfacename> offer low level methods that accept and return
binary values (<literal>byte</literal> arrays), the template takes care of serialization and connection management, freeing the user from dealing with such details.</para>
<para>Moreover, the template provides operations views (following the grouping from Redis command <ulink url="http://code.google.com/p/redis/wiki/CommandReference">reference</ulink>)
<para>Moreover, the template provides operations views (following the grouping from Redis command <ulink url="http://redis.io/commands">reference</ulink>)
that offer rich, generified interfaces for working against a certain type or certain key (through the <interfacename>KeyBound</interfacename> interfaces) as described below:</para>
<table id="redis-template-operations-view" pgwide="1">
@@ -229,11 +228,53 @@
<para>Out of the box, <classname>RedisTemplate</classname> 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
<literal>org.springframework.data.keyvalue.redis.serializer</literal> package. Note that the template requires all keys to be non-null - values can be null as long as the underlying
<literal>org.springframework.data.keyvalue.redis.serializer</literal> package - see <xref linkend="redis:serializer"/> 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.</para>
<para>Since it's quite the keys and values stored in Redis can be <classname>java.lang.String</classname>, the Redis modules provides <classname>StringRedisTemplate</classname>,
a convenient provides a one-stop solution for intensive operations operations. In addition to be bound to <literal>String</literal> keys, the template uses the
<para>For cases where a certain template <emphasis>view</emphasis> is needed, one the view as a dependency and inject the template: the container will automatically perform the conversion
eliminating the <literal>opsFor[X]</literal> calls:</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="jedisConnectionFactory" class="org.springframework.data.keyvalue.redis.connection.jedis.JedisConnectionFactory"
p:use-pool="true"/>
<!-- redis template definition -->
<bean id="redisTemplate" class="org.springframework.data.keyvalue.redis.core.RedisTemplate"
p:connection-factory-ref="jedisConnectionFactory"/>
...
</beans>]]></programlisting>
<programlisting language="java"><![CDATA[public class Example {
// inject the actual template
@Autowired
private RedisTemplate<String, String> template;
// inject the template as ListOperations
@Autowired
private ListOperations<String, String> listOps;
public void addLink(String userId, URL url) {
listOps.leftPush(userId, url.toExternalForm());
}
}]]></programlisting>
</section>
<section id="redis:string">
<title>String-focused convenience classes</title>
<para>Since it's quite the keys and values stored in Redis can be <classname>java.lang.String</classname>, the Redis modules provides two extensions to <interfacename>RedisConnection</interfacename>
and <classname>RedisTemplate</classname> respectively the <interfacename>StringRedisConnection</interfacename> (and its <classname>DefaultStringRedisConnection</classname> implementation)
and <classname>StringRedisTemplate</classname> as a convenient one-stop solution
for intensive String operations. In addition to be bound to <literal>String</literal> keys, the template and the connection use the
<classname>StringRedisSerializer</classname> 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:
</para>
@@ -264,19 +305,6 @@
}
}]]></programlisting>
<para>For cases where a certain template <emphasis>view</emphasis> is needed, one the view as a dependency and inject the template: the container will automatically perform the conversion
eliminating the <literal>opsFor[X]</literal> calls:</para>
<programlisting language="java"><![CDATA[public class Example {
// inject the template as ListOperations
@Autowired
private ListOperations<String, String> listOps;
public void addLink(String userId, URL url) {
listOps.leftPush(userId, url.toExternalForm());
}
}]]></programlisting>
<para>As with the other Spring templates, <classname>RedisTemplate</classname> and <classname>StringRedisTemplate</classname> allow the developer to talk directly to Redis through
the <interfacename>RedisCallback</interfacename> interface: this gives complete control to the developer as it talks directly to the <interfacename>RedisConnection</interfacename>.
@@ -293,6 +321,20 @@
}]]></programlisting>
</section>
<section id="redis:serializer">
<title>Serializers</title>
<para>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 SDKV Redis through the <interfacename>RedisSerializer</interfacename> interface
(package <literal>org.springframework.data.keyvalue.redis.serializer</literal>) 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 <literal>StringRedisSerializer</literal> and
the <literal>JdkSerializationRedisSerializer</literal>. However one can use <classname>OxmSerializer</classname> for Object/XML mapping through Spring 3
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/oxm.html">OXM</ulink> support or <classname>JacksonJsonRedisSerializer</classname> for storing
data in <ulink url="http://en.wikipedia.org/wiki/JSON">JSON</ulink> format. Do note that the storage format is not limited only to values - it can be used for keys, values or hashes
without any restrictions.</para>
</section>
<xi:include href="redis-messaging.xml"/>
<section id="redis:support">