Enable support for structured ProjectionEntity queries

Author: dmitrykuzmin

datastore/src/main/java/io/spine/server/storage/datastore/DatastoreWrapper.java

@@ -266,16 +266,18 @@ public Entity read(Key key) {
      *
      * @param query
      *         {@link Query} to execute upon the Datastore
+     * @param <E>
+     *         the type of queried entities
      * @return results fo the query as a lazily evaluated {@link Iterator}
      * @see DatastoreReader#run(Query)
      */
-    public DsQueryIterator read(StructuredQuery<Entity> query) {
+    public <E extends BaseEntity<?>> DsQueryIterator<E> read(StructuredQuery<E> query) {
         Namespace namespace = currentNamespace();
-        StructuredQuery<Entity> queryWithNamespace =
+        StructuredQuery<E> queryWithNamespace =
                 query.toBuilder()
                      .setNamespace(namespace.getValue())
                      .build();
-        DsQueryIterator result = new DsQueryIterator(queryWithNamespace, actor);
+        DsQueryIterator<E> result = new DsQueryIterator<>(queryWithNamespace, actor);
         return result;
     }
 
@@ -292,11 +294,13 @@ public DsQueryIterator read(StructuredQuery<Entity> query) {
      *         {@link Query} to execute upon the Datastore
      * @param pageSize
      *         a non-zero number of elements to be returned per a single read from Datastore
+     * @param <E>
+     *         the type of queried entities
      * @return results fo the query as a lazily evaluated {@link Iterator}
      * @throws IllegalArgumentException
      *         if the provided {@linkplain StructuredQuery#getLimit() query includes a limit}
      */
-    Iterator<Entity> readAll(StructuredQuery<Entity> query, int pageSize) {
+    <E extends BaseEntity<?>> Iterator<E> readAll(StructuredQuery<E> query, int pageSize) {
         return readAllPageByPage(query, pageSize);
     }
 
@@ -311,11 +315,13 @@ Iterator<Entity> readAll(StructuredQuery<Entity> query, int pageSize) {
      *
      * @param query
      *         {@link Query} to execute upon the Datastore
+     * @param <E>
+     *         the type of queried entities
      * @return results fo the query as a lazily evaluated {@link Iterator}
      * @throws IllegalArgumentException
      *         if the provided {@linkplain StructuredQuery#getLimit() query includes a limit}
      */
-    Iterator<Entity> readAll(StructuredQuery<Entity> query) {
+    <E extends BaseEntity<?>> Iterator<E> readAll(StructuredQuery<E> query) {
         return readAllPageByPage(query, null);
     }
 
@@ -333,26 +339,29 @@ Iterator<Entity> readAll(StructuredQuery<Entity> query) {
      * @param pageSize
      *         a non-zero number of elements to be returned per a single read from Datastore;
      *         if {@code null} the page size will be dictated by the Datastore
+     * @param <E>
+     *         the type of queried entities
      * @return results fo the query as a lazily evaluated {@link Iterator}
      * @throws IllegalArgumentException
      *         if the provided {@linkplain StructuredQuery#getLimit() query includes a limit} or
      *         the provided {@code batchSize} is 0
      */
-    private Iterator<Entity> readAllPageByPage(StructuredQuery<Entity> query,
-                                               @Nullable Integer pageSize) {
+    @SuppressWarnings("unchecked") // Checked logically.
+    private <E extends BaseEntity<?>> Iterator<E>
+    readAllPageByPage(StructuredQuery<E> query, @Nullable Integer pageSize) {
         checkArgument(query.getLimit() == null,
                       "Cannot limit a number of entities for \"read all\" operation.");
         checkArgument(pageSize == null || pageSize != 0,
                       "The size of a single read operation cannot be 0.");
 
-        StructuredQuery<Entity> limitedQuery = limit(query, pageSize);
-        return stream(new DsQueryPageIterator(limitedQuery, this))
+        StructuredQuery<E> limitedQuery = limit(query, pageSize);
+        return stream(new DsQueryPageIterator<>(limitedQuery, this))
                 .flatMap(Streams::stream)
                 .iterator();
     }
 
-    private static StructuredQuery<Entity> limit(StructuredQuery<Entity> query,
-                                                 @Nullable Integer batchSize) {
+    private static <E extends BaseEntity<?>> StructuredQuery<E>
+    limit(StructuredQuery<E> query, @Nullable Integer batchSize) {
         return batchSize == null
                ? query
                : query.toBuilder()

datastore/src/main/java/io/spine/server/storage/datastore/DsQueryIterator.java

@@ -20,9 +20,9 @@
 
 package io.spine.server.storage.datastore;
 
+import com.google.cloud.datastore.BaseEntity;
 import com.google.cloud.datastore.Cursor;
 import com.google.cloud.datastore.DatastoreReaderWriter;
-import com.google.cloud.datastore.Entity;
 import com.google.cloud.datastore.QueryResults;
 import com.google.cloud.datastore.StructuredQuery;
 import com.google.common.collect.UnmodifiableIterator;
@@ -44,18 +44,21 @@
  * <p>A call to {@link #next() next()} may not cause a Datastore query.
  *
  * <p>The {@link #remove() remove()} method throws an {@link UnsupportedOperationException}.
+ *
+ * @param <E>
+ *         the type of queried entities
  */
-final class DsQueryIterator extends UnmodifiableIterator<Entity> {
+final class DsQueryIterator<E extends BaseEntity<?>> extends UnmodifiableIterator<E> {
 
-    private final StructuredQuery<Entity> query;
-    private final QueryResults<Entity> currentPage;
+    private final StructuredQuery<E> query;
+    private final QueryResults<E> currentPage;
 
     private final Integer limit;
     private int readCount = 0;
 
     private boolean terminated;
 
-    DsQueryIterator(StructuredQuery<Entity> query, DatastoreReaderWriter datastore) {
+    DsQueryIterator(StructuredQuery<E> query, DatastoreReaderWriter datastore) {
         super();
         this.query = query;
         this.limit = query.getLimit();
@@ -92,21 +95,21 @@ private void terminate() {
      * <p>The query is built utilizing the {@linkplain Cursor Datastore Cursor} from the current
      * query results.
      */
-    StructuredQuery<Entity> nextPageQuery() {
+    StructuredQuery<E> nextPageQuery() {
         Cursor cursorAfter = currentPage.getCursorAfter();
-        StructuredQuery<Entity> queryForMoreResults =
+        StructuredQuery<E> queryForMoreResults =
                 query.toBuilder()
                      .setStartCursor(cursorAfter)
                      .build();
         return queryForMoreResults;
     }
 
     @Override
-    public Entity next() {
+    public E next() {
         if (!hasNext()) {
             throw new NoSuchElementException("The query results Iterator is empty.");
         }
-        Entity result = currentPage.next();
+        E result = currentPage.next();
         readCount++;
         return result;
     }

datastore/src/main/java/io/spine/server/storage/datastore/DsQueryPageIterator.java

@@ -20,7 +20,7 @@
 
 package io.spine.server.storage.datastore;
 
-import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.BaseEntity;
 import com.google.cloud.datastore.StructuredQuery;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
@@ -39,15 +39,18 @@
  *
  * <p>If the limit is not specified, then the page size is determined by the Datastore
  * query restrictions.
+ *
+ * @param <E>
+ *         the type of queried entities
  */
-final class DsQueryPageIterator implements Iterator<DsQueryIterator> {
+final class DsQueryPageIterator<E extends BaseEntity<?>> implements Iterator<DsQueryIterator> {
 
     private final DatastoreWrapper datastore;
 
-    private DsQueryIterator currentPage;
-    private @Nullable DsQueryIterator nextPage;
+    private DsQueryIterator<E> currentPage;
+    private @Nullable DsQueryIterator<E> nextPage;
 
-    DsQueryPageIterator(StructuredQuery<Entity> query, DatastoreWrapper datastore) {
+    DsQueryPageIterator(StructuredQuery<E> query, DatastoreWrapper datastore) {
         this.datastore = datastore;
         this.currentPage = datastore.read(query);
     }
@@ -61,7 +64,7 @@ public boolean hasNext() {
     }
 
     @Override
-    public DsQueryIterator next() {
+    public DsQueryIterator<E> next() {
         if (nextPage == null) {
             currentPage = loadNextPage();
         } else {
@@ -74,8 +77,8 @@ public DsQueryIterator next() {
         return currentPage;
     }
 
-    private DsQueryIterator loadNextPage() {
-        StructuredQuery<Entity> nextPageQuery = currentPage.nextPageQuery();
+    private DsQueryIterator<E> loadNextPage() {
+        StructuredQuery<E> nextPageQuery = currentPage.nextPageQuery();
         return datastore.read(nextPageQuery);
     }
 }