feat(storage): Update list api documentation to add pagination exampl…

…es (#5397) * feat(storage): Updated list api documentation to add pagination examples * addressed PR comments * remove semicolon from kotlin code * remove semicolon from kotlin code
aws-amplify · Apr 26, 2023 · f79b0c5 · f79b0c5
1 parent 46bb723
commit f79b0c5
Showing 1 changed file with 60 additions and 23 deletions.
diff --git a/src/fragments/lib/storage/android/list.mdx b/src/fragments/lib/storage/android/list.mdx
@@ -1,28 +1,43 @@
-You can list all of the objects uploaded under a given prefix. This will list all public files:
+You can list all of the objects uploaded under a given prefix by setting the pageSize. If the pageSize is set lower than the total file size available,
+A single `Storage.list` call only returns a subset of all the files. To list all the files with multiple calls, the user can use the nextToken from the previous call response.
+
+This will list all public files:
 
 <BlockSwitcher>
 <Block name="Java">
 
 ```java
-Amplify.Storage.list("",
+StoragePagedListOptions options = StoragePagedListOptions.builder()
+    .setPageSize(1000)
+    .build();
+
+Amplify.Storage.list(
+    "",
+    options,
     result -> {
         for (StorageItem item : result.getItems()) {
             Log.i("MyAmplifyApp", "Item: " + item.getKey());
         }
+        Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
     },
-    error -> Log.e("MyAmplifyApp", "List failure", error)
+    error -> Log.e("MyAmplifyApp", "List failure", error);
 );
 ```
 
 </Block>
 <Block name="Kotlin - Callbacks">
 
 ```kotlin
-Amplify.Storage.list("",
+val options = StoragePagedListOptions.builder()
+    .setPageSize(1000)
+    .build()
+
+Amplify.Storage.list("", options,
     { result ->
         result.items.forEach { item ->
             Log.i("MyAmplifyApp", "Item: ${item.key}")
         }
+        Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}")
     },
     { Log.e("MyAmplifyApp", "List failure", it) }
 )
@@ -32,10 +47,16 @@ Amplify.Storage.list("",
 <Block name="Kotlin - Coroutines">
 
 ```kotlin
+val options = StoragePagedListOptions.builder()
+    .setPageSize(1000)
+    .build()
+
 try {
-    Amplify.Storage.list("").items.forEach {
-        Log.i("MyAmplifyApp", "Item: ${it.key}")
+    val result = Amplify.Storage.list("", options)
+    result.items.forEach {
+        Log.i("MyAmplifyApp", "Item: $it")
     }
+    Log.i("MyAmplifyApp", "next token: ${result.nextToken}")
 } catch (error: StorageException) {
     Log.e("MyAmplifyApp", "List failure", error)
 }
@@ -45,29 +66,37 @@ try {
 <Block name="RxJava">
 
 ```java
-RxAmplify.Storage.list("")
-    .subscribe(
-        result -> {
-            for (StorageItem item : result.getItems()) {
-                Log.i("MyAmplifyApp", "Item: " + item.getKey());
-            }
-        },
-        error -> Log.e("MyAmplifyApp", "List failure", error)
-    );
+StoragePagedListOptions options = StoragePagedListOptions.builder()
+        .setPageSize(1000)
+        .build();
+
+RxAmplify.Storage.list("", options)
+        .subscribe(
+            result -> {
+                for (StorageItem item : result.getItems()) {
+                    Log.i("MyAmplifyApp", "Item: " + item.getKey());
+                }
+                Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
+            },
+            error -> Log.e("MyAmplifyApp", "List failure", error);
+        );
 ```
 
 </Block>
 </BlockSwitcher>
 
+<Callout>Note: The range of pageSize can be from 1 - 1000.</Callout>
+
 You can also list private or protected files by passing options. For example, to list all protected files owned by a user identified by the ID `otherUserID`:
 
 <BlockSwitcher>
 <Block name="Java">
 
 ```java
-StorageListOptions options = StorageListOptions.builder()
+StoragePagedListOptions options = StoragePagedListOptions.builder()
     .accessLevel(StorageAccessLevel.PROTECTED)
     .targetIdentityId("otherUserID")
+    .setPageSize(1000)
     .build();
 
 Amplify.Storage.list(
@@ -77,25 +106,28 @@ Amplify.Storage.list(
         for (StorageItem item : result.getItems()) {
             Log.i("MyAmplifyApp", "Item: " + item.getKey());
         }
+        Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
     },
-    error -> Log.e("MyAmplifyApp", "List failure", error)
+    error -> Log.e("MyAmplifyApp", "List failure", error);
 );
 ```
 
 </Block>
 <Block name="Kotlin - Callbacks">
 
 ```kotlin
-val options = StorageListOptions.builder()
+val options = StoragePagedListOptions.builder()
     .accessLevel(StorageAccessLevel.PROTECTED)
     .targetIdentityId("otherUserID")
+    .setPageSize(1000)
     .build()
 
 Amplify.Storage.list("", options,
     { result ->
         result.items.forEach { item ->
             Log.i("MyAmplifyApp", "Item: ${item.key}")
         }
+        Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}")
     },
     { Log.e("MyAmplifyApp", "List failure", it) }
 )
@@ -105,15 +137,18 @@ Amplify.Storage.list("", options,
 <Block name="Kotlin - Coroutines">
 
 ```kotlin
-val options = StorageListOptions.builder()
+val options = StoragePagedListOptions.builder()
     .accessLevel(StorageAccessLevel.PROTECTED)
     .targetIdentityId("otherUserID")
+    .setPageSize(1000)
     .build()
 
 try {
-    Amplify.Storage.list("", options).items.forEach {
-        Log.i("AmplifyApplication", "Item: $it")
+    val result = Amplify.Storage.list("", options)
+    result.items.forEach {
+        Log.i("MyAmplifyApp", "Item: $it")
     }
+    Log.i("MyAmplifyApp", "next token: ${result.nextToken}")
 } catch (error: StorageException) {
     Log.e("MyAmplifyApp", "List failure", error)
 }
@@ -123,9 +158,10 @@ try {
 <Block name="RxJava">
 
 ```java
-StorageListOptions options = StorageListOptions.builder()
+StoragePagedListOptions options = StoragePagedListOptions.builder()
         .accessLevel(StorageAccessLevel.PROTECTED)
         .targetIdentityId("otherUserID")
+        .setPageSize(1000)
         .build();
 
 RxAmplify.Storage.list("", options)
@@ -134,8 +170,9 @@ RxAmplify.Storage.list("", options)
                 for (StorageItem item : result.getItems()) {
                     Log.i("MyAmplifyApp", "Item: " + item.getKey());
                 }
+                Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
             },
-            error -> Log.e("MyAmplifyApp", "List failure", error)
+            error -> Log.e("MyAmplifyApp", "List failure", error);
         );
 ```