DATACOUCH-531 - Initial javadoc polish for GA

Author: daschl

src/main/java/org/springframework/data/couchbase/CouchbaseClientFactory.java

@@ -25,16 +25,47 @@
 import com.couchbase.client.java.Collection;
 import com.couchbase.client.java.Scope;
 
+/**
+ * The {@link CouchbaseClientFactory} is the main way to get access to the managed SDK instance and resources.
+ * <p>
+ * Please note that a single factory is always bound to a {@link Bucket}, so if you need to access more than one
+ * you need to initialize one factory for each.
+ */
 public interface CouchbaseClientFactory extends Closeable {
 
+	/**
+	 * Provides access to the managed SDK {@link Cluster} reference.
+	 */
 	Cluster getCluster();
 
+	/**
+	 * Provides access to the managed SDK {@link Bucket} reference.
+	 */
 	Bucket getBucket();
 
+	/**
+	 * Provides access to the managed SDK {@link Scope} reference.
+	 */
 	Scope getScope();
 
-	PersistenceExceptionTranslator getExceptionTranslator();
-
+	/**
+	 * Provides access to a collection (identified by its name) in managed SDK {@link Scope} reference.
+	 *
+	 * @param name the name of the collection. If null is passed in, the default collection is assumed.
+	 */
 	Collection getCollection(String name);
 
+	/**
+	 * Returns a new {@link CouchbaseClientFactory} set to the scope given as an argument.
+	 *
+	 * @param scopeName the name of the scope to use for all collection access.
+	 * @return a new client factory, bound to the other scope.
+	 */
+	CouchbaseClientFactory withScope(String scopeName);
+
+	/**
+	 * The exception translator used on the factory.
+	 */
+	PersistenceExceptionTranslator getExceptionTranslator();
+
 }

src/main/java/org/springframework/data/couchbase/SimpleCouchbaseClientFactory.java

@@ -31,6 +31,9 @@
 import com.couchbase.client.java.Scope;
 import com.couchbase.client.java.env.ClusterEnvironment;
 
