Merge pull request #142 from intercom/MM/scroll

add scroll API support for User and Contact

Author: mmartinic

README.md

@@ -134,12 +134,17 @@ 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
+ScrollableUserCollection usersScroll = User.scroll();
+List<User> users = usersScroll.getPage();
+usersScroll = usersScroll.scroll();
+
 // Bulk submit users
 final List<JobItem<User>> items = Lists.newArrayList();
 items.add(new JobItem<User>("post", user1));
@@ -187,12 +192,18 @@ 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
+ScrollableContactCollection contactsScroll = Contact.scroll();
+List<Contact> contacts = contactsScroll.getPage();
+contactsScroll = contactsScroll.scroll();
+
+
 // Remove a contact
 Contact.delete(contact);
 
@@ -586,6 +597,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,11 @@ public static ContactCollection list()
         return DataResource.list(SENTINEL, "contacts", ContactCollection.class);
     }
 
+    public static ScrollableContactCollection scroll()
+            throws AuthorizationException, ClientException, ServerException, InvalidException, RateLimitException {
+        return DataResource.scroll(null, "contacts", ScrollableContactCollection.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/DataResource.java

@@ -1,5 +1,8 @@
 package io.intercom.api;
 
+import com.google.common.base.Strings;
+import com.google.common.collect.Maps;
+
 import java.net.URI;
 import java.util.List;
 import java.util.Map;
@@ -58,4 +61,13 @@ public static <C> C list(Map<String, String> params, String collectionPath, Clas
         return resource.get(c);
     }
 
+    public static <C> C scroll(String scrollParam, String collectionPath, Class<C> c) {
+        Map<String, String> params = Maps.newHashMap();
+        if (!Strings.isNullOrEmpty(scrollParam)) {
+            params.put("scroll_param", scrollParam);
+        }
+        final HttpClient resource = new HttpClient(UriBuilder.newBuilder().path(collectionPath + "/scroll").query(params).build());
+        return resource.get(c);
+    }
+
 }

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

@@ -0,0 +1,19 @@
+package io.intercom.api;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public class ScrollableContactCollection  extends ScrollableTypedDataCollection<Contact> {
+
+    @Override
+    public ScrollableContactCollection scroll() {
+        return DataResource.scroll(getScrollParam(), "contacts", ScrollableContactCollection.class);
+    }
+
+    @JsonProperty("contacts")
+    @Override
+    public List<Contact> getPage() {
+        return super.getPage();
+    }
+}

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

@@ -0,0 +1,33 @@
+package io.intercom.api;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.google.common.collect.Lists;
+
+import java.util.List;
+
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+public abstract class ScrollableTypedDataCollection<T extends TypedData> extends TypedData {
+
+    protected List<T> page = Lists.newArrayList();
+
+    @JsonProperty("scroll_param")
+    protected String scrollParam;
+
+    @JsonProperty("type")
+    protected String type;
+
+    public String getScrollParam() {
+        return scrollParam;
+    }
+
+    public String getType() {
+        return type;
+    }
+
+    public abstract ScrollableTypedDataCollection<T> scroll();
+
+    public List<T> getPage() {
+        return page;
+    }
+}

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

@@ -0,0 +1,20 @@
+package io.intercom.api;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import java.util.List;
+
+public class ScrollableUserCollection extends ScrollableTypedDataCollection<User> {
+
+    @Override
+    public ScrollableUserCollection scroll() {
+        return DataResource.scroll(getScrollParam(), "users", ScrollableUserCollection.class);
+    }
+
+    @JsonProperty("users")
+    @Override
+    public List<User> getPage() {
+        return super.getPage();
+    }
+
+}

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

@@ -70,6 +70,11 @@ public static UserCollection list()
         return DataResource.list(SENTINEL, "users", UserCollection.class);
     }
 
+    public static ScrollableUserCollection scroll()
+            throws AuthorizationException, ClientException, ServerException, InvalidException, RateLimitException {
+        return DataResource.scroll(null, "users", ScrollableUserCollection.class);
+    }
+
     public static Job submit(final List<JobItem<User>> items)
         throws AuthorizationException, ClientException, ServerException, InvalidException, RateLimitException {
         return submit(items, null);