feat: add stream methods for Page

gax-java/gax/clirr-ignored-differences.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- see http://www.mojohaus.org/clirr-maven-plugin/examples/ignored-differences.html -->
+<differences>
+  <difference>
+    <differenceType>7012</differenceType>
+    <className>com/google/api/gax/paging/Page</className>
+    <method>* stream*(*)</method>
+  </difference>
+</differences>

gax-java/gax/src/main/java/com/google/api/gax/paging/Page.java

@@ -29,6 +29,9 @@
  */
 package com.google.api.gax.paging;
 
+import java.util.stream.Stream;
+import java.util.stream.StreamSupport;
+
 /**
  * A Page object wraps an API list method response.
  *
@@ -52,12 +55,26 @@ public interface Page<ResourceT> {
   Page<ResourceT> getNextPage();
 
   /**
-   * Returns an iterable that traverses all of the elements of the underlying data source. The data
-   * is fetched lazily page by page, where each page may contain multiple elements. A new page is
+   * Returns an iterable that traverses all the elements of the underlying data source. The data is
+   * fetched lazily page by page, where each page may contain multiple elements. A new page is
    * fetched whenever the elements of any particular page are exhausted.
    */
   Iterable<ResourceT> iterateAll();
 
   /** Returns an iterable over the elements in this page. */
   Iterable<ResourceT> getValues();
+
+  /**
+   * Returns a stream that traverses all the elements of the underlying data source. The data is
+   * fetched lazily page by page, where each page may contain multiple elements. A new page is
+   * fetched whenever the elements of any particular page are exhausted.
+   */
+  default Stream<ResourceT> streamAll() {
+    return StreamSupport.stream(iterateAll().spliterator(), false);
+  }
+
+  /** Returns a stream over the elements in this page. */
+  default Stream<ResourceT> streamValues() {
+    return StreamSupport.stream(getValues().spliterator(), false);
+  }
 }

gax-java/gax/src/test/java/com/google/api/gax/rpc/PagingTest.java

@@ -133,6 +133,54 @@ public void pagedByPage() {
     Truth.assertThat(requestCapture.getAllValues()).containsExactly(0, 2, 4).inOrder();
   }
 
