+ and yet more javadocs

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/connection/package-info.java

@@ -1,7 +1,8 @@
 /**
- * <p/>Connection package providing low-level abstractions for interacting with
- * the various Redis 'drivers'/libraries. Performs exception translation between
- * the underlying library exceptions to Spring's DAO hierarchy.
+ * Connection package providing low-level abstractions for interacting with
+ * the various Redis 'drivers'/libraries. 
+ * 
+ * <p/>Performs exception translation between the underlying library exceptions to Spring's DAO hierarchy.
  */
 package org.springframework.data.keyvalue.redis.connection;
 

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/BoundValueOperations.java

@@ -18,6 +18,8 @@ package org.springframework.data.keyvalue.redis.core;
 import java.util.concurrent.TimeUnit;
 
 /**
+ * Value (or String in Redis terminology) operations bound to a certain key. 
+ * 
  * @author Costin Leau
  */
 public interface BoundValueOperations<K, V> extends KeyBound<K> {

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/DefaultKeyBound.java

@@ -18,6 +18,7 @@ package org.springframework.data.keyvalue.redis.core;
 
 /**
  * Default {@link KeyBound} implementation.
+ * Meant for internal usage.
  * 
  * @author Costin Leau
  */

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/ListOperations.java

@@ -19,7 +19,7 @@ import java.util.List;
 import java.util.concurrent.TimeUnit;
 
 /**
- * Redis, list specific operations.
+ * Redis list specific operations.
  * 
  * @author Costin Leau
  */

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisAccessor.java

@@ -22,6 +22,9 @@ import org.springframework.data.keyvalue.redis.connection.RedisConnectionFactory
 import org.springframework.util.Assert;
 
 /**
+ * Base class for {@link RedisTemplate} defining common properties.
+ * Not intended to be used directly. 
+ * 
  * @author Costin Leau
  */
 public class RedisAccessor implements InitializingBean {
@@ -52,8 +55,4 @@ public class RedisAccessor implements InitializingBean {
 	public void setConnectionFactory(RedisConnectionFactory connectionFactory) {
 		this.connectionFactory = connectionFactory;
 	}
-
-	public RuntimeException tryToConvertRedisAccessException(Exception ex) {
-		throw new UnsupportedOperationException("wire this into dialects/XXXClient utils");
-	}
 }

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisCallback.java

@@ -19,8 +19,9 @@ import org.springframework.dao.DataAccessException;
 import org.springframework.data.keyvalue.redis.connection.RedisConnection;
 
 /**
- * Callback interface for Redis code. To be used with {@link RedisTemplate} execution methods, often as anonymous 
- * classes within a method implementation.
+ * Callback interface for Redis 'low level' code. 
+ * To be used with {@link RedisTemplate} execution methods, often as anonymous classes within a method implementation.
+ * Usually, used for chaining several operations together ({@code get/set/trim etc...}.
  * 
  * @author Costin Leau
  */
@@ -28,11 +29,11 @@ public interface RedisCallback<T> {
 
 	/**
 	 * Gets called by {@link RedisTemplate} with an active Redis connection. Does not need to care about activating or 
-	 * closing the connection or handling exceptions or transactions.
+	 * closing the connection or handling exceptions.
 	 * 
-	 * @param connection
-	 * @return
-	 * @throws Exception
+	 * @param connection active Redis connection
+	 * @return a result object or {@code null} if none
+	 * @throws DataAccessException
 	 */
 	T doInRedis(RedisConnection connection) throws DataAccessException;
 }

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisConnectionUtils.java

@@ -25,7 +25,7 @@ import org.springframework.transaction.support.TransactionSynchronizationManager
 import org.springframework.util.Assert;
 
 /**
- * Helper class featuring {@link RedisConnection} handling, allowing for reuse of instances within transactions.
+ * Helper class featuring {@link RedisConnection} handling, allowing for reuse of instances within 'transactions'/scopes.
  * 
  * @author Costin Leau
  */
@@ -33,10 +33,25 @@ public abstract class RedisConnectionUtils {
 
 	private static final Log log = LogFactory.getLog(RedisConnectionUtils.class);
 
+	/**
+	 * Gets a Redis connection from the given factory. Is aware of and will return any existing corresponding connections bound to the current thread, 
+	 * for example when using a transaction manager. Will always create a new connection otherwise.
+	 * 
+	 * @param factory connection factory for creating the connection
+	 * @return an active Redis connection
+	 */
 	public static RedisConnection getRedisConnection(RedisConnectionFactory factory) {
 		return doGetRedisConnection(factory, true);
 	}
 
+	/**
+	 * Gets a Redis connection. Is aware of and will return any existing corresponding connections bound to the current thread, 
+	 * for example when using a transaction manager. Will create a new Connection otherwise, if {@code allowCreate} is <tt>true</tt>.
+	 * 
+	 * @param factory connection factory for creating the connection
+	 * @param allowCreate whether a new (unbound) connection should be created when no connection can be found for the current thread 
+	 * @return an active Redis connection
+	 */
 	public static RedisConnection doGetRedisConnection(RedisConnectionFactory factory, boolean allowCreate) {
 		Assert.notNull(factory, "No RedisConnectionFactory specified");
 
@@ -65,6 +80,12 @@ public abstract class RedisConnectionUtils {
 		return conn;
 	}
 
+	/**
+	 * Closes the given connection, created via the given factory if not managed externally (i.e. not bound to the thread).
+	 * 
+	 * @param conn the Redis connection to close
+	 * @param factory the Redis factory that the connection was created with
+	 */
 	public static void releaseConnection(RedisConnection conn, RedisConnectionFactory factory) {
 		if (conn == null) {
 			return;
@@ -76,6 +97,13 @@ public abstract class RedisConnectionUtils {
 		}
 	}
 
+	/**
+	 * Return whether the given Redis connection is transactional, that is, bound to the current thread by Spring's transaction facilities. 
+	 * 
+	 * @param conn Redis connection to check
+	 * @param connFactory Redis connection factory that the connection was created with
+	 * @return whether the connection is transactional or not
+	 */
 	public static boolean isConnectionTransactional(RedisConnection conn, RedisConnectionFactory connFactory) {
 		if (connFactory == null) {
 			return false;

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisOperations.java

@@ -26,12 +26,30 @@ import org.springframework.data.keyvalue.redis.connection.SortParameters;
 
 
 /**
- * Basic set of Redis operations, implemented by {@link RedisTemplate}. 
+ * Interface that specified a basic set of Redis operations, implemented by {@link RedisTemplate}.
+ * Not often used but a useful option for extensibility and testability (as it can be easily mocked or stubbed). 
  * 
  * @author Costin Leau
  */
 public interface RedisOperations<K, V> {
 
+	/**
+	 * Executes the given action within a Redis connection.
+	 * 
+	 * Application exceptions thrown by the action object get propagated to the caller (can only be unchecked) whenever possible.
+	 * Redis exceptions are transformed into appropriate DAO ones. 
+	 * Allows for returning a result object, that is a domain object or a collection of domain objects.
+	 * Performs automatic serialization/deserialization for the given objects to and from binary data suitable for the Redis storage.   
+	 * 
+	 * Note: Callback code is not supposed to handle transactions itself! Use an appropriate transaction manager. 
+	 * Generally, callback code must not touch any Connection lifecycle methods, like close, to let the template do its work. 
+	 * 
+	 * @param <T> return type
+	 * @param action callback object that specifies the Redis action
+	 * @return a result object returned by the action or <tt>null</tt>
+	 */
+	<T> T execute(RedisCallback<T> action);
+
 	Boolean exists(K key);
 
 	void delete(Collection<K> key);
@@ -79,8 +97,8 @@ public interface RedisOperations<K, V> {
 	ZSetOperations<K, V> zSetOps();
 
 	BoundZSetOperations<K, V> forZSet(K key);
-	
+
 	<HK, HV> HashOperations<K, HK, HV> hashOps();
 
 	<HK, HV> BoundHashOperations<K, HK, HV> forHash(K key);
-}
+}

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisTemplate.java

@@ -43,19 +43,26 @@ import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 
 /**
- * 
- * Helper class that simplifies Redis data access code. Automatically converts Redis connection exceptions into 
- * DataAccessExceptions, following the org.springframework.dao exception hierarchy.
- *
+ * Helper class that simplifies Redis data access code. 
+ * <p/>
+ * Performs automatic serialization/deserialization between the given objects and the underlying binary data in the Redis store.
+ * <p/>
  * The central method is execute, supporting Redis access code implementing the {@link RedisCallback} interface.
  * It provides {@link RedisConnection} handling such that neither the {@link RedisCallback} implementation nor 
- * the calling code needs to explicitly care about retrieving/closing Redis connections, or handling Session 
+ * the calling code needs to explicitly care about retrieving/closing Redis connections, or handling Connection 
  * lifecycle exceptions. For typical single step actions, there are various convenience methods.
- *  
+ * <p/>
+ * Once configured, this class is thread-safe.
+ * 
+ * <p/>Note that while the template is generified, it is up to the serializers/deserializers to properly convert the given Objects
+ * to and from binary data. When using a generic serialization mechanism (such as Java serialization or JSON) the types lose their
+ * importance and can be skipped or only used as syntactic sugar. 
+ * <p/>
  * <b>This is the central class in Redis support</b>.
- * Simplifies the use of Redis and helps avoid common errors.
  * 
  * @author Costin Leau
+ * @param <K> the Redis key type against which the template works (usually a String)
+ * @param <V> the Redis value type against which the template works
  */
 public class RedisTemplate<K, V> extends RedisAccessor implements RedisOperations<K, V> {
 
@@ -65,9 +72,18 @@ public class RedisTemplate<K, V> extends RedisAccessor implements RedisOperation
 	private RedisSerializer hashKeySerializer = new SimpleRedisSerializer();
 	private RedisSerializer hashValueSerializer = new SimpleRedisSerializer();
 
+	/**
+	 * Constructs a new <code>RedisTemplate</code> instance.
+	 *
+	 */
 	public RedisTemplate() {
 	}
 
+	/**
+	 * Constructs a new <code>RedisTemplate</code> instance.
+	 *
+	 * @param connectionFactory connection factory for creating new connections
+	 */
 	public RedisTemplate(RedisConnectionFactory connectionFactory) {
 		this.setConnectionFactory(connectionFactory);
 		afterPropertiesSet();
@@ -77,10 +93,28 @@ public class RedisTemplate<K, V> extends RedisAccessor implements RedisOperation
 		return execute(action, isExposeConnection());
 	}
 
+	/**
+	 * Executes the given action object within a connection, which can be exposed or not.
+	 *   
+	 * @param <T> return type
+	 * @param action callback object that specifies the Redis action
+	 * @param exposeConnection whether to enforce exposure of the native Redis Connection to callback code 
+	 * @return object returned by the action
+	 */
 	public <T> T execute(RedisCallback<T> action, boolean exposeConnection) {
 		return execute(action, exposeConnection, valueSerializer);
 	}
 
+	/**
+	 * Executes the given action object within a connection, which can be exposed or not. Allows a custom serializer
+	 * to be specified for the returned object.
+	 * 
+	 * @param <T> return type
+	 * @param action action callback object that specifies the Redis action
+	 * @param exposeConnection whether to enforce exposure of the native Redis Connection to callback code
+	 * @param returnSerializer serializer used for converting the binary data to the custom return type
+	 * @return returned by the action
+	 */
 	public <T> T execute(RedisCallback<T> action, boolean exposeConnection, RedisSerializer<?> returnSerializer) {
 		Assert.notNull(action, "Callback object must not be null");
 
@@ -110,9 +144,9 @@ public class RedisTemplate<K, V> extends RedisAccessor implements RedisOperation
 	}
 
 	/**
-	 * Returns the exposeConnection.
+	 * Returns whether to expose the native Redis connection to RedisCallback code, or rather a connection proxy (the default). 
 	 *
-	 * @return Returns the exposeConnection
+	 * @return whether to expose the native Redis connection or not
 	 */
 	public boolean isExposeConnection() {
 		return exposeConnection;

spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/package-info.java

@@ -0,0 +1,7 @@
+/**
+ * Core package for integrating <a href="http://code.google.com/p/redis/">Redis</a> with Spring concepts.
+ * 
+ * <p/>Provides template support and callback for low-level access.
+ */
+package org.springframework.data.keyvalue.redis.core;
+