From cb122aed50054565c03875f93f7bd3814abfa582 Mon Sep 17 00:00:00 2001 From: Costin Leau Date: Tue, 7 Dec 2010 19:39:48 +0200 Subject: [PATCH] + and yet more javadocs --- .../redis/connection/package-info.java | 7 +-- .../redis/core/BoundValueOperations.java | 2 + .../keyvalue/redis/core/DefaultKeyBound.java | 1 + .../keyvalue/redis/core/ListOperations.java | 2 +- .../keyvalue/redis/core/RedisAccessor.java | 7 ++- .../keyvalue/redis/core/RedisCallback.java | 13 ++--- .../redis/core/RedisConnectionUtils.java | 30 ++++++++++- .../keyvalue/redis/core/RedisOperations.java | 24 +++++++-- .../keyvalue/redis/core/RedisTemplate.java | 52 +++++++++++++++---- .../keyvalue/redis/core/package-info.java | 7 +++ 10 files changed, 118 insertions(+), 27 deletions(-) create mode 100644 spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/package-info.java diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/connection/package-info.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/connection/package-info.java index 096008586..72c48c6b4 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/connection/package-info.java +++ b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/connection/package-info.java @@ -1,7 +1,8 @@ /** - *

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. + * + *

Performs exception translation between the underlying library exceptions to Spring's DAO hierarchy. */ package org.springframework.data.keyvalue.redis.connection; diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/BoundValueOperations.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/BoundValueOperations.java index 1cf4d3217..4e8eb4f6d 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/BoundValueOperations.java +++ b/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 extends KeyBound { diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/DefaultKeyBound.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/DefaultKeyBound.java index 20df1b616..84f2043b5 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/DefaultKeyBound.java +++ b/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 */ diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/ListOperations.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/ListOperations.java index a9a610d3a..8a7f99707 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/ListOperations.java +++ b/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 */ diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisAccessor.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisAccessor.java index 76803929f..cf758c6f1 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisAccessor.java +++ b/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"); - } } \ No newline at end of file diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisCallback.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisCallback.java index 79e93c131..bd428a3ea 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisCallback.java +++ b/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 { /** * 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; } diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisConnectionUtils.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisConnectionUtils.java index 1044c7ab2..13f13e8f9 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisConnectionUtils.java +++ b/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 true. + * + * @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; diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisOperations.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisOperations.java index dcab5ffcd..7dcbb3ab2 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisOperations.java +++ b/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 { + /** + * 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 return type + * @param action callback object that specifies the Redis action + * @return a result object returned by the action or null + */ + T execute(RedisCallback action); + Boolean exists(K key); void delete(Collection key); @@ -79,8 +97,8 @@ public interface RedisOperations { ZSetOperations zSetOps(); BoundZSetOperations forZSet(K key); - + HashOperations hashOps(); BoundHashOperations forHash(K key); -} +} \ No newline at end of file diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisTemplate.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisTemplate.java index f3a806d96..bf9231745 100644 --- a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/RedisTemplate.java +++ b/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. + *

+ * Performs automatic serialization/deserialization between the given objects and the underlying binary data in the Redis store. + *

* 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. - * + *

+ * Once configured, this class is thread-safe. + * + *

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. + *

* This is the central class in Redis support. - * Simplifies the use of Redis and helps avoid common errors. * * @author Costin Leau + * @param the Redis key type against which the template works (usually a String) + * @param the Redis value type against which the template works */ public class RedisTemplate extends RedisAccessor implements RedisOperations { @@ -65,9 +72,18 @@ public class RedisTemplate extends RedisAccessor implements RedisOperation private RedisSerializer hashKeySerializer = new SimpleRedisSerializer(); private RedisSerializer hashValueSerializer = new SimpleRedisSerializer(); + /** + * Constructs a new RedisTemplate instance. + * + */ public RedisTemplate() { } + /** + * Constructs a new RedisTemplate instance. + * + * @param connectionFactory connection factory for creating new connections + */ public RedisTemplate(RedisConnectionFactory connectionFactory) { this.setConnectionFactory(connectionFactory); afterPropertiesSet(); @@ -77,10 +93,28 @@ public class RedisTemplate extends RedisAccessor implements RedisOperation return execute(action, isExposeConnection()); } + /** + * Executes the given action object within a connection, which can be exposed or not. + * + * @param 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 execute(RedisCallback 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 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 execute(RedisCallback action, boolean exposeConnection, RedisSerializer returnSerializer) { Assert.notNull(action, "Callback object must not be null"); @@ -110,9 +144,9 @@ public class RedisTemplate 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; diff --git a/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/package-info.java b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/package-info.java new file mode 100644 index 000000000..2b41724e0 --- /dev/null +++ b/spring-data-redis/src/main/java/org/springframework/data/keyvalue/redis/core/package-info.java @@ -0,0 +1,7 @@ +/** + * Core package for integrating Redis with Spring concepts. + * + *

Provides template support and callback for low-level access. + */ +package org.springframework.data.keyvalue.redis.core; +