Rename ListResult and move to core module

gcloud-java-storage/src/main/java/com/google/gcloud/storage/ListResult.java → gcloud-java-core/src/main/java/com/google/gcloud/Page.java

@@ -14,21 +14,38 @@
  * limitations under the License.
  */
 
-package com.google.gcloud.storage;
+package com.google.gcloud;
 
 /**
- * Interface for Google Cloud storage list result.
+ * Interface for Google Cloud paginated results.
+ *
+ * <p>
+ * A typical {@code Page} usage:
+ * <pre> {@code
+ * Page<T> page = ...; // get a Page<T> instance
+ * while (page != null) {
+ *   for (T value : page.values()) {
+ *     // do something with value
+ *   }
+ *   page = page.nextPage();
+ * }
+ * }</pre>
  */
-public interface ListResult<T> extends Iterable<T> {
+public interface Page<T> {
+
+  /**
+   * Returns the values contained in this page.
+   */
+  Iterable<T> values();
 
   /**
    * Returns the cursor for the nextPage or {@code null} if no more results.
    */
   String nextPageCursor();
 
   /**
-   * Returns the results of the nextPage or {@code null} if no more result.
+   * Returns the next page of results or {@code null} if no more result.
    */
-  ListResult<T> nextPage();
+  Page<T> nextPage();
 
 }

gcloud-java-storage/src/main/java/com/google/gcloud/storage/BaseListResult.java → gcloud-java-core/src/main/java/com/google/gcloud/PageImpl.java

@@ -14,63 +14,66 @@
  * limitations under the License.
  */
 
-package com.google.gcloud.storage;
+package com.google.gcloud;
 
 import java.io.Serializable;
 import java.util.Collections;
-import java.util.Iterator;
 import java.util.Objects;
 
 /**
- * Base implementation for Google Cloud storage list result.
+ * Base implementation for Google Cloud paginated results.
  */
-public class BaseListResult<T extends Serializable> implements ListResult<T>, Serializable {
+public class PageImpl<T> implements Page<T>, Serializable {
 
-  private static final long serialVersionUID = -6937287874908527950L;
+  private static final long serialVersionUID = 3914827379823557934L;
 
   private final String cursor;
   private final Iterable<T> results;
   private final NextPageFetcher<T> pageFetcher;
 
-  public interface NextPageFetcher<T extends Serializable> extends Serializable {
-    ListResult<T> nextPage();
+  public interface NextPageFetcher<T> extends Serializable {
+    Page<T> nextPage();
   }
 
-  public BaseListResult(NextPageFetcher<T> pageFetcher, String cursor, Iterable<T> results) {
+  /**
+   * Creates a {@code PageImpl} object. In order for the object to be serializable the {@code
+   * results} parameter must be serializable.
+   */
+  public PageImpl(NextPageFetcher<T> pageFetcher, String cursor, Iterable<T> results) {
     this.pageFetcher = pageFetcher;
     this.cursor = cursor;
     this.results = results;
   }
 
+  @Override
+  public Iterable<T> values() {
+    return results == null ? Collections.EMPTY_LIST : results;
+  }
+
   @Override
   public String nextPageCursor() {
     return cursor;
   }
 
   @Override
-  public ListResult<T> nextPage() {
+  public Page<T> nextPage() {
     if (cursor == null || pageFetcher == null) {
       return null;
     }
     return pageFetcher.nextPage();
   }
 
-  @Override
-  public Iterator<T> iterator() {
-    return results == null ? Collections.<T>emptyIterator() : results.iterator();
-  }
-
   @Override
   public int hashCode() {
     return Objects.hash(cursor, results);
   }
 
   @Override
   public boolean equals(Object obj) {
-    if (!(obj instanceof BaseListResult)) {
+    if (!(obj instanceof PageImpl)) {
       return false;
     }
-    BaseListResult<?> other = (BaseListResult<?>) obj;
+    PageImpl<?> other = (PageImpl<?>) obj;
     return Objects.equals(cursor, other.cursor)
         && Objects.equals(results, other.results);
   }

gcloud-java-storage/src/test/java/com/google/gcloud/storage/BaseListResultTest.java → gcloud-java-core/src/test/java/com/google/gcloud/PageImplTest.java

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-package com.google.gcloud.storage;
+package com.google.gcloud;
 
 import static org.junit.Assert.assertEquals;
 
@@ -24,24 +24,23 @@
 
 import java.util.Collections;
 
-public class BaseListResultTest {
+public class PageImplTest {
 
   @Test
-  public void testListResult() throws Exception {
+  public void testPage() throws Exception {
     ImmutableList<String> values = ImmutableList.of("1", "2");
-    final BaseListResult<String> nextResult =
-        new BaseListResult<>(null, "c", Collections.<String>emptyList());
-    BaseListResult.NextPageFetcher<String> fetcher = new BaseListResult.NextPageFetcher<String>() {
+    final PageImpl<String> nextResult =
+        new PageImpl<>(null, "c", Collections.<String>emptyList());
+    PageImpl.NextPageFetcher<String> fetcher = new PageImpl.NextPageFetcher<String>() {
 
       @Override
-      public BaseListResult<String> nextPage() {
+      public PageImpl<String> nextPage() {
         return nextResult;
       }
     };
-    BaseListResult<String> result = new BaseListResult<>(fetcher, "c", values);
+    PageImpl<String> result = new PageImpl<>(fetcher, "c", values);
     assertEquals(nextResult, result.nextPage());
     assertEquals("c", result.nextPageCursor());
-    assertEquals(values, ImmutableList.copyOf(result.iterator()));
-
+    assertEquals(values, ImmutableList.copyOf(result.values().iterator()));
   }
 }

gcloud-java-examples/src/main/java/com/google/gcloud/examples/StorageExample.java

@@ -18,6 +18,7 @@
 
 import com.google.gcloud.AuthCredentials;
 import com.google.gcloud.AuthCredentials.ServiceAccountAuthCredentials;
+import com.google.gcloud.Page;
 import com.google.gcloud.RetryParams;
 import com.google.gcloud.spi.StorageRpc.Tuple;
 import com.google.gcloud.storage.Blob;
@@ -213,8 +214,12 @@ String parse(String... args) {
     public void run(Storage storage, String bucketName) {
       if (bucketName == null) {
         // list buckets
-        for (BucketInfo b : storage.list()) {
-          System.out.println(b);
+        Page<BucketInfo> bucketPage = storage.list();
+        while (bucketPage != null) {
+          for (BucketInfo b : bucketPage.values()) {
+            System.out.println(b);
+          }
+          bucketPage = bucketPage.nextPage();
         }
       } else {
         // list a bucket's blobs
@@ -223,8 +228,12 @@ public void run(Storage storage, String bucketName) {
           System.out.println("No such bucket");
           return;
         }
-        for (Blob b : bucket.list()) {
-          System.out.println(b.info());
+        Page<Blob> blobPage = bucket.list();
+        while (blobPage != null) {
+          for (Blob b : blobPage.values()) {
+            System.out.println(b.info());
+          }
+          blobPage = blobPage.nextPage();
         }
       }
     }

gcloud-java-storage/src/main/java/com/google/gcloud/storage/Bucket.java

@@ -19,16 +19,24 @@
 import static com.google.common.base.Preconditions.checkArgument;
 import static com.google.common.base.Preconditions.checkNotNull;
 
+import com.google.common.base.Function;
 import com.google.common.base.MoreObjects;
+import com.google.common.collect.Iterators;
+import com.google.gcloud.PageImpl;
+import com.google.gcloud.Page;
 import com.google.gcloud.storage.Storage.BlobSourceOption;
 import com.google.gcloud.storage.Storage.BlobTargetOption;
 import com.google.gcloud.storage.Storage.BlobWriteOption;
 import com.google.gcloud.storage.Storage.BucketSourceOption;
 import com.google.gcloud.storage.Storage.BucketTargetOption;
-import java.io.InputStream;
 
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.ObjectInputStream;
+import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.Collections;
+import java.util.Iterator;
 import java.util.List;
 import java.util.Objects;
 
@@ -46,6 +54,71 @@ public final class Bucket {
   private final Storage storage;
   private final BucketInfo info;
 
+  private static class BlobPageFetcher implements PageImpl.NextPageFetcher<Blob> {
+
+    private static final long serialVersionUID = 3221100177471323801L;
+
+    private final StorageOptions options;
+    private final Page<BlobInfo> infoPage;
+
+    BlobPageFetcher(StorageOptions options, Page<BlobInfo> infoPage) {
+      this.options = options;
+      this.infoPage = infoPage;
+    }
+
+    @Override
+    public Page<Blob> nextPage() {
+      Page<BlobInfo> nextInfoPage = infoPage.nextPage();
+      return new PageImpl<Blob>(new BlobPageFetcher(options, nextInfoPage),
+          nextInfoPage.nextPageCursor(), new LazyBlobIterable(options, nextInfoPage.values()));
+    }
+  }
+
+  private static class LazyBlobIterable implements Iterable<Blob>, Serializable {
+
+    private static final long serialVersionUID = -3092290247725378832L;
+
+    private final StorageOptions options;
+    private Iterable<BlobInfo> infoIterable;
+    private transient Storage storage;
+
+    public LazyBlobIterable(StorageOptions options, Iterable<BlobInfo> infoIterable) {
+      this.options = options;
+      this.infoIterable = infoIterable;
+      this.storage = options.service();
+    }
+
+    private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
+      in.defaultReadObject();
+      this.storage = options.service();
+    }
+
+    @Override
+    public Iterator<Blob> iterator() {
+      return Iterators.transform(infoIterable.iterator(), new Function<BlobInfo, Blob>() {
+        @Override
+        public Blob apply(BlobInfo blobInfo) {
+          return new Blob(storage, blobInfo);
+        }
+      });
+    }
+
+    @Override
+    public int hashCode() {
+      return Objects.hash(options, infoIterable);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+      if (!(obj instanceof LazyBlobIterable)) {
+        return false;
+      }
+      LazyBlobIterable other = (LazyBlobIterable) obj;
+      return Objects.equals(options, other.options)
+          && Objects.equals(infoIterable, other.infoIterable);
+    }
+  }
+
   /**
    * Constructs a {@code Bucket} object for the provided {@code BucketInfo}. The storage service is
    * used to issue requests.
@@ -134,8 +207,11 @@ public boolean delete(BucketSourceOption... options) {
    * @param options options for listing blobs
    * @throws StorageException upon failure
    */
-  public ListResult<Blob> list(Storage.BlobListOption... options) {
-    return new BlobListResult(storage, storage.list(info.name(), options));
+  public Page<Blob> list(Storage.BlobListOption... options) {
+    Page<BlobInfo> infoPage = storage.list(info.name(), options);
+    StorageOptions storageOptions = storage.options();
+    return new PageImpl<Blob>(new BlobPageFetcher(storageOptions, infoPage),
+        infoPage.nextPageCursor(), new LazyBlobIterable(storageOptions, infoPage.values()));
   }
 
   /**