Update lots of stuff, settle #16

Author: dec4234

src/main/java/net/dec4234/javadestinyapi/exceptions/APIException.java

@@ -8,10 +8,11 @@
 package net.dec4234.javadestinyapi.exceptions;
 
 /**
- * Base class for all exceptions generated when an issue occurs in the request pipeline to Bungie.
- * This most common reason for this error would be when the API is offline, and all objects are misparsed.
+ * Base class for all exceptions generated when an issue occurs in the request pipeline to Bungie. <br>
+ * This is defined as a RuntimeException to give more flexibility internally (namely in {@link net.dec4234.javadestinyapi.material.DestinyAPI#searchUsers(String)}).
+ * You should still try/catch this rather than deferring it to being a solely runtime exception
  */
-public abstract class APIException extends Exception {
+public abstract class APIException extends RuntimeException {
 
     public APIException() {
 

src/main/java/net/dec4234/javadestinyapi/material/DestinyAPI.java

@@ -12,21 +12,27 @@
 import com.google.gson.JsonObject;
 import net.dec4234.javadestinyapi.exceptions.APIException;
 import net.dec4234.javadestinyapi.material.clan.Clan;
+import net.dec4234.javadestinyapi.material.clan.ClanMember;
+import net.dec4234.javadestinyapi.material.clan.GroupType;
 import net.dec4234.javadestinyapi.material.user.BungieUser;
 import net.dec4234.javadestinyapi.material.user.UserCredential;
 import net.dec4234.javadestinyapi.material.user.UserCredentialType;
 import net.dec4234.javadestinyapi.responses.user.SanitizedUsernamesResponse;
 import net.dec4234.javadestinyapi.utils.HttpUtils;
 import net.dec4234.javadestinyapi.utils.StringUtils;
+import net.dec4234.javadestinyapi.utils.fast.Pagination;
 import net.dec4234.javadestinyapi.utils.framework.OAuthManager;
+import org.jetbrains.annotations.NotNull;
 
 import java.util.ArrayList;
+import java.util.Iterator;
 import java.util.LinkedList;
 import java.util.List;
 
 /**
  * This is the base class for the entire API. It MUST be initialized with an API key before <u>any part</u>
  * of the API is used.
+ * // TODO: its time to rethink this class and instancing the API
  */
 public class DestinyAPI {
 
@@ -163,8 +169,9 @@ public static SanitizedUsernamesResponse getSanitizedUsernames(String id) throws
     }
 
     /**
-     * Get a BungieUser from a Steam ID
-     * NOT the same IDs used by Bungie to identify individual users
+     * Get a BungieUser from a Steam ID, which is NOT the same IDs used by Bungie to identify individual users.
+     * @param steamID The steamID corresponding with the user you are looking for.
+     * @return The bungie user corresponding with that steam ID
      */
     public static BungieUser getMemberFromSteamID(String steamID) throws APIException {
         return getMemberFromPlatformID("SteamId", steamID);
@@ -251,44 +258,85 @@ public static BungieUser getUserWithName(String nameAndDiscrim) throws APIExcept
     /**
      * Search users across all platforms for anyone with that name.
      * <p>
-     * Searching "dec4234" will return an array containing a single
-     * BungieUser. While searching "Gladd" or "Datto" should return many users.
-     * <p>
-     * // TODO: Issue #16
+     * Returns a "Pagination" object. This allows you to request the next page of guardians with that name one at a time,
+     * rather than returning a huge array after a long time. This was proposed in issue #16.
+     * <br>
+     * <pre>
+     * {@code
+     *      Pagination<List<BungieUser>> pagination = DestinyAPI.searchUsers("Etho");
+     *      for(List<BungieUser> bungieUsers : pagination) { // iterate through all pages one by one
+     *          bungieUsers.forEach(bungieUser -> { // Print details for users on the current page
+     *           	System.out.println(bungieUser);
+     *          });
+     *      }
+     * }
+     * </pre>
+     * @param name The name of the user you want to search for
+     * @return A Pagination object that returns a List of matching bungie users per page.
      */
-    public static List<BungieUser> searchUsers(String name) throws APIException {
-        List<BungieUser> users = new ArrayList<>();
-
+    public static Pagination<List<BungieUser>> searchUsers(String name) throws APIException {
         JsonObject body = new JsonObject();
         body.addProperty("displayNamePrefix", name);
 
-        List<JsonObject> jsonObjects = new ArrayList<>();
+		return new Pagination<>() {
+            private int i = 0;
+            private boolean isDone = false;
+
+			@Override
+			public boolean hasNext() throws APIException {
+                if(isDone) {
+                    return false;
+                }
 
-        for (int i = 0; i < 100; i++) { // Start at page 0 and increment each time until there are no more valid pages
-            JsonObject jsonObject = httpUtils.urlRequestPOST(HttpUtils.URL_BASE + "/User/Search/GlobalName/" + i + "/", body);
+                JsonObject response = httpUtils.urlRequestPOST(HttpUtils.URL_BASE + "/User/Search/GlobalName/" + i + "/", body);
+                i++;
 
-            // Only continue looping if the result has a list of search results
-            if (jsonObject.has("Response") && jsonObject.getAsJsonObject("Response").getAsJsonArray("searchResults").size() != 0) {
-                JsonArray jsonArray = jsonObject.getAsJsonObject("Response").getAsJsonArray("searchResults");
+                List<JsonObject> jsonObjects = new ArrayList<>();
+                List<BungieUser> users = new ArrayList<>();
 
-                for (JsonElement jsonElement : jsonArray) { // Add all user info objects into one list
-                    jsonObjects.add(jsonElement.getAsJsonObject());
+                // Only continue looping if the result has a list of search results
+                if (response.has("Response") && !response.getAsJsonObject("Response").getAsJsonArray("searchResults").isEmpty()) {
+                    JsonArray jsonArray = response.getAsJsonObject("Response").getAsJsonArray("searchResults");
+
+                    for (JsonElement jsonElement : jsonArray) { // Add all user info objects into one list
+                        jsonObjects.add(jsonElement.getAsJsonObject());
+                    }
+                } else {
+                    currentResponse = null;
+                    this.hasGrabbed = false;
+                    this.isDone = true;
+                    return false;
                 }
-            } else {
-                break;
-            }
-        }
 
-        // Process the one big list to convert bungie.net profile info into destiny profile info
-        for (JsonObject jsonObject : jsonObjects) {
-            BungieUser bungieUser = processListOfProfiles(jsonObject.getAsJsonArray("destinyMemberships"));
+                // Process the one big list to convert bungie.net profile info into destiny profile info
+                for (JsonObject jsonObject : jsonObjects) {
+                    BungieUser bungieUser = processListOfProfiles(jsonObject.getAsJsonArray("destinyMemberships"));
 
-            if (bungieUser != null) {
-                users.add(bungieUser);
-            }
-        }
+                    if (bungieUser != null) {
+                        users.add(bungieUser);
+                    }
+                }
+
+                this.currentResponse = users;
+                this.hasGrabbed = false;
+				return true;
+			}
 
-        return users;
+			@Override
+			public List<BungieUser> next() throws APIException {
+                if(isDone) {
+                    return null;
+                }
+
+                if(!hasGrabbed) {
+                    hasGrabbed = true;
+                    return this.currentResponse;
+                } else {
+                    this.hasNext();
+					return this.currentResponse;
+                }
+            }
+		};
     }
 
     /**
@@ -403,6 +451,33 @@ public static List<BungieUser> searchGlobalDisplayNames(String prefix) throws AP
         return bungieUsers;
     }
 
+    /**
+     * Search for the clan with the given name. This is given as the preferred method for searching for clans by name.
+     * @param search The search query
+     * @return A single clan that matches the search query, null if none are found
+     * @throws APIException If anything goes wrong when interacting with the API
+     */
+    public static Clan searchClan(String search) throws APIException {
+        JsonObject body = new JsonObject();
+        body.addProperty("groupName", search);
+        body.addProperty("groupType", GroupType.CLAN.getType());
+
+        JsonObject jsonObject = httpUtils.urlRequestPOST(HttpUtils.URL_BASE + "/GroupV2/NameV2/", body);
+
+        if(!jsonObject.has("Response")) {
+            return null; // no clan found -- error 686
+        }
+
+        jsonObject = jsonObject.getAsJsonObject("Response");
+
+        if(jsonObject.has("founder") && jsonObject.has("detail")) {
+            long id = jsonObject.getAsJsonObject("detail").get("groupId").getAsLong();
+            return new Clan(id, jsonObject.getAsJsonObject("detail"), jsonObject.getAsJsonObject("founder"));
+        } else {
+            return null;
+        }
+    }
+
     public static String getApiKey() {
         return apiKey;
     }

src/main/java/net/dec4234/javadestinyapi/material/clan/Clan.java

@@ -26,9 +26,7 @@
 
 public class Clan extends ContentFramework {
 
-    private String apiKey = DestinyAPI.getApiKey();
     private HttpUtils hu = DestinyAPI.getHttpUtils();
-    private JsonObject jo, cjo; // The entire Clan response
 
     private long clanId = -1;
     private String clanName, clanDescription, motto;
@@ -37,19 +35,28 @@ public class Clan extends ContentFramework {
     private Date creationDate;
     private int memberCount = -1;
 
-    private List<BungieUser> admins, members;
+    private ClanMember founder;
+    private List<ClanMember> admins, members;
     private ClanManagement clanManagement;
-    private JsonObject jj;
+    private JsonObject jj, detail, founderJO;
 
+    /**
+     * @param clanId The ID of the clan
+     */
     public Clan(long clanId) {
         super("https://www.bungie.net/platform/GroupV2/" + clanId + "/?components=200", source -> {
             return source.getAsJsonObject("Response");
         });
         this.clanId = clanId;
     }
 
+    /**
+     * This is no longer the preferred method for searching by name. Use {@link DestinyAPI#searchClan(String)}
+     * @param clanName The name of the clan that you would like to look at
+     */
+    @Deprecated
     public Clan(String clanName) {
-        super(("https://www.bungie.net/Platform/GroupV2/Name/" + clanName.replace(" ", "%20") + "/1/?components=200"), source -> {
+        super(("https://www.bungie.net/Platform/GroupV2/Name/" + StringUtils.httpEncode(clanName) + "/1/?components=200"), source -> {
             return source.getAsJsonObject("Response");
         });
         this.clanName = clanName;
@@ -63,6 +70,15 @@ public Clan(long clanId, String clanName) {
         this.clanName = clanName;
     }
 
+    public Clan(long clanId, JsonObject detail, JsonObject founder) {
+        super(("https://www.bungie.net/platform/GroupV2/" + clanId + "/?components=200"), source -> {
+            return source.getAsJsonObject("Response");
+        });
+        this.clanId = clanId;
+        this.detail = detail;
+        this.founderJO = founder;
+    }
+
     public String getClanID() throws APIException {
         if (clanId == -1) {
             clanId = getDetail().get("groupId").getAsLong();
@@ -119,35 +135,37 @@ public boolean isAllowChat() throws APIException {
     /**
      * Get the founder of the clan
      */
-    public BungieUser getFounder() throws APIException {
-        return new BungieUser(getJO().getAsJsonObject("founder").getAsJsonObject("destinyUserInfo").get("membershipId").getAsString());
+    public ClanMember getFounder() throws APIException {
+        if(founder != null) {
+            return new ClanMember(founderJO);
+        }
+
+        return new ClanMember(getJO().getAsJsonObject("founder"));
     }
 
     /**
-     * Returns a list of the founder and the admins of the clan
+     * Returns a list of the founder and the admins of the clan.
      * The founder is always the first in this list?
      * Followed by the admins in the order they were promoted
      */
-    public List<BungieUser> getAdmins() throws APIException {
+    public List<ClanMember> getAdmins() throws APIException {
         if (admins != null) {
             return admins;
         }
 
-        List<BungieUser> temp = new ArrayList<>();
+        List<ClanMember> temp = new ArrayList<>();
         JsonArray ja = hu.urlRequestGET("https://www.bungie.net/Platform/GroupV2/" + getClanID() + "/AdminsAndFounder/?components=200").getAsJsonObject("Response").getAsJsonArray("results");
 
         for (JsonElement je : ja) {
-            temp.add(new BungieUser(je.getAsJsonObject().get("destinyUserInfo").getAsJsonObject().get("membershipId").getAsString()));
+            temp.add(new ClanMember(je.getAsJsonObject()));
         }
 
         admins = temp; // Cache this information
         return temp;
     }
 
     /**
-     * Returns the average number of days since all members last played.
-     *
-     * Thanks to the ClanMember system, requires very little calls and should be pretty fast.
+     * @return A double representing the average amount of days since clan members have last logged in.
      */
     public double getAverageInactivityAmongMembers() throws APIException {
         ArrayList<Double> averages = new ArrayList<>();
@@ -163,6 +181,10 @@ public double getAverageInactivityAmongMembers() throws APIException {
 
     /**
      * Get the most inactive members of a clan, using the getMembers() endpoint and the ClanMember class
+     * @param numberOfResults The number of inactive members you want
+     * @param exclude An exclusion list of bungie IDs. If an inactive user has their id in this list then they will NOT
+     *                be included in the returned list.
+     * @return A list of the most inactive members, sorted from most to least inactive
      */
     public List<ClanMember> getMostInactiveMembers(int numberOfResults, String... exclude) throws APIException {
         List<ClanMember> list = getMembers();
@@ -348,6 +370,10 @@ public ClanManagement getClanManagement() {
     }
 
     private JsonObject getDetail() throws APIException {
+        if(detail != null) {
+            return detail;
+        }
+
         return getJO().getAsJsonObject("detail");
     }
 }

src/main/java/net/dec4234/javadestinyapi/material/clan/ClanMember.java

@@ -13,6 +13,10 @@
 
 import java.util.Date;
 
+/**
+ * Represents a "ClanMember" which is basically the same as a BungieUser but with some added-on info like join date,
+ * is online and last online date. This information is pulled from the /Members/ list of a clan.
+ */
 public class ClanMember extends BungieUser {
 
     private int memberType;
@@ -34,10 +38,19 @@ public int getMemberType() {
         return memberType;
     }
 
+    /**
+     * @return True if this user is currently online in Destiny 2
+     */
     public boolean isOnline() {
         return isOnline;
     }
 
+    /**
+     * When was the last time this user's online status changed. In other words, when they went from offline to online
+     * or online to offline. If they are currently online then this could tell you how long they have been on in the
+     * current playing session.
+     * @return The date representing when their online status changed
+     */
     public Date getLastOnlineStatusChange() {
         if(lastOnline == null) {
             try {
@@ -50,14 +63,23 @@ public Date getLastOnlineStatusChange() {
         return lastOnline;
     }
 
+    /**
+     * @return The number of days since this user's online status last changed
+     */
     public double getDaysSinceLastPlayed() {
         return StringUtils.getDaysSinceTime(getLastOnlineStatusChange());
     }
 
+    /**
+     * @return The ID of the clan that this user belongs to
+     */
     public String getGroupId() {
         return groupId;
     }
 
+    /**
+     * @return The date this user joined their current clan
+     */
     public Date getJoinDate() {
         return joinDate;
     }