Apache
/
jclouds
mirror of https://github.com/apache/jclouds.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1387 from rackspace/pagediterable-javadoc 

Updated Javadoc for PagedIterable.
This commit is contained in:
Everett Toews 2013-03-06 13:38:06 -08:00
parent c31145e42e bbede1bd0a
commit 46f9219272
1 changed files with 23 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
core/src/main/java/org/jclouds/collect/PagedIterable.java
View File

@ -27,31 +27,33 @@ import com.google.common.collect.UnmodifiableIterator;
/**
* Extends {@link FluentIterable} allowing you to lazily advance through
* sequence of pages in a resultset. Typically used in apis that return only a
* sequence of pages in a result set. Typically used in APIs that return only a
* certain number of records at a time.
*
* Simplest usage is to employ the {@link #concat} convenience function, and one
* of the methods from {@link FluentIterable}.
*
* </p>
* Simplest usage is to employ the {@link #concat} convenience function, and iterate.
* </p>
* <pre>
* // pull in new pages until it we see something interesting.
* Optional<StorageMetadata> firstInterestingBlob = blobstore
* .list(// options //)
* .concat()
* .firstMatch(isInterestingBlob());
* </pre>
* FluentIterable<? extends Image> images = imageApi.listInDetail().concat();
*
* For those seeking manual control of page advances, don't use concat, and
* instead look at the value of {@link IterableWithMarker#nextToken}.
*
* <pre>
* PagedIterator<StorageMetadata> blobs = blobstore.list(...).iterator();
* while (blobs.hasNext()) {
* IterableWithMarker<StorageMetadata> page = blobs.next();
* ProcessedResults results = process(page);
* if (results.shouldBeBookmarked() && page.nextMarker().isPresent()) {
* saveBookmark(page.nextMarker().get());
* for (Image image: images) {
* System.out.println(image);
* }
* </pre>
* </p>
* Another usage is to employ the {@link #concat} convenience function, and one
* of the methods from {@link FluentIterable}.
* </p>
* <pre>
* Optional<? extends Image> image = imageApi.listInDetail().concat().firstMatch(isInterestingImage());
* System.out.println(image.orNull());
* ...
* private static Predicate<Image> isInterestingImage() {
* return new Predicate<Image>() {
* {@literal @}Override
* public boolean apply(Image image) {
* return image.getName().startsWith("Arch");
* }
* };
* }
* </pre>
*