DATAREDIS-425 - Add JSR-310 support, CDI extension and Update reference documentation.

We ship converters for JSR-310 types (LocalDate/Time, ZonedDateTime, Period, Duration and ZoneId) to map between UTF-8-encoded byte[] and JDK 8 date/time types.

We also export Redis Repositories in a CDI environment. Repositories can be injected using @Inject. The CDI extension requires at least RedisOperations to be provided. Other beans like RedisKeyValueAdapter and RedisKeyValueTemplate can be provided by the user. If no RedisKeyValueAdapter/RedisKeyValueTemplate beans are found, the CDI extension creates own managed instances.

Original Pull Request: #156

Author: mp911de

.travis.yml

@@ -1,6 +1,5 @@
 language: java
 jdk:
-  - oraclejdk7
   - oraclejdk8
 env:
   matrix:

pom.xml

@@ -152,6 +152,36 @@
 			<optional>true</optional>
 		</dependency>
 
+		<!-- CDI -->
+		<dependency>
+			<groupId>javax.enterprise</groupId>
+			<artifactId>cdi-api</artifactId>
+			<version>${cdi}</version>
+			<scope>provided</scope>
+			<optional>true</optional>
+		</dependency>
+
+		<dependency>
+			<groupId>javax.el</groupId>
+			<artifactId>el-api</artifactId>
+			<version>${cdi}</version>
+			<scope>test</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>org.apache.openwebbeans.test</groupId>
+			<artifactId>cditest-owb</artifactId>
+			<version>${webbeans}</version>
+			<scope>test</scope>
+		</dependency>
+
+		<dependency>
+			<groupId>javax.servlet</groupId>
+			<artifactId>servlet-api</artifactId>
+			<version>2.5</version>
+			<scope>test</scope>
+		</dependency>
+
 		<!-- Test -->
 
 		<dependency>

src/main/asciidoc/reference/redis-repositories.adoc

@@ -14,7 +14,7 @@ To access domain entities stored in a Redis you can leverage repository support
 ====
 [source,java]
 ----
