Improve param name and doc

Author: dmitrykuzmin

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

@@ -255,29 +255,29 @@ public Entity read(Key key) {
      * <p>The Datastore may return a partial result set, so an execution of this method may
      * result in several Datastore queries.
      *
-     * <p>The limit included in the {@link StructuredQuery}, will be a maximum count of entities
+     * <p>The limit included in the {@link StructuredQuery}, will be a maximum count of objects
      * in the returned iterator.
      *
      * <p>The returned {@link DsQueryIterator} allows to {@linkplain DsQueryIterator#nextPageQuery()
-     * create a query} to the next page of entities reusing an existing cursor.
+     * create a query} to the next page of results reusing an existing cursor.
      *
      * <p>The resulting {@code Iterator} is evaluated lazily. A call to
      * {@link Iterator#remove() Iterator.remove()} causes an {@link UnsupportedOperationException}.
      *
      * @param query
      *         {@link Query} to execute upon the Datastore
-     * @param <E>
+     * @param <R>
      *         the type of queried objects
      * @return results fo the query as a lazily evaluated {@link Iterator}
      * @see DatastoreReader#run(Query)
      */
-    public <E> DsQueryIterator<E> read(StructuredQuery<E> query) {
+    public <R> DsQueryIterator<R> read(StructuredQuery<R> query) {
         Namespace namespace = currentNamespace();
-        StructuredQuery<E> queryWithNamespace =
+        StructuredQuery<R> queryWithNamespace =
                 query.toBuilder()
                      .setNamespace(namespace.getValue())
                      .build();
-        DsQueryIterator<E> result = new DsQueryIterator<>(queryWithNamespace, actor);
+        DsQueryIterator<R> result = new DsQueryIterator<>(queryWithNamespace, actor);
         return result;
     }
 
@@ -294,13 +294,13 @@ public <E> DsQueryIterator<E> read(StructuredQuery<E> 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>
+     * @param <R>
      *         the type of queried objects
      * @return results fo the query as a lazily evaluated {@link Iterator}
      * @throws IllegalArgumentException
      *         if the provided {@linkplain StructuredQuery#getLimit() query includes a limit}
      */
-    <E> Iterator<E> readAll(StructuredQuery<E> query, int pageSize) {
+    <R> Iterator<R> readAll(StructuredQuery<R> query, int pageSize) {
         return readAllPageByPage(query, pageSize);
     }
 
@@ -315,13 +315,13 @@ <E> Iterator<E> readAll(StructuredQuery<E> query, int pageSize) {
      *
      * @param query
      *         {@link Query} to execute upon the Datastore
-     * @param <E>
+     * @param <R>
      *         the type of queried objects
      * @return results fo the query as a lazily evaluated {@link Iterator}
      * @throws IllegalArgumentException
      *         if the provided {@linkplain StructuredQuery#getLimit() query includes a limit}
      */
-    <E> Iterator<E> readAll(StructuredQuery<E> query) {
+    <R> Iterator<R> readAll(StructuredQuery<R> query) {
         return readAllPageByPage(query, null);
     }
 
@@ -339,28 +339,28 @@ <E> Iterator<E> readAll(StructuredQuery<E> 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>
+     * @param <R>
      *         the type of queried objects
      * @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
      */
     @SuppressWarnings("unchecked") // Checked logically.
-    private <E> Iterator<E>
-    readAllPageByPage(StructuredQuery<E> query, @Nullable Integer pageSize) {
+    private <R> Iterator<R>
+    readAllPageByPage(StructuredQuery<R> 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<E> limitedQuery = limit(query, pageSize);
+        StructuredQuery<R> limitedQuery = limit(query, pageSize);
         return stream(new DsQueryPageIterator<>(limitedQuery, this))
                 .flatMap(Streams::stream)
                 .iterator();
     }
 
-    private static <E> StructuredQuery<E> limit(StructuredQuery<E> query,
+    private static <R> StructuredQuery<R> limit(StructuredQuery<R> query,
                                                 @Nullable Integer batchSize) {
         return batchSize == null
                ? query

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

@@ -44,20 +44,20 @@
  *
  * <p>The {@link #remove() remove()} method throws an {@link UnsupportedOperationException}.
  *
- * @param <E>
+ * @param <R>
  *         the type of queried objects
  */
-final class DsQueryIterator<E> extends UnmodifiableIterator<E> {
+final class DsQueryIterator<R> extends UnmodifiableIterator<R> {
 
-    private final StructuredQuery<E> query;
-    private final QueryResults<E> currentPage;
+    private final StructuredQuery<R> query;
+    private final QueryResults<R> currentPage;
 
     private final Integer limit;
     private int readCount = 0;
 
     private boolean terminated;
 
-    DsQueryIterator(StructuredQuery<E> query, DatastoreReaderWriter datastore) {
+    DsQueryIterator(StructuredQuery<R> query, DatastoreReaderWriter datastore) {
         super();
         this.query = query;
         this.limit = query.getLimit();
@@ -94,21 +94,21 @@ private void terminate() {
      * <p>The query is built utilizing the {@linkplain Cursor Datastore Cursor} from the current
      * query results.
      */
-    StructuredQuery<E> nextPageQuery() {
+    StructuredQuery<R> nextPageQuery() {
         Cursor cursorAfter = currentPage.getCursorAfter();
-        StructuredQuery<E> queryForMoreResults =
+        StructuredQuery<R> queryForMoreResults =
                 query.toBuilder()
                      .setStartCursor(cursorAfter)
                      .build();
         return queryForMoreResults;
     }
 
     @Override
-    public E next() {
+    public R next() {
         if (!hasNext()) {
             throw new NoSuchElementException("The query results Iterator is empty.");
         }
-        E result = currentPage.next();
+        R result = currentPage.next();
         readCount++;
         return result;
     }

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

@@ -39,17 +39,17 @@
  * <p>If the limit is not specified, then the page size is determined by the Datastore
  * query restrictions.
  *
- * @param <E>
+ * @param <R>
  *         the type of queried objects
  */
-final class DsQueryPageIterator<E> implements Iterator<DsQueryIterator> {
+final class DsQueryPageIterator<R> implements Iterator<DsQueryIterator> {
 
     private final DatastoreWrapper datastore;
 
-    private DsQueryIterator<E> currentPage;
-    private @Nullable DsQueryIterator<E> nextPage;
+    private DsQueryIterator<R> currentPage;
+    private @Nullable DsQueryIterator<R> nextPage;
 
-    DsQueryPageIterator(StructuredQuery<E> query, DatastoreWrapper datastore) {
+    DsQueryPageIterator(StructuredQuery<R> query, DatastoreWrapper datastore) {
         this.datastore = datastore;
         this.currentPage = datastore.read(query);
     }
@@ -63,7 +63,7 @@ public boolean hasNext() {
     }
 
     @Override
-    public DsQueryIterator<E> next() {
+    public DsQueryIterator<R> next() {
         if (nextPage == null) {
             currentPage = loadNextPage();
         } else {
@@ -76,8 +76,8 @@ public DsQueryIterator<E> next() {
         return currentPage;
     }
 
-    private DsQueryIterator<E> loadNextPage() {
-        StructuredQuery<E> nextPageQuery = currentPage.nextPageQuery();
+    private DsQueryIterator<R> loadNextPage() {
+        StructuredQuery<R> nextPageQuery = currentPage.nextPageQuery();
         return datastore.read(nextPageQuery);
     }
 }