Add support for Scroll API

Author: Timothy Lim

README.md

@@ -134,12 +134,16 @@ user = User.find(params);
 user.addCustomAttribute(CustomAttribute.newStringAttribute("role", "captain"));
 User.update(user);
 
-// Iterate over all users
+// Iterate over all users (up to 10k records, to read all use Scroll API)
 UserCollection users = User.list();
 while(users.hasNext()) {
     System.out.println(users.next().getUserId());
 }
 
+// Retrieve users via Scroll API
+UserCollection users = User.scroll(null);
+users = User.scroll(users.getScrollParam());
+
 // Bulk submit users
 final List<JobItem<User>> items = Lists.newArrayList();
 items.add(new JobItem<User>("post", user1));
@@ -187,12 +191,16 @@ while(contacts.hasNext()) {
     System.out.println(contacts.next());
 }
 
-// Iterate over all contacts
+// Iterate over all contacts (up to 10k records, to read all use Scroll API)
 ContactCollection allContacts = Contact.list();
 while(allContacts.hasNext()) {
     System.out.println(allContacts.next());
 }
 
+// Retrieve contacts via Scroll API
+ContactCollection contacts = Contact.scroll(null);
+contacts = Contact.scroll(contacts.getScrollParam());
+
 // Remove a contact
 Contact.delete(contact);
 
@@ -586,6 +594,8 @@ These return a Collection object (eg `UserCollection`) which can be iterated in
 
 - Java's inbuilt iterator methods `next()` and `hasNext()` - these are useful when you want to fetch data without manually handling pagination.
 
+- User and Contact listing only works up to 10k records. To retrieve all records use the Scroll API via `scroll()`
+
 ### Error handling
 
 You do not need to deal with the HTTP response from an API call directly.

intercom-java/src/main/java/io/intercom/api/Contact.java

@@ -49,6 +49,15 @@ public static ContactCollection list()
         return DataResource.list(SENTINEL, "contacts", ContactCollection.class);
     }
 
+    public static ContactCollection scroll(String scrollParam)
+            throws AuthorizationException, ClientException, ServerException, InvalidException, RateLimitException {
+        Map<String, String> params = Maps.newHashMap();
+        if(scrollParam != null && scrollParam.trim() != ""){
+            params.put("scroll_param", scrollParam);
+        }
+        return DataResource.list(params, "contacts/scroll", ContactCollection.class);
+    }
+
     public static Contact create(Contact c)
             throws AuthorizationException, ClientException, ServerException, InvalidException, RateLimitException {
         return DataResource.create(ContactUpdate.buildFrom(c), "contacts", Contact.class);

intercom-java/src/main/java/io/intercom/api/TypedDataCollection.java

@@ -27,6 +27,9 @@ public abstract class TypedDataCollection<T extends TypedData> extends TypedData
     @JsonProperty("type")
     protected String type;
 
+    @JsonProperty("scroll_param")
+    protected String scrollParam;
+
     public abstract TypedDataCollection<T> nextPage();
 
     public boolean hasNextPage() {
@@ -55,6 +58,10 @@ public String getType() {
         return type;
     }
 
+    public String getScrollParam() {
+        return scrollParam;
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;

intercom-java/src/main/java/io/intercom/api/User.java

@@ -70,6 +70,15 @@ public static UserCollection list()
         return DataResource.list(SENTINEL, "users", UserCollection.class);
     }
 
+    public static UserCollection scroll(String scrollParam)
+            throws AuthorizationException, ClientException, ServerException, InvalidException, RateLimitException {
+        Map<String, String> params = Maps.newHashMap();
+        if(scrollParam != null && scrollParam.trim() != ""){
+            params.put("scroll_param", scrollParam);
+        }
+        return DataResource.list(params, "users/scroll", UserCollection.class);
+    }
+
     public static Job submit(final List<JobItem<User>> items)
         throws AuthorizationException, ClientException, ServerException, InvalidException, RateLimitException {
         return submit(items, null);