DATAREDIS-425 - Update JavaDoc.

Author: christophstrobl

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

@@ -26,7 +26,13 @@
 import org.springframework.util.CollectionUtils;
 
 /**
+ * {@link IndexWriter} takes care of writing <a href="http://redis.io/topics/indexes">secondary index</a> structures to
+ * Redis. Depending on the type of {@link IndexedData} it uses eg. Sets with specific names to add actually referenced
+ * keys to. While doing so {@link IndexWriter} also keeps track of all indexes associated with the root types key, which
+ * allows to remove the root key from all indexes in case of deletion.
+ * 
  * @author Christoph Strobl
+ * @since 1.7
  */
 class IndexWriter {
 

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

@@ -26,7 +26,10 @@
 import org.springframework.data.keyvalue.annotation.KeySpace;
 
 /**
+ * {@link RedisHash} marks Objects as aggregate roots to be stored in a Redis hash.
+ * 
  * @author Christoph Strobl
+ * @since 1.7
  */
 @Persistent
 @Documented
@@ -36,13 +39,19 @@
 public @interface RedisHash {
 
 	/**
-	 * The key space aka prefix to distinguish between domain types.
+	 * The prefix to distinguish between domain types.
 	 * 
 	 * @return
+	 * @see KeySpace
 	 */
 	@KeySpace
 	String value() default "";
 
+	/**
+	 * Time before expire in seconds. Superseded by {@link TimeToLive}.
+	 * 
+	 * @return positive number when expiration should be applied.
+	 */
 	long timeToLive() default -1L;
 
 }

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

@@ -17,44 +17,79 @@
 
 import java.nio.charset.Charset;
 
+import org.springframework.context.ApplicationEvent;
 import org.springframework.data.redis.util.ByteUtils;
 
 /**
+ * {@link RedisKeyExpiredEvent} is Redis specific {@link ApplicationEvent} published when a specific key in Redis
+ * expires. It might but must not hold the expired value itself next to the key.
+ * 
  * @author Christoph Strobl
+ * @since 1.7
  */
-public class RedisKeyExpiredEvent extends RedisKeyspaceEvent {
+public class RedisKeyExpiredEvent<T> extends RedisKeyspaceEvent {
 
 	private final byte[][] args;
 	private final Object value;
 
+	/**
+	 * Creates new {@link RedisKeyExpiredEvent}.
+	 * 
+	 * @param key
+	 */
 	public RedisKeyExpiredEvent(byte[] key) {
 		this(key, null);
 	}
 
+	/**
+	 * Creates new {@link RedisKeyExpiredEvent}
+	 * 
+	 * @param key
+	 * @param value
+	 */
 	public RedisKeyExpiredEvent(byte[] key, Object value) {
 		super(key);
 
 		args = ByteUtils.split(key, ':');
 		this.value = value;
 	}
 
+	/**
+	 * Gets the keyspace in which the expiration occured.
+	 * 
+	 * @return {@literal null} if it could not be determined.
+	 */
 	public String getKeyspace() {
 
-		if (args.length == 2) {
+		if (args.length >= 2) {
 			return new String(args[0], Charset.forName("UTF-8"));
 		}
 
 		return null;
 	}
 
+	/**
+	 * Get the expired objects id;
+	 * 
+	 * @return
+	 */
 	public byte[] getId() {
 		return args.length == 2 ? args[1] : args[0];
 	}
 
+	/**
+	 * Get the expired Object
+	 * 
+	 * @return {@literal null} if not present.
+	 */
 	public Object getValue() {
 		return value;
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see java.util.EventObject#toString()
+	 */
 	@Override
 	public String toString() {
 		return "RedisKeyExpiredEvent [keyspace=" + getKeyspace() + ", id=" + getId() + "]";

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

@@ -36,10 +36,12 @@
 import org.springframework.data.keyvalue.core.KeyValueAdapter;
 import org.springframework.data.keyvalue.core.mapping.KeyValuePersistentProperty;
 import org.springframework.data.redis.connection.Message;
+import org.springframework.data.redis.connection.MessageListener;
 import org.springframework.data.redis.connection.RedisConnection;
 import org.springframework.data.redis.connection.RedisConnectionFactory;
 import org.springframework.data.redis.core.convert.CustomConversions;
 import org.springframework.data.redis.core.convert.IndexResolverImpl;
+import org.springframework.data.redis.core.convert.KeyspaceConfiguration;
 import org.springframework.data.redis.core.convert.MappingRedisConverter;
 import org.springframework.data.redis.core.convert.RedisConverter;
 import org.springframework.data.redis.core.convert.RedisData;
@@ -52,9 +54,37 @@
 import org.springframework.util.Assert;
 
 /**
- * Redis specific {@link KeyValueAdapter} implementation. Uses binary codec to read/write data from/to Redis.
+ * Redis specific {@link KeyValueAdapter} implementation. Uses binary codec to read/write data from/to Redis. Objects
+ * are stored in a Redis Hash using the value of {@link RedisHash}, the {@link KeyspaceConfiguration} or just
+ * {@link Class#getName()} as a prefix. <br />
+ * <strong>Example</strong>
+ * 
+ * <pre>
+ * <code>
+ * &#64;RedisHash("persons")
+ * class Person {
+ *   &#64;Id String id;
+ *   String name;
+ * }
+ * 
+ * 
+ *         prefix              ID
+ *           |                 |
+ *           V                 V
+ * hgetall persons:5d67b7e1-8640-4475-beeb-c666fab4c0e5
+ * 1) id
+ * 2) 5d67b7e1-8640-4475-beeb-c666fab4c0e5
+ * 3) name
+ * 4) Rand al'Thor
+ * </code>
+ * </pre>
+ * 
+ * <br />
+ * The {@link KeyValueAdapter} is <strong>not</strong> intended to store simple types such as {@link String} values.
+ * Please use {@link RedisTemplate} for this purpose.
  * 
  * @author Christoph Strobl
+ * @since 1.7
  */
 public class RedisKeyValueAdapter extends AbstractKeyValueAdapter implements ApplicationContextAware,
 		ApplicationListener<RedisKeyspaceEvent> {
@@ -113,6 +143,8 @@ public RedisKeyValueAdapter(RedisOperations<?, ?> redisOps, RedisMappingContext
 	}
 
 	/**
+	 * Creates new {@link RedisKeyValueAdapter} with specific {@link RedisConverter}.
+	 * 
 	 * @param redisOps must not be {@literal null}.
 	 * @param mappingContext must not be {@literal null}.
 	 */
@@ -461,13 +493,25 @@ private void initKeyExpirationListener() {
 	}
 
 	/**
+	 * {@link MessageListener} implementation used to capture Redis keypspace notifications. Tries to read a previously
+	 * created phantom key {@code keyspace:id:phantom} to provide the expired object as part of the published
+	 * {@link RedisKeyExpiredEvent}.
+	 * 
 	 * @author Christoph Strobl
+	 * @since 1.7
 	 */
 	static class MappingExpirationListener extends KeyExpirationEventMessageListener {
 
 		private final RedisOperations<?, ?> ops;
 		private final RedisConverter converter;
 
+		/**
+		 * Creates new {@link MappingExpirationListener}.
+		 * 
+		 * @param listenerContainer
+		 * @param ops
+		 * @param converter
+		 */
 		public MappingExpirationListener(RedisMessageListenerContainer listenerContainer, RedisOperations<?, ?> ops,
 				RedisConverter converter) {
 
@@ -476,6 +520,10 @@ public MappingExpirationListener(RedisMessageListenerContainer listenerContainer
 			this.converter = converter;
 		}
 
+		/*
+		 * (non-Javadoc)
+		 * @see org.springframework.data.redis.listener.KeyspaceEventMessageListener#onMessage(org.springframework.data.redis.connection.Message, byte[])
+		 */
 		@Override
 		public void onMessage(Message message, byte[] pattern) {
 
@@ -525,14 +573,13 @@ private boolean isKeyExpirationMessage(Message message) {
 	 * {@link ReferenceResolver} using {@link RedisKeyValueAdapter} to read and convert referenced entities.
 	 * 
 	 * @author Christoph Strobl
+	 * @since 1.7
 	 */
 	static class ReferenceResolverImpl implements ReferenceResolver {
 
 		private RedisKeyValueAdapter adapter;
 
-		ReferenceResolverImpl() {
-
-		}
+		ReferenceResolverImpl() {}
 
 		/**
 		 * @param adapter must not be {@literal null}.

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

@@ -24,6 +24,7 @@
  * Redis specific implementation of {@link KeyValueTemplate}.
  * 
  * @author Christoph Strobl
+ * @since 1.7
  */
 public class RedisKeyValueTemplate extends KeyValueTemplate {
 
@@ -51,9 +52,14 @@ public RedisMappingContext getMappingContext() {
 	 * 
 	 * @author Christoph Strobl
 	 * @param <T>
+	 * @since 1.7
 	 */
 	public static abstract class RedisKeyValueCallback<T> implements KeyValueCallback<T> {
 
+		/*
+		 * (non-Javadoc)
+		 * @see org.springframework.data.keyvalue.core.KeyValueCallback#doInKeyValue(org.springframework.data.keyvalue.core.KeyValueAdapter)
+		 */
 		@Override
 		public T doInKeyValue(KeyValueAdapter adapter) {
 			return doInRedis((RedisKeyValueAdapter) adapter);

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

@@ -18,14 +18,26 @@
 import org.springframework.context.ApplicationEvent;
 
 /**
+ * Redis specific {@link ApplicationEvent} published when a key expires in Redis.
+ * 
  * @author Christoph Strobl
+ * @since 1.7
  */
 public class RedisKeyspaceEvent extends ApplicationEvent {
 
+	/**
+	 * Creates new {@link RedisKeyspaceEvent}.
+	 * 
+	 * @param key The key that expired. Must not be {@literal null}.
+	 */
 	public RedisKeyspaceEvent(byte[] key) {
 		super(key);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see java.util.EventObject#getSource()
+	 */
 	public byte[] getSource() {
 		return (byte[]) super.getSource();
 	}

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

@@ -17,7 +17,6 @@
 
 import java.io.Serializable;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collection;
 import java.util.Comparator;
 import java.util.LinkedHashMap;
@@ -33,23 +32,39 @@
 import org.springframework.data.redis.connection.RedisConnection;
 import org.springframework.data.redis.core.convert.RedisData;
 import org.springframework.data.redis.repository.query.RedisOperationChain;
+import org.springframework.data.redis.util.ByteUtils;
 
 /**
  * Redis specific {@link QueryEngine} implementation.
  * 
  * @author Christoph Strobl
+ * @since 1.7
  */
-public class RedisQueryEngine extends QueryEngine<RedisKeyValueAdapter, RedisOperationChain, Comparator<?>> {
+class RedisQueryEngine extends QueryEngine<RedisKeyValueAdapter, RedisOperationChain, Comparator<?>> {
 
+	/**
+	 * Creates new {@link RedisQueryEngine} with defaults.
+	 */
 	public RedisQueryEngine() {
 		this(new RedisCriteriaAccessor(), null);
 	}
 
+	/**
+	 * Creates new {@link RedisQueryEngine}.
+	 * 
+	 * @param criteriaAccessor
+	 * @param sortAccessor
+	 * @see QueryEngine#QueryEngine(CriteriaAccessor, SortAccessor)
+	 */
 	public RedisQueryEngine(CriteriaAccessor<RedisOperationChain> criteriaAccessor,
 			SortAccessor<Comparator<?>> sortAccessor) {
 		super(criteriaAccessor, sortAccessor);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.keyvalue.core.QueryEngine#execute(java.lang.Object, java.lang.Object, int, int, java.io.Serializable, java.lang.Class)
+	 */
 	public <T> Collection<T> execute(final RedisOperationChain criteria, final Comparator<?> sort, int offset, int rows,
 			final Serializable keyspace, Class<T> type) {
 
@@ -74,9 +89,7 @@ public Map<byte[], Map<byte[], byte[]>> doInRedis(RedisConnection connection) th
 
 				for (byte[] id : allKeys) {
 
-					byte[] singleKey = Arrays.copyOf(keyspaceBin, id.length + keyspaceBin.length);
-					System.arraycopy(id, 0, singleKey, keyspaceBin.length, id.length);
-
+					byte[] singleKey = ByteUtils.concat(keyspaceBin, id);
 					rawData.put(id, connection.hGetAll(singleKey));
 				}
 
@@ -103,12 +116,20 @@ public Map<byte[], Map<byte[], byte[]>> doInRedis(RedisConnection connection) th
 		return result;
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.keyvalue.core.QueryEngine#execute(java.lang.Object, java.lang.Object, int, int, java.io.Serializable)
+	 */
 	@Override
 	public Collection<?> execute(final RedisOperationChain criteria, Comparator<?> sort, int offset, int rows,
 			final Serializable keyspace) {
 		return execute(criteria, sort, offset, rows, keyspace, Object.class);
 	}
 
+	/*
+	 * (non-Javadoc)
+	 * @see org.springframework.data.keyvalue.core.QueryEngine#count(java.lang.Object, java.io.Serializable)
+	 */
 	@Override
 	public long count(final RedisOperationChain criteria, final Serializable keyspace) {
 
@@ -129,6 +150,10 @@ public Long doInRedis(RedisConnection connection) throws DataAccessException {
 		});
 	}
 
+	/**
+	 * @author Christoph Strobl
+	 * @since 1.7
+	 */
 	static class RedisCriteriaAccessor implements CriteriaAccessor<RedisOperationChain> {
 
 		@Override