-@RedisHash("persons");
+@RedisHash("persons")
 public class Person {
 
   @Id String id;
@@ -158,7 +158,7 @@ of Complex Type
 addresses.[work].city  = "...
 |===
 
-Mapping behavior can be customized by registering the according `Converter` in `CustomConversions`. Those converters can take care of converting from/to a single `byte[]` as well as `Map<String,byte[]>` whereas the first one is suitable for eg. converting one complex type to eg. a binary JSON representation that still uses the default mappings hash structure, whereas the second options offers full control over the resulting hash.
+Mapping behavior can be customized by registering the according `Converter` in `CustomConversions`. Those converters can take care of converting from/to a single `byte[]` as well as `Map<String,byte[]>` whereas the first one is suitable for eg. converting one complex type to eg. a binary JSON representation that still uses the default mappings hash structure. The second option offers full control over the resulting hash. Writing objects to a Redis hash will delete the content from the hash and re-create the whole hash, so not mapped data will be lost.
 
 .Sample byte[] Converters
 ====
@@ -308,15 +308,15 @@ public class ApplicationConfig {
 
 [[redis.repositories.indexes]]
 == Secondary Indexes
-http://redis.io/topics/indexes[Secondary indexes] are used to enable lookup operations based on native redis structures. Values are written to the according indexes on every save and are removed when objects are deleted or <<redis.repositories.expirations,expire>>.
+http://redis.io/topics/indexes[Secondary indexes] are used to enable lookup operations based on native Redis structures. Values are written to the according indexes on every save and are removed when objects are deleted or <<redis.repositories.expirations,expire>>.
 
 Given the sample `Person` entity we can create an index for _firstname_ by annotating the property with `@Indexed`. 
 
 .Annotation driven indexing
 ====
 [source,java]
 ----
-@RedisHash("persons");
+@RedisHash("persons")
 public class Person {
 
   @Id String id;
@@ -351,7 +351,7 @@ Further more the programmatic setup allows to define indexes on map keys and lis
 ====
 [source,java]
 ----
-@RedisHash("persons");
+@RedisHash("persons")
 public class Person {
 
   // ... other properties omitted
@@ -457,16 +457,19 @@ public class TimeToLiveOnMethod {
 The repository implementation ensures subscription to http://redis.io/topics/notifications[Redis keyspace notifications] via `RedisMessageListenerContainer`.
 
 When the expiration is set to a positive value the according `EXPIRE` command is executed. 
-Additionally to persisting the original, a _phantom_ copy is persisted in Redis and set to expire 5 minutes after the original one. This done to enable the Repository support to publish `RedisKeyExpiredEvent` holding the expired value via Springs `ApplicationEventPublisher` whenever a key expires even though the original values have already been gone.
+Additionally to persisting the original, a _phantom_ copy is persisted in Redis and set to expire 5 minutes after the original one. This is done to enable the Repository support to publish `RedisKeyExpiredEvent` holding the expired value via Springs `ApplicationEventPublisher` whenever a key expires even though the original values have already been gone. Expiry events
+will be received on all connected applications using Spring Data Redis repositories.
 
 The `RedisKeyExpiredEvent` will hold a copy of the actually expired domain object as well as the key. 
 
-NOTE: The keyspace notification message listener will alter `notify-keyspace-events` settings in Redis if those are not already set. Existing settings will not be overridden so it is left to the user to set those up correctly when not leaving them empty.
+NOTE: The keyspace notification message listener will alter `notify-keyspace-events` settings in Redis if those are not already set. Existing settings will not be overridden, so it is left to the user to set those up correctly when not leaving them empty.
+
+NOTE: Redis Pub/Sub messages are not persistent. If a key expires while the application is down the expiry event will not be processed which may lead to secondary indexes containing still references to the expired object.
 
 [[redis.repositories.references]]
 == Persisting References
-Marking properties with `@Reference` allows to store a simple key reference instead of copying the all values into the hash itself.
-On loading from Redis references are resolved automatically and mapped back into the object.
+Marking properties with `@Reference` allows storing a simple key reference instead of copying values into the hash itself.
+On loading from Redis, references are resolved automatically and mapped back into the object.
 
 .Sample Property Reference
 ====
@@ -499,9 +502,12 @@ public interface PersonRepository extends CrudRepository<Person, String> {
 ----
 ====
 
+
 NOTE: Please make sure properties used in finder methods are set up for indexing.
 
-Using derived finder methods might not always be sufficient to model the queries to execute. `RedisCallback` offers more control over the actual matching of index structures or even customly added ones. All it takes is providing a `RedisCallback` that returns a single or `Iterable` set of _id_ values. 
+NOTE: Query methods for Redis repositories support only queries for entities and collections of entities with paging.
+
+Using derived query methods might not always be sufficient to model the queries to execute. `RedisCallback` offers more control over the actual matching of index structures or even custom added ones. All it takes is providing a `RedisCallback` that returns a single or `Iterable` set of _id_ values.
 
 .Sample finder using RedisCallback
 ====
@@ -518,6 +524,81 @@ List<RedisSession> sessionsByUser = template.find(new RedisCallback<Set<byte[]>>
 ----
 ====
 
+Here's an overview of the keywords supported for Redis and what a method containing that keyword essentially translates to.
+====
+
+.Supported keywords inside method names
+[options = "header, autowidth"]
+|===============
+|Keyword|Sample|Redis snippet
+|`And`|`findByLastnameAndFirstname`|`SINTER …:firstname:rand …:lastname:al’thor`
+|`Or`|`findByLastnameOrFirstname`|`SUNION …:firstname:rand …:lastname:al’thor`
+|`Is,Equals`|`findByFirstname`,`findByFirstnameIs`,`findByFirstnameEquals`|`SINTER …:firstname:rand`
+|===============
+====
+
+[[redis.misc.cdi-integration]]
+== CDI integration
+
+Instances of the repository interfaces are usually created by a container, which Spring is the most natural choice when working with Spring Data. There's sophisticated support to easily set up Spring to create bean instances. Spring Data Redis ships with a custom CDI extension that allows using the repository abstraction in CDI environments. The extension is part of the JAR so all you need to do to activate it is dropping the Spring Data Redis JAR into your classpath.
+
+You can now set up the infrastructure by implementing a CDI Producer for the `RedisConnectionFactory` and `RedisOperations`:
+
+[source, java]
+----
+class RedisOperationsProducer {
+
+
+  @Produces
+  RedisConnectionFactory redisConnectionFactory() {
+
+    JedisConnectionFactory jedisConnectionFactory = new JedisConnectionFactory();
+    jedisConnectionFactory.setHostName("localhost");
+    jedisConnectionFactory.setPort(6379);
+    jedisConnectionFactory.afterPropertiesSet();
+
+    return jedisConnectionFactory;
+  }
+
+  void disposeRedisConnectionFactory(@Disposes RedisConnectionFactory redisConnectionFactory) throws Exception {
+
+    if (redisConnectionFactory instanceof DisposableBean) {
+      ((DisposableBean) redisConnectionFactory).destroy();
+    }
+  }
+
+  @Produces
+  @ApplicationScoped
+  RedisOperations<byte[], byte[]> redisOperationsProducer(RedisConnectionFactory redisConnectionFactory) {
+
+    RedisTemplate<byte[], byte[]> template = new RedisTemplate<byte[], byte[]>();
+    template.setConnectionFactory(redisConnectionFactory);
+    template.afterPropertiesSet();
+
+    return template;
+  }
+
+}
+----
+
+The necessary setup can vary depending on the JavaEE environment you run in.
+
+The Spring Data Redis CDI extension will pick up all Repositories available as CDI beans and create a proxy for a Spring Data repository whenever a bean of a repository type is requested by the container. Thus obtaining an instance of a Spring Data repository is a matter of declaring an `@Injected` property:
+
+[source, java]
+----
+class RepositoryClient {
+
+  @Inject
+  PersonRepository repository;
+
+  public void businessMethod() {
+    List<Person> people = repository.findAll();
+  }
+}
+----
+
+A Redis Repository requires `RedisKeyValueAdapter` and `RedisKeyValueTemplate` instances. These beans are created and managed by the Spring Data CDI extension if no provided beans are found. You can however supply your own beans to configure the specific properties of `RedisKeyValueAdapter` and `RedisKeyValueTemplate`.
 
 
 

src/main/java/org/springframework/data/redis/core/RedisKeyExpiredEvent.java

@@ -29,6 +29,11 @@
  */
 public class RedisKeyExpiredEvent<T> extends RedisKeyspaceEvent {
 
+	/**
+	 * Use {@literal UTF-8} as default charset.
+	 */
+	public static final Charset CHARSET = Charset.forName("UTF-8");
+
 	private final byte[][] args;
 	private final Object value;
 
@@ -62,7 +67,7 @@ public RedisKeyExpiredEvent(byte[] key, Object value) {
 	public String getKeyspace() {
 
 		if (args.length >= 2) {
-			return new String(args[0], Charset.forName("UTF-8"));
+			return new String(args[0], CHARSET);
 		}
 
 		return null;

src/main/java/org/springframework/data/redis/core/RedisKeyValueAdapter.java

@@ -160,6 +160,12 @@ public RedisKeyValueAdapter(RedisOperations<?, ?> redisOps, RedisConverter redis
 		initKeyExpirationListener();
 	}
 
+	/**
+	 * Default constructor.
+	 */
+	protected RedisKeyValueAdapter() {
+	}
+
 	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.data.keyvalue.core.KeyValueAdapter#put(java.io.Serializable, java.lang.Object, java.io.Serializable)

src/main/java/org/springframework/data/redis/core/RedisQueryEngine.java

@@ -66,6 +66,7 @@ public RedisQueryEngine(CriteriaAccessor<RedisOperationChain> criteriaAccessor,
 	 * (non-Javadoc)
 	 * @see org.springframework.data.keyvalue.core.QueryEngine#execute(java.lang.Object, java.lang.Object, int, int, java.io.Serializable, java.lang.Class)
 	 */
+	@Override
 	public <T> Collection<T> execute(final RedisOperationChain criteria, final Comparator<?> sort, final int offset,
 			final int rows, final Serializable keyspace, Class<T> type) {
 

src/main/java/org/springframework/data/redis/core/convert/BinaryConverters.java

@@ -45,7 +45,7 @@ private BinaryConverters() {}
 	 * @author Christoph Strobl
 	 * @since 1.7
 	 */
-	private static class StringBasedConverter {
+	static class StringBasedConverter {
 
 		byte[] fromString(String source) {
 
@@ -166,7 +166,7 @@ public T convert(byte[] source) {
 				if (value == null || value.length() == 0) {
 					return null;
 				}
-				return (T) Enum.valueOf(this.enumType, value.trim());
+				return Enum.valueOf(this.enumType, value.trim());
 			}
 		}
 	}
@@ -183,8 +183,8 @@ public <T extends Number> Converter<byte[], T> getConverter(Class<T> targetType)
 			return new BytesToNumberConverter<T>(targetType);
 		}
 
-		private static final class BytesToNumberConverter<T extends Number> extends StringBasedConverter implements
-				Converter<byte[], T> {
+		private static final class BytesToNumberConverter<T extends Number> extends StringBasedConverter
+				implements Converter<byte[], T> {
 
 			private final Class<T> targetType;
 

src/main/java/org/springframework/data/redis/core/convert/Bucket.java

@@ -98,6 +98,13 @@ public boolean isEmpty() {
 		return data.isEmpty();
 	}
 
+	/**
+	 * @return the number of key-value mappings of the {@link Bucket}.
+	 */
+	public int size() {
+		return data.size();
+	}
+
 	/**
 	 * @return never {@literal null}.
 	 */
@@ -121,6 +128,12 @@ public Map<String, byte[]> asMap() {
 		return Collections.unmodifiableMap(this.data);
 	}
 
+	/**
+	 * Extracts a bucket containing key/value pairs with the {@code prefix}.
+	 * 
+	 * @param prefix
+	 * @return
+	 */
 	public Bucket extract(String prefix) {
 
 		Bucket partial = new Bucket();

src/main/java/org/springframework/data/redis/core/convert/CustomConversions.java

@@ -103,6 +103,8 @@ public CustomConversions(List<?> converters) {
 		toRegister.add(new BinaryConverters.DateToBytesConverter());
 		toRegister.add(new BinaryConverters.BytesToDateConverter());
 
+		toRegister.addAll(Jsr310Converters.getConvertersToRegister());
+
 		for (Object c : toRegister) {
 			registerConversion(c);
 		}
@@ -161,7 +163,8 @@ public void registerConvertersIn(GenericConversionService conversionService) {
 			}
 
 			if (!added) {
-				throw new IllegalArgumentException("Given set contains element that is neither Converter nor ConverterFactory!");
+				throw new IllegalArgumentException(
+						"Given set contains element that is neither Converter nor ConverterFactory!");
 			}
 		}
 	}