diff --git a/src/main/java/org/springframework/data/couchbase/CouchbaseClientFactory.java b/src/main/java/org/springframework/data/couchbase/CouchbaseClientFactory.java index 0586ea3a..cec54ebd 100644 --- a/src/main/java/org/springframework/data/couchbase/CouchbaseClientFactory.java +++ b/src/main/java/org/springframework/data/couchbase/CouchbaseClientFactory.java @@ -25,16 +25,47 @@ import com.couchbase.client.java.Cluster; 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. + *

+ * 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(); + } diff --git a/src/main/java/org/springframework/data/couchbase/SimpleCouchbaseClientFactory.java b/src/main/java/org/springframework/data/couchbase/SimpleCouchbaseClientFactory.java index 1c63cc5c..2f8d1501 100644 --- a/src/main/java/org/springframework/data/couchbase/SimpleCouchbaseClientFactory.java +++ b/src/main/java/org/springframework/data/couchbase/SimpleCouchbaseClientFactory.java @@ -31,6 +31,9 @@ import com.couchbase.client.java.Collection; 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; @@ -69,6 +72,7 @@ public class SimpleCouchbaseClientFactory implements CouchbaseClientFactory { this.exceptionTranslator = new CouchbaseExceptionTranslator(); } + @Override public CouchbaseClientFactory withScope(final String scopeName) { return new SimpleCouchbaseClientFactory(cluster, bucket.name(), scopeName); } diff --git a/src/main/java/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.java b/src/main/java/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.java index c85b9268..32cf783c 100644 --- a/src/main/java/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.java +++ b/src/main/java/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.java @@ -65,24 +65,59 @@ import com.couchbase.client.java.json.JacksonTransformers; @Configuration public abstract class AbstractCouchbaseConfiguration { + /** + * The connection string which allows the SDK to connect to the cluster. + *

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

+ * 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 abstract class AbstractCouchbaseConfiguration { 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) { } diff --git a/src/main/java/org/springframework/data/couchbase/core/CouchbaseOperations.java b/src/main/java/org/springframework/data/couchbase/core/CouchbaseOperations.java index b98fcaa2..3385278b 100644 --- a/src/main/java/org/springframework/data/couchbase/core/CouchbaseOperations.java +++ b/src/main/java/org/springframework/data/couchbase/core/CouchbaseOperations.java @@ -24,12 +24,24 @@ import org.springframework.data.couchbase.core.convert.CouchbaseConverter; */ 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(); } diff --git a/src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplate.java b/src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplate.java index d1f482a6..4458d98a 100644 --- a/src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplate.java +++ b/src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplate.java @@ -20,8 +20,6 @@ import org.springframework.beans.BeansException; 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 org.springframework.lang.Nullable; 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, 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 class CouchbaseTemplate implements CouchbaseOperations, ApplicationContex 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) { diff --git a/src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplateSupport.java b/src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplateSupport.java index 0419125c..1e69eda3 100644 --- a/src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplateSupport.java +++ b/src/main/java/org/springframework/data/couchbase/core/CouchbaseTemplateSupport.java @@ -40,20 +40,20 @@ import org.springframework.data.mapping.model.ConvertingPropertyAccessor; 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, 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) { diff --git a/src/main/java/org/springframework/data/couchbase/core/ExecutableExistsByIdOperation.java b/src/main/java/org/springframework/data/couchbase/core/ExecutableExistsByIdOperation.java index 2ebf3740..a5b44efa 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ExecutableExistsByIdOperation.java +++ b/src/main/java/org/springframework/data/couchbase/core/ExecutableExistsByIdOperation.java @@ -20,18 +20,38 @@ import java.util.Map; 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 all(Collection 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); } diff --git a/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByAnalyticsOperation.java b/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByAnalyticsOperation.java index dd33027f..3fa427ab 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByAnalyticsOperation.java +++ b/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByAnalyticsOperation.java @@ -19,19 +19,26 @@ import java.util.List; 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. + */ ExecutableFindByAnalytics findByAnalytics(Class domainType); interface TerminatingFindByAnalytics { + /** * 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 one() { return Optional.ofNullable(oneValue()); @@ -41,7 +48,7 @@ public interface ExecutableFindByAnalyticsOperation { * 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 @@ public interface ExecutableFindByAnalyticsOperation { } - /** - * Terminating operations invoking the actual query execution. - * - * @author Christoph Strobl - * @since 2.0 - */ interface FindByAnalyticsWithQuery extends TerminatingFindByAnalytics { /** - * 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 matching(AnalyticsQuery query); diff --git a/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByIdOperation.java b/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByIdOperation.java index b19d31e6..04cd5880 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByIdOperation.java +++ b/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByIdOperation.java @@ -19,23 +19,51 @@ import java.util.Collection; public interface ExecutableFindByIdOperation { + /** + * Loads a document from a bucket. + * + * @param domainType the entity type to use for the results. + */ ExecutableFindById findById(Class domainType); interface TerminatingFindById { + /** + * Finds one document based on the given ID. + * + * @param id the document ID. + * @return the entity if found. + */ T one(String id); + /** + * Finds a list of documents based on the given IDs. + * + * @param ids the document ID ids. + * @return the list of found entities. + */ Collection all(Collection ids); } interface FindByIdWithCollection extends TerminatingFindById { + /** + * Allows to specify a different collection than the default one configured. + * + * @param collection the collection to use in this scope. + */ TerminatingFindById inCollection(String collection); + } interface FindByIdWithProjection extends FindByIdWithCollection { + /** + * Load only certain fields for the document. + * + * @param fields the projected fields to load. + */ FindByIdWithCollection project(String... fields); } diff --git a/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByQueryOperation.java b/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByQueryOperation.java index f51dd37b..2fc6e428 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByQueryOperation.java +++ b/src/main/java/org/springframework/data/couchbase/core/ExecutableFindByQueryOperation.java @@ -19,6 +19,7 @@ import java.util.List; import java.util.Optional; import java.util.stream.Stream; +import org.springframework.dao.IncorrectResultSizeDataAccessException; import org.springframework.data.couchbase.core.query.Query; import org.springframework.lang.Nullable; @@ -26,6 +27,11 @@ import com.couchbase.client.java.query.QueryScanConsistency; public interface ExecutableFindByQueryOperation { + /** + * Queries the N1QL service. + * + * @param domainType the entity type to use for the results. + */ ExecutableFindByQuery findByQuery(Class domainType); interface TerminatingFindByQuery { @@ -33,7 +39,7 @@ public interface ExecutableFindByQueryOperation { * 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 one() { return Optional.ofNullable(oneValue()); @@ -43,7 +49,7 @@ public interface ExecutableFindByQueryOperation { * 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(); @@ -104,10 +110,9 @@ public interface ExecutableFindByQueryOperation { interface FindByQueryWithQuery extends TerminatingFindByQuery { /** - * Set the filter query to be used. + * Set the filter for the query to be used. * * @param query must not be {@literal null}. - * @return new instance of {@link TerminatingFindByQuery}. * @throws IllegalArgumentException if query is {@literal null}. */ TerminatingFindByQuery matching(Query query); @@ -116,6 +121,11 @@ public interface ExecutableFindByQueryOperation { interface FindByQueryConsistentWith extends FindByQueryWithQuery { + /** + * Allows to override the default scan consistency. + * + * @param scanConsistency the custom scan consistency to use for this query. + */ FindByQueryWithQuery consistentWith(QueryScanConsistency scanConsistency); } diff --git a/src/main/java/org/springframework/data/couchbase/core/FluentCouchbaseOperations.java b/src/main/java/org/springframework/data/couchbase/core/FluentCouchbaseOperations.java index 42a66082..4a4da4de 100644 --- a/src/main/java/org/springframework/data/couchbase/core/FluentCouchbaseOperations.java +++ b/src/main/java/org/springframework/data/couchbase/core/FluentCouchbaseOperations.java @@ -16,6 +16,9 @@ package org.springframework.data.couchbase.core; +/** + * The fluent couchbase operations combines all different possible operations for simplicity reasons. + */ public interface FluentCouchbaseOperations extends ExecutableUpsertByIdOperation, ExecutableInsertByIdOperation, ExecutableReplaceByIdOperation, ExecutableFindByIdOperation, ExecutableFindFromReplicasByIdOperation, ExecutableFindByQueryOperation, ExecutableFindByAnalyticsOperation, ExecutableExistsByIdOperation, diff --git a/src/main/java/org/springframework/data/couchbase/core/ReactiveCouchbaseOperations.java b/src/main/java/org/springframework/data/couchbase/core/ReactiveCouchbaseOperations.java index f82bdbe9..b438d10e 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ReactiveCouchbaseOperations.java +++ b/src/main/java/org/springframework/data/couchbase/core/ReactiveCouchbaseOperations.java @@ -20,16 +20,28 @@ import org.springframework.data.couchbase.CouchbaseClientFactory; import org.springframework.data.couchbase.core.convert.CouchbaseConverter; /** - * Defines common operations on the Couchbase data source, most commonly implemented by {@link CouchbaseTemplate}. + * Defines common operations on the Couchbase data source, most commonly implemented by {@link ReactiveCouchbaseTemplate}. */ public interface ReactiveCouchbaseOperations extends ReactiveFluentCouchbaseOperations { + /** + * 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(); } diff --git a/src/main/java/org/springframework/data/couchbase/core/ReactiveCouchbaseTemplate.java b/src/main/java/org/springframework/data/couchbase/core/ReactiveCouchbaseTemplate.java index d7bf8398..c231530f 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ReactiveCouchbaseTemplate.java +++ b/src/main/java/org/springframework/data/couchbase/core/ReactiveCouchbaseTemplate.java @@ -136,13 +136,13 @@ public class ReactiveCouchbaseTemplate implements ReactiveCouchbaseOperations, A * * @param ex the exception to translate */ - RuntimeException potentiallyConvertRuntimeException(RuntimeException ex) { + RuntimeException potentiallyConvertRuntimeException(final 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 { templateSupport.setApplicationContext(applicationContext); } diff --git a/src/main/java/org/springframework/data/couchbase/core/ReactiveExistsByIdOperation.java b/src/main/java/org/springframework/data/couchbase/core/ReactiveExistsByIdOperation.java index 81156db3..cd85162c 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ReactiveExistsByIdOperation.java +++ b/src/main/java/org/springframework/data/couchbase/core/ReactiveExistsByIdOperation.java @@ -22,19 +22,40 @@ import java.util.Map; public interface ReactiveExistsByIdOperation { + /** + * Checks if the document exists in the bucket. + */ ReactiveExistsById 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. + */ Mono 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. + */ Mono> all(Collection 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); + } interface ReactiveExistsById extends ExistsByIdWithCollection {} diff --git a/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByAnalyticsOperation.java b/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByAnalyticsOperation.java index 63beb527..32bbf96d 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByAnalyticsOperation.java +++ b/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByAnalyticsOperation.java @@ -15,13 +15,21 @@ */ package org.springframework.data.couchbase.core; +import org.springframework.dao.IncorrectResultSizeDataAccessException; import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; import org.springframework.data.couchbase.core.query.AnalyticsQuery; +import java.util.Optional; + public interface ReactiveFindByAnalyticsOperation { + /** + * Queries the analytics service. + * + * @param domainType the entity type to use for the results. + */ ReactiveFindByAnalytics findByAnalytics(Class domainType); /** @@ -29,31 +37,50 @@ public interface ReactiveFindByAnalyticsOperation { */ interface TerminatingFindByAnalytics { + /** + * Get exactly zero or one result. + * + * @return a mono with the match if found (an empty one otherwise). + * @throws IncorrectResultSizeDataAccessException if more than one match found. + */ Mono one(); + /** + * Get the first or no result. + * + * @return the first or an empty mono if none found. + */ Mono first(); + /** + * Get all matching elements. + * + * @return never {@literal null}. + */ Flux all(); + /** + * Get the number of matching elements. + * + * @return total number of matching elements. + */ Mono count(); + /** + * Check for the presence of matching elements. + * + * @return {@literal true} if at least one matching element exists. + */ Mono exists(); } - /** - * Terminating operations invoking the actual query execution. - * - * @author Christoph Strobl - * @since 2.0 - */ interface FindByAnalyticsWithQuery extends TerminatingFindByAnalytics { /** - * 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 matching(AnalyticsQuery query); diff --git a/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByIdOperation.java b/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByIdOperation.java index b801a855..6d753955 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByIdOperation.java +++ b/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByIdOperation.java @@ -22,23 +22,50 @@ import java.util.Collection; public interface ReactiveFindByIdOperation { + /** + * Loads a document from a bucket. + * + * @param domainType the entity type to use for the results. + */ ReactiveFindById findById(Class domainType); interface TerminatingFindById { + /** + * Finds one document based on the given ID. + * + * @param id the document ID. + * @return the entity if found. + */ Mono one(String id); + /** + * Finds a list of documents based on the given IDs. + * + * @param ids the document ID ids. + * @return the list of found entities. + */ Flux all(Collection ids); } interface FindByIdWithCollection extends TerminatingFindById { + /** + * Allows to specify a different collection than the default one configured. + * + * @param collection the collection to use in this scope. + */ TerminatingFindById inCollection(String collection); } interface FindByIdWithProjection extends FindByIdWithCollection { + /** + * Load only certain fields for the document. + * + * @param fields the projected fields to load. + */ FindByIdWithCollection project(String... fields); } diff --git a/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByQueryOperation.java b/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByQueryOperation.java index af0d0110..50e333a9 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByQueryOperation.java +++ b/src/main/java/org/springframework/data/couchbase/core/ReactiveFindByQueryOperation.java @@ -15,6 +15,7 @@ */ package org.springframework.data.couchbase.core; +import org.springframework.dao.IncorrectResultSizeDataAccessException; import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; @@ -24,6 +25,11 @@ import com.couchbase.client.java.query.QueryScanConsistency; public interface ReactiveFindByQueryOperation { + /** + * Queries the N1QL service. + * + * @param domainType the entity type to use for the results. + */ ReactiveFindByQuery findByQuery(Class domainType); /** @@ -31,14 +37,40 @@ public interface ReactiveFindByQueryOperation { */ interface TerminatingFindByQuery { + /** + * Get exactly zero or one result. + * + * @return a mono with the match if found (an empty one otherwise). + * @throws IncorrectResultSizeDataAccessException if more than one match found. + */ Mono one(); + /** + * Get the first or no result. + * + * @return the first or an empty mono if none found. + */ Mono first(); + /** + * Get all matching elements. + * + * @return never {@literal null}. + */ Flux all(); + /** + * Get the number of matching elements. + * + * @return total number of matching elements. + */ Mono count(); + /** + * Check for the presence of matching elements. + * + * @return {@literal true} if at least one matching element exists. + */ Mono exists(); } @@ -52,10 +84,9 @@ public interface ReactiveFindByQueryOperation { interface FindByQueryWithQuery extends TerminatingFindByQuery { /** - * Set the filter query to be used. + * Set the filter for the query to be used. * * @param query must not be {@literal null}. - * @return new instance of {@link TerminatingFindByQuery}. * @throws IllegalArgumentException if query is {@literal null}. */ TerminatingFindByQuery matching(Query query); @@ -64,6 +95,11 @@ public interface ReactiveFindByQueryOperation { interface FindByQueryConsistentWith extends FindByQueryWithQuery { + /** + * Allows to override the default scan consistency. + * + * @param scanConsistency the custom scan consistency to use for this query. + */ FindByQueryWithQuery consistentWith(QueryScanConsistency scanConsistency); } diff --git a/src/main/java/org/springframework/data/couchbase/core/ReactiveFluentCouchbaseOperations.java b/src/main/java/org/springframework/data/couchbase/core/ReactiveFluentCouchbaseOperations.java index 6de90efa..0ff0a8b8 100644 --- a/src/main/java/org/springframework/data/couchbase/core/ReactiveFluentCouchbaseOperations.java +++ b/src/main/java/org/springframework/data/couchbase/core/ReactiveFluentCouchbaseOperations.java @@ -16,6 +16,9 @@ package org.springframework.data.couchbase.core; +/** + * The fluent couchbase operations combines all different possible operations for simplicity reasons. + */ public interface ReactiveFluentCouchbaseOperations extends ReactiveUpsertByIdOperation, ReactiveInsertByIdOperation, ReactiveReplaceByIdOperation, ReactiveFindByIdOperation, ReactiveExistsByIdOperation, ReactiveFindByAnalyticsOperation, ReactiveFindFromReplicasByIdOperation, ReactiveFindByQueryOperation, diff --git a/src/main/java/org/springframework/data/couchbase/core/query/N1qlSecondaryIndexed.java b/src/main/java/org/springframework/data/couchbase/core/query/N1qlSecondaryIndexed.java deleted file mode 100644 index bafb9cc3..00000000 --- a/src/main/java/org/springframework/data/couchbase/core/query/N1qlSecondaryIndexed.java +++ /dev/null @@ -1,46 +0,0 @@ -/* - * Copyright 2012-2020 the original author or authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * https://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package org.springframework.data.couchbase.core.query; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - -import org.springframework.data.couchbase.repository.CouchbaseRepository; - -/** - * This annotation is targeted at {@link CouchbaseRepository Repository} interfaces, indicating that the framework - * should ensure a N1QL Secondary Index is present when the repository is instantiated. - *

- * Said index will relate to the "type" field (the one bearing type information) and restrict on documents that match - * the repository's entity class. - *

- * Be sure to also use {@link N1qlPrimaryIndexed} to make sure the PRIMARY INDEX is there as well. - * - * @author Simon Baslé - */ -@Target({ ElementType.TYPE }) -@Retention(RetentionPolicy.RUNTIME) -public @interface N1qlSecondaryIndexed { - - /** - * the name of the index to be created, in the repository's associated bucket namespace. - */ - String indexName(); - -} diff --git a/src/main/java/org/springframework/data/couchbase/core/query/ViewIndexed.java b/src/main/java/org/springframework/data/couchbase/core/query/ViewIndexed.java deleted file mode 100644 index 0cdc419b..00000000 --- a/src/main/java/org/springframework/data/couchbase/core/query/ViewIndexed.java +++ /dev/null @@ -1,63 +0,0 @@ -/* - * Copyright 2012-2020 the original author or authors - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * https://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -package org.springframework.data.couchbase.core.query; - -import java.lang.annotation.ElementType; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; -import java.lang.annotation.Target; - -import org.springframework.data.couchbase.repository.CouchbaseRepository; - -/** - * This annotation is targeted at {@link CouchbaseRepository Repository} interfaces, indicating that the framework - * should ensure a View is present when the repository is instantiated. - *

- * The view must at least be described as a design document name and view name. Default map function will filter - * documents on the type associated to the repository, and default reduce function is "_count". - *

- * One can specify a custom reduce function as well as a non-default map function. - * - * @author Simon Baslé - */ -@Target({ ElementType.TYPE }) -@Retention(RetentionPolicy.RUNTIME) -public @interface ViewIndexed { - - /** - * The design document in which to create/look for the view. Usually to create the backing view for CRUD methods, the - * expected designDoc value is the entity's simple class name, with a lowercase first letter (eg. a UserInfo - * repository would expect a design document named "userInfo"). - */ - String designDoc(); - - /** - * The name of the view, defaults to "all" (which is what CRUD methods expect by default). - */ - String viewName() default "all"; - - /** - * The map function to use (default is empty, which will trigger a default map function filtering on the repository's - * associated entity type). - */ - String mapFunction() default ""; - - /** - * The reduce function to use (default is built in "_count" reduce function). - */ - String reduceFunction() default "_count"; -} diff --git a/src/main/java/org/springframework/data/couchbase/repository/CouchbaseRepository.java b/src/main/java/org/springframework/data/couchbase/repository/CouchbaseRepository.java index 6e8d6b61..aab74e92 100644 --- a/src/main/java/org/springframework/data/couchbase/repository/CouchbaseRepository.java +++ b/src/main/java/org/springframework/data/couchbase/repository/CouchbaseRepository.java @@ -21,9 +21,10 @@ import java.util.List; import org.springframework.data.domain.Sort; import org.springframework.data.repository.NoRepositoryBean; import org.springframework.data.repository.PagingAndSortingRepository; +import org.springframework.data.repository.Repository; /** - * Couchbase specific {@link org.springframework.data.repository.Repository} interface. + * Couchbase specific {@link Repository} interface. * * @author Michael Nitschinger */ diff --git a/src/main/java/org/springframework/data/couchbase/repository/ReactiveCouchbaseRepository.java b/src/main/java/org/springframework/data/couchbase/repository/ReactiveCouchbaseRepository.java index a2afdbe0..d76af65f 100644 --- a/src/main/java/org/springframework/data/couchbase/repository/ReactiveCouchbaseRepository.java +++ b/src/main/java/org/springframework/data/couchbase/repository/ReactiveCouchbaseRepository.java @@ -19,6 +19,8 @@ import org.springframework.data.repository.NoRepositoryBean; import org.springframework.data.repository.reactive.ReactiveSortingRepository; /** + * Couchbase-specific {@link ReactiveSortingRepository} implementation. + * * @author Subhashni Balakrishnan * @since 3.0 */