+/**
+ * The default implementation of a {@link CouchbaseClientFactory}.
+ */
 public class SimpleCouchbaseClientFactory implements CouchbaseClientFactory {
 
 	private final Supplier<Cluster> cluster;
@@ -69,6 +72,7 @@ private SimpleCouchbaseClientFactory(final Supplier<Cluster> cluster, final Stri
 		this.exceptionTranslator = new CouchbaseExceptionTranslator();
 	}
 
+	@Override
 	public CouchbaseClientFactory withScope(final String scopeName) {
 		return new SimpleCouchbaseClientFactory(cluster, bucket.name(), scopeName);
 	}

src/main/java/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.java

@@ -65,24 +65,59 @@
 @Configuration
 public abstract class AbstractCouchbaseConfiguration {
 
+	/**
+	 * The connection string which allows the SDK to connect to the cluster.
+	 * <p>
+	 * Note that the connection string can take many forms, in its simplest it is just a single hostname
+	 * like "127.0.0.1". Please refer to the couchbase Java SDK documentation for all the different
+	 * possibilities and options.
+	 */
 	public abstract String getConnectionString();
 
+	/**
+	 * The username of the user accessing Couchbase, configured on the cluster.
+	 */
 	public abstract String getUserName();
 
+	/**
+	 * The password used or the username to authenticate against the cluster.
+	 */
 	public abstract String getPassword();
 
+	/**
+	 * The name of the bucket that should be used (for example "travel-sample").
+	 */
 	public abstract String getBucketName();
 
+	/**
+	 * If a non-default scope should be used, override this method.
+	 *
+	 * @return the custom scope name or null if the default scope should be used (default).
+	 */
 	protected String getScopeName() {
 		return null;
 	}
 
+	/**
+	 * Allows to override the {@link Authenticator} used.
+	 * <p>
+	 * The default implementation uses the {@link PasswordAuthenticator} and takes the username and password from
+	 * {@link #getUserName()} and {@link #getPassword()} respectively.
+	 *
+	 * @return the authenticator to be passed into the SDK.
+	 */
 	protected Authenticator authenticator() {
 		return PasswordAuthenticator.create(getUserName(), getPassword());
 	}
 
+	/**
+	 * The {@link CouchbaseClientFactory} provides access to the lower level SDK resources.
+	 *
+	 * @param couchbaseCluster the cluster reference from the SDK.
+	 * @return the initialized factory.
+	 */
 	@Bean
-	public CouchbaseClientFactory couchbaseClientFactory(Cluster couchbaseCluster) {
+	public CouchbaseClientFactory couchbaseClientFactory(final Cluster couchbaseCluster) {
 		return new SimpleCouchbaseClientFactory(couchbaseCluster, getBucketName(), getScopeName());
 	}
 
@@ -99,6 +134,11 @@ public ClusterEnvironment couchbaseClusterEnvironment() {
 		return builder.build();
 	}
 
+	/**
+	 * Can be overridden to customize the configuration of the environment before bootstrap.
+	 *
+	 * @param builder the builder that can be customized.
+	 */
 	protected void configureEnvironment(final ClusterEnvironment.Builder builder) {
 
 	}

src/main/java/org/springframework/data/couchbase/core/CouchbaseOperations.java

@@ -24,12 +24,24 @@
  */
 public interface CouchbaseOperations extends FluentCouchbaseOperations {
 
+	/**
+	 * Returns the converter used for this template/operations.
+	 */
 	CouchbaseConverter getConverter();
 
+	/**
+	 * The name of the bucket used.
+	 */
 	String getBucketName();
 
+	/**
+	 * The name of the scope used, null if the default scope is used.
+	 */
 	String getScopeName();
 
+	/**
+	 * Returns the underlying client factory.
+	 */
 	CouchbaseClientFactory getCouchbaseClientFactory();
 
 }

src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplate.java

@@ -20,8 +20,6 @@
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.ApplicationContextAware;
 import org.springframework.context.ConfigurableApplicationContext;
-import org.springframework.dao.DataAccessException;
-import org.springframework.dao.support.PersistenceExceptionTranslator;
 import org.springframework.data.couchbase.CouchbaseClientFactory;
 import org.springframework.data.couchbase.core.convert.CouchbaseConverter;
 import org.springframework.data.couchbase.core.index.CouchbasePersistentEntityIndexCreator;
@@ -34,7 +32,7 @@
 import com.couchbase.client.java.Collection;
 
 /**
- * Implements Couchbase operations findBy, insertBy, upsertBy, replaceBy, removeBy, existsBy
+ * Implements lower-level couchbase operations on top of the SDK with entity mapping capabilities.
  *
  * @author Michael Nitschinger
  * @author Michael Reiche
@@ -44,7 +42,6 @@ public class CouchbaseTemplate implements CouchbaseOperations, ApplicationContex
 
 	private final CouchbaseClientFactory clientFactory;
 	private final CouchbaseConverter converter;
-	private final PersistenceExceptionTranslator exceptionTranslator;
 	private final CouchbaseTemplateSupport templateSupport;
 	private final MappingContext<? extends CouchbasePersistentEntity<?>, CouchbasePersistentProperty> mappingContext;
 	private final ReactiveCouchbaseTemplate reactiveCouchbaseTemplate;
@@ -53,7 +50,6 @@ public class CouchbaseTemplate implements CouchbaseOperations, ApplicationContex
 	public CouchbaseTemplate(final CouchbaseClientFactory clientFactory, final CouchbaseConverter converter) {
 		this.clientFactory = clientFactory;
 		this.converter = converter;
-		this.exceptionTranslator = clientFactory.getExceptionTranslator();
 		this.templateSupport = new CouchbaseTemplateSupport(converter);
 		this.reactiveCouchbaseTemplate = new ReactiveCouchbaseTemplate(clientFactory, converter);
 
@@ -146,33 +142,18 @@ public CouchbaseConverter getConverter() {
 		return converter;
 	}
 
-	CouchbaseTemplateSupport support() {
-		return templateSupport;
-	}
-
 	public ReactiveCouchbaseTemplate reactive() {
 		return reactiveCouchbaseTemplate;
 	}
 
-	/**
-	 * Tries to convert the given {@link RuntimeException} into a {@link DataAccessException} but returns the original
-	 * exception if the conversation failed. Thus allows safe re-throwing of the return value.
-	 *
-	 * @param ex the exception to translate
-	 */
-	RuntimeException potentiallyConvertRuntimeException(RuntimeException ex) {
-		RuntimeException resolved = exceptionTranslator.translateExceptionIfPossible(ex);
-		return resolved == null ? ex : resolved;
-	}
-
 	@Override
-	public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
+	public void setApplicationContext(final ApplicationContext applicationContext) throws BeansException {
 		prepareIndexCreator(applicationContext);
 		templateSupport.setApplicationContext(applicationContext);
 		reactiveCouchbaseTemplate.setApplicationContext(applicationContext);
 	}
 
-	private void prepareIndexCreator(ApplicationContext context) {
+	private void prepareIndexCreator(final ApplicationContext context) {
 		String[] indexCreators = context.getBeanNamesForType(CouchbasePersistentEntityIndexCreator.class);
 
 		for (String creator : indexCreators) {

src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplateSupport.java

@@ -40,20 +40,20 @@
 import org.springframework.util.Assert;
 
 /**
- * encode/decode support for CouchbaseTemplate
+ * Internal encode/decode support for CouchbaseTemplate.
  *
  * @author Michael Nitschinger
  * @author Michael Reiche
  * @since 3.0
  */
-public class CouchbaseTemplateSupport implements ApplicationContextAware {
+class CouchbaseTemplateSupport implements ApplicationContextAware {
+
 	private static final Logger LOG = LoggerFactory.getLogger(CouchbaseTemplateSupport.class);
 
 	private final CouchbaseConverter converter;
 	private final MappingContext<? extends CouchbasePersistentEntity<?>, CouchbasePersistentProperty> mappingContext;
-	// TODO: this should be replaced I think
 	private final TranslationService translationService;
-	EntityCallbacks entityCallbacks;
+	private EntityCallbacks entityCallbacks;
 	private ApplicationContext applicationContext;
 
 	public CouchbaseTemplateSupport(final CouchbaseConverter converter) {

src/main/java/org/springframework/data/couchbase/core/ExecutableExistsByIdOperation.java

@@ -20,18 +20,38 @@
 
 public interface ExecutableExistsByIdOperation {
 
+	/**
+	 * Checks if the document exists in the bucket.
+	 */
 	ExecutableExistsById existsById();
 
 	interface TerminatingExistsById {
 
+		/**
+		 * Performs the operation on the ID given.
+		 *
+		 * @param id the ID to perform the operation on.
+		 * @return true if the document exists, false otherwise.
+		 */
 		boolean one(String id);
 
+		/**
+		 * Performs the operation on the collection of ids.
+		 *
+		 * @param ids the ids to check.
+		 * @return a map consisting of the document IDs as the keys and if they exist as the value.
+		 */
 		Map<String, Boolean> all(Collection<String> ids);
 
 	}
 
 	interface ExistsByIdWithCollection extends TerminatingExistsById {
 
+		/**
+		 * Allows to specify a different collection than the default one configured.
+		 *
+		 * @param collection the collection to use in this scope.
+		 */
 		TerminatingExistsById inCollection(String collection);
 	}
 

src/main/java/org/springframework/data/couchbase/core/ExecutableFindByAnalyticsOperation.java

@@ -19,19 +19,26 @@
 import java.util.Optional;
 import java.util.stream.Stream;
 
+import org.springframework.dao.IncorrectResultSizeDataAccessException;
 import org.springframework.data.couchbase.core.query.AnalyticsQuery;
 import org.springframework.lang.Nullable;
 
 public interface ExecutableFindByAnalyticsOperation {
 
+	/**
+	 * Queries the analytics service.
+	 *
+	 * @param domainType the entity type to use for the results.
+	 */
 	<T> ExecutableFindByAnalytics<T> findByAnalytics(Class<T> domainType);
 
 	interface TerminatingFindByAnalytics<T> {
+
 		/**
 		 * Get exactly zero or one result.
 		 *
 		 * @return {@link Optional#empty()} if no match found.
-		 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if more than one match found.
+		 * @throws IncorrectResultSizeDataAccessException if more than one match found.
 		 */
 		default Optional<T> one() {
 			return Optional.ofNullable(oneValue());
@@ -41,7 +48,7 @@ default Optional<T> one() {
 		 * Get exactly zero or one result.
 		 *
 		 * @return {@literal null} if no match found.
-		 * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if more than one match found.
+		 * @throws IncorrectResultSizeDataAccessException if more than one match found.
 		 */
 		@Nullable
 		T oneValue();
@@ -93,19 +100,12 @@ default Optional<T> first() {
 
 	}
 
-	/**
-	 * Terminating operations invoking the actual query execution.
-	 *
-	 * @author Christoph Strobl
-	 * @since 2.0
-	 */
 	interface FindByAnalyticsWithQuery<T> extends TerminatingFindByAnalytics<T> {
 
 		/**
-		 * Set the filter query to be used.
+		 * Set the filter for the analytics query to be used.
 		 *
 		 * @param query must not be {@literal null}.
-		 * @return new instance of {@link TerminatingFindByAnalytics}.
 		 * @throws IllegalArgumentException if query is {@literal null}.
 		 */
 		TerminatingFindByAnalytics<T> matching(AnalyticsQuery query);