DATACOUCH-588 - Part 2 of 2 refactoring for paging and projection. (#1080)

* DATACOUCH-588 - Part 2 of framework changes. Add support for projection and distinct. (#1040)

Support for projection is only for properties of the top-level entity. For instance, in UserSubmission, only the properties below can be specified in the projection. Projection support does not provide means of specifying something like address.street - you can only project (or not project) the whole address property. However, the address type in your resultType could have a subset of the properties in Address.

If the corresponding submissions in the resultType contained only the userId property

public class UserSubmission extends ComparableEntity {
	private String id;
	private String username;
	private List<String> roles;
	private Address address;
	private List<Submission> submissions;

Support for Distinct - I have appropriated the MongoDB model for Distinct.  It defines a separate DistinctOperationSupport class (within ExecutableFindByQuerySupport) which supports the distinct( distinctFields ) api and execution. The DistinctOperationSupport class has only a distinctFields member, and a 'delegate' member, which is an ExecutableFindByQuerySupport object. TBH, I don't see the advantage over simply adding a distinctFields member to ExecutableFindByQuerySupport

Amend #1 - changes as discussed in Pull Request
         - clean up test entity types

Amend #2
- Eliminate DistinctOperationSupport class. In MongoDB, only distinct on a single field is supported, so the returnType from distinct was very different from the returnType of other query operations (all(), one() etc. (but so is count(), and it doesn't need it's own class)). In Couchbase, distinct on any fields in the entity is allowed - so the returned type could be the domainType or resultType. And as(resultType) still allows any resultType to be specified. This makes it unnecessary to have combinations of interfaces such as DistinctWithProjection and DistinctWithQuery.

- Clean up the interfaces in ExecutableFindByQuery. There are two types of interfaces (a) the TerminatingFindByQuery which has the one(), oneValue() first(), firstValue(), all(), count(), exists() and stream(); and (b) the option interfaces (FindByQueryWithConsistency etc), which are essentially with-er interfaces. The changes are:
1) make all the with-er interfaces base interfaces instead of chaining them together. (I don't know why there isn't simply one interface with all the with-er methods).
2) make the ExecutableFindByQuery interface extend the Terminating interface and all the with-er interfaces.

Amend #3
- Add execution support for collections

Amend #4
- Add tests for collections. This includes a new CollectionAwareIntegrationTests class which extends a new JavaIntegratationTests class which extends the existing ClusterAwareIntegrationTests.
- Fixed up several issues collections issues that were uncovered by the tests.
- Did further cleanup of OperationSupport interfaces.

Amend #5
- Revert changes to interfaces in *Operation
- Sorted interfaces in same order for consistency (because of the chaining of interfaces, fluent methods must be called in order).

Co-authored-by: mikereiche <[email protected]>

* DATACOUCH-588 - after cherry-pick, remove reference to 4.2 method deleteAllById().

Original pull request #1040

Author: mikereiche

pom.xml

@@ -197,6 +197,14 @@
             <version>${kotlin}</version>
             <scope>test</scope>
         </dependency>
+
+        <dependency>
+            <groupId>org.awaitility</groupId>
+            <artifactId>awaitility</artifactId>
+            <version>4.0.3</version>
+            <scope>test</scope>
+        </dependency>
+
     </dependencies>
 
     <repositories>

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

@@ -18,14 +18,17 @@
 import java.util.Collection;
 import java.util.Map;
 
+import org.springframework.data.couchbase.core.support.OneAndAllExists;
+import org.springframework.data.couchbase.core.support.WithCollection;
+
 public interface ExecutableExistsByIdOperation {
 
 	/**
 	 * Checks if the document exists in the bucket.
 	 */
 	ExecutableExistsById existsById();
 
-	interface TerminatingExistsById {
+	interface TerminatingExistsById extends OneAndAllExists {
 
 		/**
 		 * Performs the operation on the ID given.
@@ -45,7 +48,7 @@ interface TerminatingExistsById {
 
 	}
 
-	interface ExistsByIdWithCollection extends TerminatingExistsById {
+	interface ExistsByIdWithCollection extends TerminatingExistsById, WithCollection {
 
 		/**
 		 * Allows to specify a different collection than the default one configured.

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

@@ -19,12 +19,15 @@
 import java.util.Optional;
 import java.util.stream.Stream;
 
-import com.couchbase.client.java.analytics.AnalyticsScanConsistency;
-import com.couchbase.client.java.query.QueryScanConsistency;
 import org.springframework.dao.IncorrectResultSizeDataAccessException;
 import org.springframework.data.couchbase.core.query.AnalyticsQuery;
+import org.springframework.data.couchbase.core.support.OneAndAll;
+import org.springframework.data.couchbase.core.support.WithAnalyticsConsistency;
+import org.springframework.data.couchbase.core.support.WithAnalyticsQuery;
 import org.springframework.lang.Nullable;
 
+import com.couchbase.client.java.analytics.AnalyticsScanConsistency;
+
 public interface ExecutableFindByAnalyticsOperation {
 
 	/**
@@ -34,7 +37,7 @@ public interface ExecutableFindByAnalyticsOperation {
 	 */
 	<T> ExecutableFindByAnalytics<T> findByAnalytics(Class<T> domainType);
 
-	interface TerminatingFindByAnalytics<T> {
+	interface TerminatingFindByAnalytics<T> extends OneAndAll<T> {
 
 		/**
 		 * Get exactly zero or one result.
@@ -102,7 +105,7 @@ default Optional<T> first() {
 
 	}
 
-	interface FindByAnalyticsWithQuery<T> extends TerminatingFindByAnalytics<T> {
+	interface FindByAnalyticsWithQuery<T> extends TerminatingFindByAnalytics<T>, WithAnalyticsQuery<T> {
 
 		/**
 		 * Set the filter for the analytics query to be used.
@@ -114,17 +117,30 @@ interface FindByAnalyticsWithQuery<T> extends TerminatingFindByAnalytics<T> {
 
 	}
 
+	@Deprecated
 	interface FindByAnalyticsConsistentWith<T> extends FindByAnalyticsWithQuery<T> {
 
 		/**
 		 * Allows to override the default scan consistency.
 		 *
 		 * @param scanConsistency the custom scan consistency to use for this analytics query.
 		 */
+		@Deprecated
 		FindByAnalyticsWithQuery<T> consistentWith(AnalyticsScanConsistency scanConsistency);
 
 	}
 
-	interface ExecutableFindByAnalytics<T> extends FindByAnalyticsConsistentWith<T> {}
+	interface FindByAnalyticsWithConsistency<T> extends FindByAnalyticsConsistentWith<T>, WithAnalyticsConsistency<T> {
+
+		/**
+		 * Allows to override the default scan consistency.
+		 *
+		 * @param scanConsistency the custom scan consistency to use for this analytics query.
+		 */
+		FindByAnalyticsConsistentWith<T> withConsistency(AnalyticsScanConsistency scanConsistency);
+
+	}
+
+	interface ExecutableFindByAnalytics<T> extends FindByAnalyticsWithConsistency<T> {}
 
 }

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

@@ -15,11 +15,10 @@
  */
 package org.springframework.data.couchbase.core;
 
-import org.springframework.data.couchbase.core.ReactiveFindByAnalyticsOperationSupport.ReactiveFindByAnalyticsSupport;
-
 import java.util.List;
 import java.util.stream.Stream;
 
+import org.springframework.data.couchbase.core.ReactiveFindByAnalyticsOperationSupport.ReactiveFindByAnalyticsSupport;
 import org.springframework.data.couchbase.core.query.AnalyticsQuery;
 
 import com.couchbase.client.java.analytics.AnalyticsScanConsistency;
@@ -79,10 +78,16 @@ public TerminatingFindByAnalytics<T> matching(final AnalyticsQuery query) {
 		}
 
 		@Override
+		@Deprecated
 		public FindByAnalyticsWithQuery<T> consistentWith(final AnalyticsScanConsistency scanConsistency) {
 			return new ExecutableFindByAnalyticsSupport<>(template, domainType, query, scanConsistency);
 		}
 
+		@Override
+		public FindByAnalyticsWithConsistency<T> withConsistency(final AnalyticsScanConsistency scanConsistency) {
+			return new ExecutableFindByAnalyticsSupport<>(template, domainType, query, scanConsistency);
+		}
+
 		@Override
 		public Stream<T> stream() {
 			return reactiveSupport.all().toStream();

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

@@ -17,6 +17,10 @@
 
 import java.util.Collection;
 
+import org.springframework.data.couchbase.core.support.OneAndAllId;
+import org.springframework.data.couchbase.core.support.WithCollection;
+import org.springframework.data.couchbase.core.support.WithProjectionId;
+
 public interface ExecutableFindByIdOperation {
 
 	/**
@@ -26,7 +30,7 @@ public interface ExecutableFindByIdOperation {
 	 */
 	<T> ExecutableFindById<T> findById(Class<T> domainType);
 
-	interface TerminatingFindById<T> {
+	interface TerminatingFindById<T> extends OneAndAllId<T> {
 
 		/**
 		 * Finds one document based on the given ID.
@@ -46,7 +50,7 @@ interface TerminatingFindById<T> {
 
 	}
 
-	interface FindByIdWithCollection<T> extends TerminatingFindById<T> {
+	interface FindByIdWithCollection<T> extends TerminatingFindById<T>, WithCollection<T> {
 
 		/**
 		 * Allows to specify a different collection than the default one configured.
@@ -57,7 +61,7 @@ interface FindByIdWithCollection<T> extends TerminatingFindById<T> {
 
 	}
 
-	interface FindByIdWithProjection<T> extends FindByIdWithCollection<T> {
+	interface FindByIdWithProjection<T> extends FindByIdWithCollection<T>, WithProjectionId<T> {
 
 		/**
 		 * Load only certain fields for the document.

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

@@ -15,12 +15,11 @@
  */
 package org.springframework.data.couchbase.core;
 
-import org.springframework.data.couchbase.core.ReactiveFindByIdOperationSupport.ReactiveFindByIdSupport;
-
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
 
+import org.springframework.data.couchbase.core.ReactiveFindByIdOperationSupport.ReactiveFindByIdSupport;
 import org.springframework.util.Assert;
 
 public class ExecutableFindByIdOperationSupport implements ExecutableFindByIdOperation {

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

@@ -21,6 +21,13 @@
 
 import org.springframework.dao.IncorrectResultSizeDataAccessException;
 import org.springframework.data.couchbase.core.query.Query;
+import org.springframework.data.couchbase.core.query.QueryCriteriaDefinition;
+import org.springframework.data.couchbase.core.support.OneAndAll;
+import org.springframework.data.couchbase.core.support.WithCollection;
+import org.springframework.data.couchbase.core.support.WithConsistency;
+import org.springframework.data.couchbase.core.support.WithDistinct;
+import org.springframework.data.couchbase.core.support.WithProjection;
+import org.springframework.data.couchbase.core.support.WithQuery;
 import org.springframework.lang.Nullable;
 
 import com.couchbase.client.java.query.QueryScanConsistency;
@@ -34,7 +41,7 @@ public interface ExecutableFindByQueryOperation {
 	 */
 	<T> ExecutableFindByQuery<T> findByQuery(Class<T> domainType);
 
-	interface TerminatingFindByQuery<T> {
+	interface TerminatingFindByQuery<T> extends OneAndAll<T> {
 		/**
 		 * Get exactly zero or one result.
 		 *
@@ -107,7 +114,7 @@ default Optional<T> first() {
 	 * @author Christoph Strobl
 	 * @since 2.0
 	 */
-	interface FindByQueryWithQuery<T> extends TerminatingFindByQuery<T> {
+	interface FindByQueryWithQuery<T> extends TerminatingFindByQuery<T>, WithQuery<T> {
 
 		/**
 		 * Set the filter for the query to be used.
@@ -117,30 +124,90 @@ interface FindByQueryWithQuery<T> extends TerminatingFindByQuery<T> {
 		 */
 		TerminatingFindByQuery<T> matching(Query query);
 
+		/**
+		 * Set the filter {@link QueryCriteriaDefinition criteria} to be used.
+		 *
+		 * @param criteria must not be {@literal null}.
+		 * @return new instance of {@link ExecutableFindByQuery}.
+		 * @throws IllegalArgumentException if criteria is {@literal null}.
+		 */
+		default TerminatingFindByQuery<T> matching(QueryCriteriaDefinition criteria) {
+			return matching(Query.query(criteria));
+		}
+
+	}
+
+	interface FindByQueryInCollection<T> extends FindByQueryWithQuery<T>, WithCollection<T> {
+
+		/**
+		 * Allows to override the default scan consistency.
+		 *
+		 * @param collection the collection to use for this query.
+		 */
+		FindByQueryWithQuery<T> inCollection(String collection);
+
 	}
 
-	interface FindByQueryConsistentWith<T> extends FindByQueryWithQuery<T> {
+	@Deprecated
+	interface FindByQueryConsistentWith<T> extends FindByQueryInCollection<T> {
 
 		/**
 		 * Allows to override the default scan consistency.
 		 *
 		 * @param scanConsistency the custom scan consistency to use for this query.
 		 */
-		FindByQueryConsistentWith<T> consistentWith(QueryScanConsistency scanConsistency);
+		@Deprecated
+		FindByQueryInCollection<T> consistentWith(QueryScanConsistency scanConsistency);
 
 	}
 
-	interface FindByQueryInCollection<T> extends FindByQueryConsistentWith<T> {
+	interface FindByQueryWithConsistency<T> extends FindByQueryConsistentWith<T>, WithConsistency<T> {
 
 		/**
 		 * Allows to override the default scan consistency.
 		 *
-		 * @param collection the collection to use for this query.
+		 * @param scanConsistency the custom scan consistency to use for this query.
+		 */
+		FindByQueryConsistentWith<T> withConsistency(QueryScanConsistency scanConsistency);
+
+	}
+
+	/**
+	 * Result type override (Optional).
+	 */
+	interface FindByQueryWithProjection<T> extends FindByQueryWithConsistency<T> {
+
+		/**
+		 * Define the target type fields should be mapped to. <br />
+		 * Skip this step if you are anyway only interested in the original domain type.
+		 *
+		 * @param returnType must not be {@literal null}.
+		 * @return new instance of {@link FindByQueryWithProjection}.
+		 * @throws IllegalArgumentException if returnType is {@literal null}.
+		 */
+		<R> FindByQueryWithConsistency<R> as(Class<R> returnType);
+	}
+
+	/**
+	 * Distinct Find support.
+	 */
+	interface FindByQueryWithDistinct<T> extends FindByQueryWithProjection<T>, WithDistinct<T> {
+
+		/**
+		 * Finds the distinct values for a specified {@literal field} across a single collection
+		 *
+		 * @param distinctFields name of the field. Must not be {@literal null}.
+		 * @return new instance of {@link ExecutableFindByQuery}.
+		 * @throws IllegalArgumentException if field is {@literal null}.
 		 */
-		FindByQueryInCollection<T> inCollection(String collection);
+		FindByQueryWithProjection<T> distinct(String[] distinctFields);
 
 	}
 
-	interface ExecutableFindByQuery<T> extends FindByQueryInCollection<T> {}
+	/**
+	 * {@link ExecutableFindByQuery} provides methods for constructing lookup operations in a fluent way.
+	 */
+
+	interface ExecutableFindByQuery<T> extends FindByQueryWithDistinct<T> {}
 
 }