more comments and refactoring.

src/main/java/com/couchbase/spring/cache/CouchbaseCache.java

@@ -23,6 +23,7 @@
 package com.couchbase.spring.cache;
 
 import com.couchbase.client.CouchbaseClient;
+import net.spy.memcached.internal.OperationFuture;
 import org.springframework.cache.Cache;
 import org.springframework.cache.support.SimpleValueWrapper;
 
@@ -45,9 +46,10 @@ public class CouchbaseCache implements Cache {
   /**
    * Construct the cache and pass in the CouchbaseClient instance.
    *
+   * @param name the name of the cache reference.
    * @param client the CouchbaseClient instance.
    */
-  public CouchbaseCache(String name, CouchbaseClient client) {
+  public CouchbaseCache(final String name, final CouchbaseClient client) {
     this.name = name;
     this.client = client;
   }
@@ -57,7 +59,7 @@ public class CouchbaseCache implements Cache {
    *
    * @return the name of the cache.
    */
-  public String getName() {
+  public final String getName() {
     return name;
   }
 
@@ -66,7 +68,7 @@ public class CouchbaseCache implements Cache {
    *
    * @return the actual CouchbaseClient instance.
    */
-  public CouchbaseClient getNativeCache() {
+  public final CouchbaseClient getNativeCache() {
     return this.client;
   }
 
@@ -76,7 +78,7 @@ public class CouchbaseCache implements Cache {
    * @param key the key to lookup against.
    * @return the fetched value from Couchbase.
    */
-  public ValueWrapper get(Object key) {
+  public final ValueWrapper get(final Object key) {
     String documentId = key.toString();
     Object result = this.client.get(documentId);
     return (result != null ? new SimpleValueWrapper(result) : null);
@@ -88,7 +90,7 @@ public class CouchbaseCache implements Cache {
    * @param key the Key of the storable object.
    * @param value the Object to store.
    */
-  public void put(Object key, Object value) {
+  public final void put(final Object key, final Object value) {
     String documentId = key.toString();
     this.client.set(documentId, 0, value);
   }
@@ -98,7 +100,7 @@ public class CouchbaseCache implements Cache {
    *
    * @param key the Key of the object to delete.
    */
-  public void evict(Object key) {
+  public final void evict(final Object key) {
     String documentId = key.toString();
     this.client.delete(documentId);
   }
@@ -109,7 +111,7 @@ public class CouchbaseCache implements Cache {
    * Note that this action is very destructive, so only use it with care.
    * Also note that "flush" may not be enabled on the bucket.
    */
-  public void clear() {
+  public final void clear() {
     this.client.flush();
   }
 

src/main/java/com/couchbase/spring/cache/CouchbaseCacheManager.java

@@ -45,9 +45,11 @@ public class CouchbaseCacheManager extends AbstractCacheManager {
   private final HashMap<String, CouchbaseClient> clients;
 
   /**
-   * Construct a new CouchabseCacheManager.
+   * Construct a new CouchbaseCacheManager.
+   *
+   * @param clients one ore more CouchbaseClients to reference.
    */
-  public CouchbaseCacheManager(HashMap<String, CouchbaseClient> clients) {
+  public CouchbaseCacheManager(final HashMap<String, CouchbaseClient> clients) {
     this.clients = clients;
   }
 
@@ -56,7 +58,7 @@ public class CouchbaseCacheManager extends AbstractCacheManager {
    *
    * @return the actual CouchbaseClient instances.
    */
-  public HashMap<String, CouchbaseClient> getClients() {
+  public final HashMap<String, CouchbaseClient> getClients() {
     return this.clients;
   }
 
@@ -66,10 +68,10 @@ public class CouchbaseCacheManager extends AbstractCacheManager {
    * @return a collection of loaded caches.
    */
   @Override
-  protected Collection<? extends Cache> loadCaches() {
+  protected final Collection<? extends Cache> loadCaches() {
     Collection<Cache> caches = new LinkedHashSet<Cache>();
 
-    for(Map.Entry<String, CouchbaseClient> cache : this.clients.entrySet()) {
+    for (Map.Entry<String, CouchbaseClient> cache : this.clients.entrySet()) {
       caches.add(new CouchbaseCache(cache.getKey(), cache.getValue()));
     }
 

src/main/java/com/couchbase/spring/core/CouchbaseExceptionTranslator.java

@@ -42,13 +42,19 @@ import com.couchbase.client.vbucket.ConnectionException;
  */
 public class CouchbaseExceptionTranslator implements PersistenceExceptionTranslator {
 
+  /**
+   * Translate Couchbase specific exceptions to spring exceptions if possible.
+   *
+   * @param ex the exception to translate.
+   * @return the translated exception or null.
+   */
 	@Override
-	public DataAccessException translateExceptionIfPossible(RuntimeException ex) {
-		if(ex instanceof ConnectionException) {
+	public final DataAccessException translateExceptionIfPossible(RuntimeException ex) {
+		if (ex instanceof ConnectionException) {
 			return new DataAccessResourceFailureException(ex.getMessage(), ex);
 		}
 		
-		if(ex instanceof ObservedException ||
+		if (ex instanceof ObservedException ||
 			 ex instanceof ObservedTimeoutException ||
 			 ex instanceof ObservedModifiedException) {
 			return new DataIntegrityViolationException(ex.getMessage(), ex);

src/main/java/com/couchbase/spring/core/CouchbaseOperations.java

@@ -127,4 +127,16 @@ public interface CouchbaseOperations {
    * @param batchToRemove the list of Objects to remove.
    */
   void remove(Collection<? extends Object> batchToRemove);
+
+  /**
+   * Executes a DbCallback translating any exceptions as necessary.
+   *
+   * Allows for returning a result object, that is a domain object or a
+   * collection of domain objects.
+   *
+   * @param action the action to execute in the callback.
+   * @param <T> the return type.
+   * @return
+   */
+  <T> T execute(DbCallback<T> action);
 }

src/main/java/com/couchbase/spring/core/CouchbaseTemplate.java

@@ -143,6 +143,14 @@ public class CouchbaseTemplate implements CouchbaseOperations {
     }
   }
 
+  public <T> T execute(final DbCallback<T> action) {
+    try {
+      return action.doInBucket();
+    } catch (RuntimeException e) {
+      throw potentiallyConvertRuntimeException(e);
+    }
+  }
+
   /**
    * Make sure the given object is not a iterable.
    *

src/main/java/com/couchbase/spring/core/DbCallback.java

@@ -0,0 +1,6 @@
+package com.couchbase.spring.core;
+
+
+public interface DbCallback<T> {
+  T doInBucket();
+}