+  @Test
+  public void streamedByPage() {
+    ArgumentCaptor<Integer> requestCapture = ArgumentCaptor.forClass(Integer.class);
+    Mockito.when(callIntList.futureCall(requestCapture.capture(), Mockito.any()))
+        .thenReturn(ApiFutures.immediateFuture(Arrays.asList(0, 1, 2)))
+        .thenReturn(ApiFutures.immediateFuture(Arrays.asList(3, 4)))
+        .thenReturn(ApiFutures.immediateFuture(Collections.emptyList()));
+
+    Page<Integer> page =
+        FakeCallableFactory.createPagedCallable(
+                callIntList,
+                PagedCallSettings.newBuilder(new ListIntegersPagedResponseFactory()).build(),
+                clientContext)
+            .call(0)
+            .getPage();
+
+    Truth.assertThat(page.streamValues().count()).isEqualTo(3);
+    Truth.assertThat(page.hasNextPage()).isTrue();
+
+    page = page.getNextPage();
+    Truth.assertThat(page.streamValues().count()).isEqualTo(2);
+    Truth.assertThat(page.hasNextPage()).isTrue();
+
+    page = page.getNextPage();
+    Truth.assertThat(page.streamValues().count()).isEqualTo(0);
+    Truth.assertThat(page.hasNextPage()).isFalse();
+    Truth.assertThat(page.getNextPage()).isNull();
+  }
+
+  @Test
+  public void streamedAll() {
+    ArgumentCaptor<Integer> requestCapture = ArgumentCaptor.forClass(Integer.class);
+    Mockito.when(callIntList.futureCall(requestCapture.capture(), Mockito.any()))
+        .thenReturn(ApiFutures.immediateFuture(Arrays.asList(0, 1, 2)))
+        .thenReturn(ApiFutures.immediateFuture(Arrays.asList(3, 4)))
+        .thenReturn(ApiFutures.immediateFuture(Collections.emptyList()));
+
+    Page<Integer> page =
+        FakeCallableFactory.createPagedCallable(
+                callIntList,
+                PagedCallSettings.newBuilder(new ListIntegersPagedResponseFactory()).build(),
+                clientContext)
+            .call(0)
+            .getPage();
+
+    Truth.assertThat(page.streamAll().count()).isEqualTo(5);
+  }
+
   @Test
   public void pagedByFixedSizeCollection() {
     ArgumentCaptor<Integer> requestCapture = ArgumentCaptor.forClass(Integer.class);

showcase/gapic-showcase/src/test/java/com/google/showcase/v1beta1/it/ITStreams.java

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * 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 com.google.showcase.v1beta1.it;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+import com.google.api.client.http.javanet.NetHttpTransport;
+import com.google.api.gax.core.NoCredentialsProvider;
+import com.google.api.gax.paging.Page;
+import com.google.showcase.v1beta1.IdentityClient;
+import com.google.showcase.v1beta1.IdentityClient.ListUsersPagedResponse;
+import com.google.showcase.v1beta1.IdentitySettings;
+import com.google.showcase.v1beta1.ListUsersRequest;
+import com.google.showcase.v1beta1.User;
+import java.io.IOException;
+import java.security.GeneralSecurityException;
+import java.util.Random;
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+
+public class ITStreams {
+  private IdentityClient client;
+
+  @Before
+  public void initClient() throws GeneralSecurityException, IOException {
+    IdentitySettings identitySettings =
+        IdentitySettings.newHttpJsonBuilder()
+            .setCredentialsProvider(NoCredentialsProvider.create())
+            .setTransportChannelProvider(
+                IdentitySettings.defaultHttpJsonTransportProviderBuilder()
+                    .setHttpTransport(
+                        new NetHttpTransport.Builder().doNotValidateCertificate().build())
+                    .setEndpoint("http://localhost:7469")
+                    .build())
+            .build();
+    client = IdentityClient.create(identitySettings);
+    create100Users();
+  }
+
+  @After
+  public void destroyClient() {
+    ListUsersRequest request = ListUsersRequest.newBuilder()
+        .setPageSize(100)
+        .build();
+    // Delete all users before destroy client to
+    // avoid interference between tests.
+    client
+        .listUsers(request)
+        .getPage()
+        .streamAll()
+        .forEach(user -> client.deleteUser(user.getName()));
+    client.close();
+  }
+
+  @Test
+  public void verifyStreamAll() {
+    ListUsersRequest request = ListUsersRequest.newBuilder()
+        .setPageSize(50)
+        .build();
+    ListUsersPagedResponse response = client.listUsers(request);
+    assertEquals(100, response.getPage().streamAll().count());
+  }
+
+  @Test
+  public void verifyStreamValues() {
+    ListUsersRequest firstRequest = ListUsersRequest.newBuilder()
+        .setPageSize(50)
+        .build();
+    Page<User> firstPage = client.listUsers(firstRequest).getPage();
+    assertEquals(50, firstPage.streamValues().count());
+    assertTrue(firstPage.hasNextPage());
+
+    ListUsersRequest secondRequest = ListUsersRequest.newBuilder()
+        .setPageSize(50)
+        .setPageToken(firstPage.getNextPageToken())
+        .build();
+    Page<User> secondPage = client.listUsers(secondRequest).getPage();
+    assertEquals(50, secondPage.streamValues().count());
+    assertFalse(secondPage.hasNextPage());
+  }
+
+  private void create100Users() {
+    Random random = new Random();
+    for (int i = 0; i < 100; i++) {
+      String randomName = String.format("random%s", random.nextInt());
+      String randomEmail = String.format("%[email protected]", randomName);
+      client.createUser(randomName, randomEmail);
+    }
+  }
+}