Add marker based pagination for get users methods

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## Next Release
+- Add marker based pagination for get users methods
+
 ## 2.41.0 [2019-10-24]
 - Added enum action option for completed in Box Task class.
 

doc/users.md

@@ -17,7 +17,9 @@ Users represent an individual's account on Box.
 - [Add Email Alias](#add-email-alias)
 - [Delete Email Alias](#delete-email-alias)
 - [Get Enterprise Users](#get-enterprise-users)
+- [Get Enterprise Users (Marker Pagination)](#get-enterprise-users-marker-pagination)
 - [Get App Users By External App User ID](#get-app-users-by-external-app-user-id)
+- [Get App Users By External App User ID (Marker Pagination)](#get-app-users-by-external-app-user-id-marker-pagination)
 - [Move User's Folder](#move-users-folder)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -203,7 +205,7 @@ user.deleteEmailAlias("123");
 Get Enterprise Users
 --------------------
 
-To get an enterprises users call the
+To get an enterprise's users call the
 [`getAllEnterpriseUsers(BoxAPIConnection api)`][get-all-enterprise-users],
 [`getAllEnterpriseUsers(BoxAPIConnection api, String filterTerm, String... fields)`][get-all-enterprise-users-2], or
 [`getAllEnterpriseOrExternalUsers(BoxAPIConnection api, String filterTerm, String... fields)`][get-all-enterprise-users-3] method.
@@ -217,6 +219,27 @@ Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(api);
 [get-all-enterprise-users-2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
 [get-all-enterprise-users-3]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseOrExternalUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
 
+Get Enterprise Users (Marker Pagination)
+--------------------
+
+To get a list of all users in an enterprise, call the
+[`getAllEnterpriseUsers(BoxAPIConnection api, boolean usemarker, String marker)`][get-all-enterprise-users],
+[`getAllEnterpriseUsers(BoxAPIConnection api, String filterTerm, boolean usemarker, String marker, String... fields)`][get-all-enterprise-users-2], or
+[`getAllEnterpriseOrExternalUsers(BoxAPIConnection api, String filterTerm, boolean usemarker, String marker, String... fields)`][get-all-enterprise-users-3] method.
+To get a list of users starting from the first page of results, set the `usemarker` parameter as `true` and the `marker` parameter as `null`. If you would like to get the marker for the next page of results from the page the iterator is currently on, you must cast the iterable to `BoxResourseIterable<BoxUser.info>` and call `getNextMarker()` on that iterable. For more information on marker pagination, look here: https://developer.box.com/en/guides/api-calls/pagination/marker-based/.
+
+<!-- sample get_users -->
+```java
+Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(api, true, null);
+
+// Get marker
+String marker = ((BoxResourceIterable<BoxUser.Info>) users).getNextMarker();
+```
+
+[get-all-enterprise-users]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-
+[get-all-enterprise-users-2]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+[get-all-enterprise-users-3]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAllEnterpriseOrExternalUsers-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+
 Get App Users By External App User ID
 -------------------------------------
 
@@ -231,6 +254,23 @@ Iterable<BoxUser.Info> users = BoxUser.getAppUsersByExternalAppUserID(api, "exte
 
 [get-app-users-by-external-app-user-id]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAppUsersByExternalAppUserID-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
 
+Get App Users By External App User ID (Marker Pagination) 
+-------------------------------------
+
+To get app user using external app user ID, call the
+[`getAppUsersByExternalAppUserID(BoxAPIConnection api, String externalID, boolean usemarker, String marker, String... fields)`][get-app-users-by-external-app-user-id].
+This method allows you to easily associate Box app users with your application's
+identifiers for those users. To get a list of users starting from the first page of results, set the `usemarker` parameter as `true` and the `marker` parameter as `null`. If you would like to get the marker for the next page of results from the page the iterator is currently on, you must cast the iterable to `BoxResourseIterable<BoxUser.info>` and call `getNextMarker()` on that iterable. For more information on marker pagination, look here: https://developer.box.com/en/guides/api-calls/pagination/marker-based/.
+
+```java
+Iterable<BoxUser.Info> users = BoxUser.getAppUsersByExternalAppUserID(api, "external_app_user_id");
+
+// Get marker
+String marker = ((BoxResourceIterable<BoxUser.Info>) users).getNextMarker();
+```
+
+[get-app-users-by-external-app-user-id]: http://opensource.box.com/box-java-sdk/javadoc/com/box/sdk/BoxUser.html#getAppUsersByExternalAppUserID-com.box.sdk.BoxAPIConnection-java.lang.String-java.lang.String...-
+
 Move User's Folder
 ------------------
 

src/main/java/com/box/sdk/BoxResourceIterable.java

@@ -52,20 +52,45 @@ public abstract class BoxResourceIterable<T> implements Iterable<T> {
      */
     private final int limit;
 
+    /**
+     * The iterator that gets the next items.
+     */
+    private final IteratorImpl iterator;
+
     /**
      * Constructor.
      *
      * @param api
      *            the API connection to be used by the resource
      * @param url
-     *            to end-point with paging support
+     *            endpoint with paging support
      * @param limit
      *            the maximum number of items to return in a page
      */
     public BoxResourceIterable(BoxAPIConnection api, URL url, int limit) {
         this.api = api;
         this.url = url;
         this.limit = limit;
+        this.iterator = new IteratorImpl(null);
+    }
+
+    /**
+     * Constructor.
+     *
+     * @param api
+     *            the API connection to be used by the resource
+     * @param url
+     *            endpoint with paging support
+     * @param limit
+     *            the maximum number of items to return in a page
+     * @param marker
+     *            the marker where the iterator will begin
+     */
+    public BoxResourceIterable(BoxAPIConnection api, URL url, int limit, String marker) {
+        this.api = api;
+        this.url = url;
+        this.limit = limit;
+        this.iterator = new IteratorImpl(marker);
     }
 
     /**
@@ -85,7 +110,17 @@ public BoxResourceIterable(BoxAPIConnection api, URL url, int limit) {
      */
     @Override
     public Iterator<T> iterator() {
-        return new IteratorImpl();
+        return this.iterator;
+    }
+
+    /**
+     * Builds internal read-only iterator over {@link BoxResource}-s.
+     *
+     * @return iterator implementation
+     * @see Iterable#iterator()
+     */
+    public String getNextMarker() {
+        return this.iterator.markerNext;
     }
 
     /**
@@ -111,8 +146,12 @@ private class IteratorImpl implements Iterator<T> {
 
         /**
          * Constructor.
+         *
+         * @param marker
+         *            the marker at which the iterator will begin
          */
-        IteratorImpl() {
+        IteratorImpl(String marker) {
+            this.markerNext = marker;
             this.loadNextPage();
         }
 
@@ -184,7 +223,6 @@ public T next() {
         public void remove() {
             throw new UnsupportedOperationException();
         }
-
     }
 
 }

src/main/java/com/box/sdk/BoxUser.java

@@ -176,7 +176,20 @@ public static BoxUser getCurrentUser(BoxAPIConnection api) {
      * @return     an iterable containing all the enterprise users.
      */
     public static Iterable<BoxUser.Info> getAllEnterpriseUsers(final BoxAPIConnection api) {
-        return getAllEnterpriseUsers(api, null);
+        return getAllEnterpriseUsers(api, false, null);
+    }
+
+
+    /**
+     * Returns an iterable containing all the enterprise users. Uses marker based pagination.
+     * @param  api       the API connection to be used when retrieving the users.
+     * @param  usemarker Boolean that determines whether to use marker based pagination.
+     * @param  marker    The marker at which the iterator will begin.
+     * @return           an iterable containing all the enterprise users.
+     */
+    public static Iterable<BoxUser.Info> getAllEnterpriseUsers(final BoxAPIConnection api, final boolean usemarker,
+            final String marker) {
+        return getUsersInfoForType(api, null, null, null, usemarker, marker);
     }
 
     /**
@@ -190,7 +203,23 @@ public static Iterable<BoxUser.Info> getAllEnterpriseUsers(final BoxAPIConnectio
      */
     public static Iterable<BoxUser.Info> getAllEnterpriseUsers(final BoxAPIConnection api, final String filterTerm,
             final String... fields) {
-        return getUsersInfoForType(api, filterTerm, null, null, fields);
+        return getUsersInfoForType(api, filterTerm, null, null, false, null, fields);
+    }
+
+    /**
+     * Returns an iterable containing all the enterprise users that matches the filter and specifies which child fields
+     * to retrieve from the API. Uses marker based pagination.
+     * @param  api        the API connection to be used when retrieving the users.
+     * @param  filterTerm used to filter the results to only users starting with this string in either the name or the
+     *                    login. Can be null to not filter the results.
+     * @param  usemarker  Boolean that determines whether to use marker based pagination.
+     * @param  marker     The marker at which the iterator will begin.
+     * @param  fields     the fields to retrieve. Leave this out for the standard fields.
+     * @return            an iterable containing all the enterprise users that matches the filter.
+     */
+    public static Iterable<BoxUser.Info> getAllEnterpriseUsers(final BoxAPIConnection api, final String filterTerm,
+            final boolean usemarker, final String marker, final String... fields) {
+        return getUsersInfoForType(api, filterTerm, null, null, usemarker, marker, fields);
     }
 
     /**
@@ -206,7 +235,25 @@ public static Iterable<BoxUser.Info> getAllEnterpriseUsers(final BoxAPIConnectio
      */
     public static Iterable<BoxUser.Info> getExternalUsers(final BoxAPIConnection api, final String filterTerm,
           final String... fields) {
-        return getUsersInfoForType(api, filterTerm, "external", null, fields);
+        return getUsersInfoForType(api, filterTerm, "external", null, false, null, fields);
+    }
+
+    /**
+     * Gets a limited set of information about an external user. (A user collaborating
+     * on content owned by the enterprise). Note: Only fields the user has permission to
+     * see will be returned with values. Other fields will return a value of null. Uses marker based pagination.
+     * @param  api        the API connection to be used when retrieving the users.
+     * @param  filterTerm used to filter the results to only users matching the given login.
+     *                    This does exact match only, so if no filter term is passed in, nothing
+     *                    will be returned.
+     * @param  usemarker  Boolean that determines whether to use marker based pagination.
+     * @param  marker     The marker at which the iterator will begin.
+     * @param  fields     the fields to retrieve. Leave this out for the standard fields.
+     * @return an iterable containing external users matching the given email
+     */
+    public static Iterable<BoxUser.Info> getExternalUsers(final BoxAPIConnection api, final String filterTerm,
+          final boolean usemarker, final String marker, final String... fields) {
+        return getUsersInfoForType(api, filterTerm, "external", null, usemarker, marker, fields);
     }
 
     /**
@@ -222,7 +269,25 @@ public static Iterable<BoxUser.Info> getExternalUsers(final BoxAPIConnection api
      */
     public static Iterable<BoxUser.Info> getAllEnterpriseOrExternalUsers(final BoxAPIConnection api,
            final String filterTerm, final String... fields) {
-        return getUsersInfoForType(api, filterTerm, "all", null, fields);
+        return getUsersInfoForType(api, filterTerm, "all", null, false, null, fields);
+    }
+
+    /**
+     * Gets any managed users that match the filter term as well as any external users that
+     * match the filter term. For managed users it matches any users names or emails that
+     * start with the term. For external, it only does full match on email. This method
+     * is ideal to use in the case where you have a full email for a user and you don't
+     * know if they're managed or external. Uses marker based pagination.
+     * @param  api        the API connection to be used when retrieving the users.
+     * @param filterTerm    The filter term to lookup users by (login for external, login or name for managed)
+     * @param usemarker     Boolean that determines whether to use marker based pagination.
+     * @param marker        The marker at which the iterator will begin.
+     * @param fields        the fields to retrieve. Leave this out for the standard fields.
+     * @return an iterable containing users matching the given email
+     */
+    public static Iterable<BoxUser.Info> getAllEnterpriseOrExternalUsers(final BoxAPIConnection api,
+           final String filterTerm, final boolean usemarker, final String marker, final String... fields) {
+        return getUsersInfoForType(api, filterTerm, "all", null, usemarker, marker, fields);
     }
 
     /**
@@ -234,7 +299,21 @@ public static Iterable<BoxUser.Info> getAllEnterpriseOrExternalUsers(final BoxAP
      */
     public static Iterable<BoxUser.Info> getAppUsersByExternalAppUserID(final BoxAPIConnection api,
            final String externalAppUserId, final String... fields) {
-        return getUsersInfoForType(api, null, null, externalAppUserId, fields);
+        return getUsersInfoForType(api, null, null, externalAppUserId, false, null, fields);
+    }
+
+    /**
+     * Gets any app users that has an exact match with the externalAppUserId term using marker based pagination.
+     * @param api                 the API connection to be used when retrieving the users.
+     * @param externalAppUserId    the external app user id that has been set for app user
+     * @param usemarker            Boolean that determines whether to use marker based pagination.
+     * @param marker               The marker at which the iterator will begin.
+     * @param fields               the fields to retrieve. Leave this out for the standard fields.
+     * @return an iterable containing users matching the given email
+     */
+    public static Iterable<BoxUser.Info> getAppUsersByExternalAppUserID(final BoxAPIConnection api,
+           final String externalAppUserId, final boolean usemarker, String marker, final String... fields) {
+        return getUsersInfoForType(api, null, null, externalAppUserId, usemarker, marker, fields);
     }
 
     /**
@@ -245,30 +324,48 @@ public static Iterable<BoxUser.Info> getAppUsersByExternalAppUserID(final BoxAPI
      * @param userType          The type of users we want to search with this request.
      *                          Valid values are 'managed' (enterprise users), 'external' or 'all'
      * @param externalAppUserId the external app user id that has been set for an app user
+     * @param usemarker         Boolean that determines whether to use marker based pagination.
+     * @param marker            The marker at which the iterator will begin.
      * @param fields            the fields to retrieve. Leave this out for the standard fields.
      * @return                  An iterator over the selected users.
      */
-    private static Iterable<BoxUser.Info> getUsersInfoForType(final BoxAPIConnection api,
-          final String filterTerm, final String userType, final String externalAppUserId, final String... fields) {
-        return new Iterable<BoxUser.Info>() {
-            public Iterator<BoxUser.Info> iterator() {
-                QueryStringBuilder builder = new QueryStringBuilder();
-                if (filterTerm != null) {
-                    builder.appendParam("filter_term", filterTerm);
-                }
-                if (userType != null) {
-                    builder.appendParam("user_type", userType);
-                }
-                if (externalAppUserId != null) {
-                    builder.appendParam("external_app_user_id", externalAppUserId);
+    private static Iterable<BoxUser.Info> getUsersInfoForType(final BoxAPIConnection api, final String filterTerm,
+        final String userType, final String externalAppUserId, final boolean usemarker, final String marker,
+        final String... fields) {
+
+        final QueryStringBuilder builder = new QueryStringBuilder();
+        if (filterTerm != null) {
+            builder.appendParam("filter_term", filterTerm);
+        }
+        if (userType != null) {
+            builder.appendParam("user_type", userType);
+        }
+        if (externalAppUserId != null) {
+            builder.appendParam("external_app_user_id", externalAppUserId);
+        }
+        if (usemarker) {
+            builder.appendParam("usemarker", "true");
+        }
+        if (fields.length > 0) {
+            builder.appendParam("fields", fields);
+        }
+        final URL url = USERS_URL_TEMPLATE.buildWithQuery(api.getBaseURL(), builder.toString());
+
+        if (usemarker) {
+            return new BoxResourceIterable<BoxUser.Info>(api, url, 100, marker) {
+                @Override
+                protected BoxUser.Info factory(JsonObject jsonObject) {
+                    BoxUser user = new BoxUser(api, jsonObject.get("id").asString());
+                    return user.new Info(jsonObject);
                 }
-                if (fields.length > 0) {
-                    builder.appendParam("fields", fields);
+            };
+        } else {
+            return new Iterable<BoxUser.Info>() {
+                public Iterator<BoxUser.Info> iterator() {
+                    return new BoxUserIterator(api, url);
                 }
-                URL url = USERS_URL_TEMPLATE.buildWithQuery(api.getBaseURL(), builder.toString());
-                return new BoxUserIterator(api, url);
-            }
-        };
+            };
+        }
     }
 
     /**