Update to JDA V4 and add new get methods

README.md

@@ -9,17 +9,16 @@
 [BadgeDownload]: https://api.bintray.com/packages/andre601/maven/JavaBotBlockAPI/images/download.svg
 [Download]: https://bintray.com/andre601/maven/JavaBotBlockAPI/_latestVersion
 
-# JavaBotBlockAPI
 JavaBotBlockAPI is a continued and updated Java Wrapper for [BotBlock], a website that makes it possible to update guild counts on multiple lists with one API.  
 This wrapper is a fork of [BotBlock4J] and was updated and improved to make it as userfriendly as possible.
 
-## Installation
+# Installation
 [![BadgeDownload]][Download]
 
 You can install JavaBotBlockAPI through the following methods.  
 Make sure to replace `{version}` with the above shown version.
 
-### Gradle
+## Gradle
 Put this code into your `build.gradle`:  
 ```gradle
 repositories{
@@ -31,7 +30,7 @@ dependencies{
 }
 ```
 
-### Maven
+## Maven
 For maven use this code snipped:  
 ```xml
 <dependencies>
@@ -43,62 +42,157 @@ For maven use this code snipped:
 </dependencies>
 ```
 
-## Usage
+# Usage
 To use the Wrapper you have to follow these steps.
 
-### Notes
+## Notes
 In the below examples do I use a JDA instance called `jda`.  
 This will also work with ShardManager.
 
-### Creating a BotBlockAPI instance
-You first need to create an instance of the BotBlockAPI class.  
-This class is the center of everything, including on what sites you want to post your guild counts.
+## POST methods
+You can post you guild counts to the different Botlists using the BotBlock API.
 
-You can use the internal Builder class of BotBlockAPI to create an instance. It would look something like this:  
+### Creating an instance of BotBlockAPI
+For posting your guild counts towards the BotBlock API you first need to create an instance of the BotBlockAPI class.  
+To do this it's recommended to use `BotBlockAPI.Builder()`.
+
+Here is an example of how it could look like.  
 ```java
-// Creating an instance of BotBlockAPI using BotBlockAPI.Builder
 BotBlockAPI api = new BotBlockAPI.Builder()
-    .addAuthToken("lbots.org", "MySecretToken123") // Adds a site with the corresponding API token.
-    .addAuthToken("botlist.space", "MySecretToken456") // The builder allows chaining of the methods.
+    .addAuthToken("lbots.org", "MySecretToken123")
+    .addAuthToken("botlist.space", "MySecretToken456")
     .build();
-```
-
-#### Notes
-There are a lot of other methods that you can use. Head over to the [Wiki] for more information.
+```  
+Remember to use `.build();` at the end to create the class.
 
-### Posting
-You can post the guilds either automatically or manually depending on your own preferences.
+### Auto Posting
+JavaBotBlockAPI allows you to post the guild counts automatically every X minutes.  
+To do this, you first need to get an instance of the RequestHandler and then call `.startAutoPosting(...)`.
 
-#### Auto-posting
-JavaBotBlockAPI comes with an inbuilt scheduler to post your guilds automatically.
-To use it simply use the `startAutoPosting` method and provide either a JDA instance, ShardManager instance or the bot id and guild count.
-
-**Example**:  
+Here is an example:  
 ```java
-// We need to get an instance of RequestHandler to use the methods.
 RequestHandler handler = new RequestHandler();
 
-// jda is a JDA instance and api a BotBlockAPI instance.
+// api is the instance of the BotBlockAPI
 handler.startAutoPosting(jda, api);
-```
+```  
+The delay in which you post the guild counts is set through the `.setUpdateInterval(int)` method in the BotBlockAPI.Builder().
 
-But what if you want to stop it?  
-For that just call the `stopAutoPosting` method:  
-```
-handler.stopAutoPosting();
-```
+### Cancel auto posting
+To cancel the auto posting just call `.stopAutoPosting();` in the RequestHandler and it should cancel the scheduler.
+
+### Manually posting
+There are methods that allow you to post the guild counts manually.  
+To Post your guild counts, just call the `.postGuilds(..., ...)` method in the RequestHandler.
 
-#### Manual posting
-If you want to post the guild counts manually you can use the `postGuilds` method.  
 ```java
-// We need to get an instance of RequestHandler to use the methods.
 RequestHandler handler = new RequestHandler();
 
-// jda is a JDA instance and api a BotBlockAPI instance.
+// api is the instance of the BotBlockAPI
 handler.postGuilds(jda, api);
 ```
 
-### Exceptions
+## GET methods
+Since version 2.0.0 of JavaBotBlockAPI can you get certain informations of a bot or the available Botlists on the BotBlock API.
+
+### All available Botlists
+You can call `.getBotlists()` to receive a JSONObject with all available Botlists in the BotBlockAPI.
+
+The returned JSONObject could look like this:  
+```json
+{
+    "botlist.space": {
+        "api_docs": "https://docs.botlist.space",
+        "api_post": "https://api.botlist.space/v1/bots/:id",
+        "api_field": "server_count",
+        "api_shard_id": null,
+        "api_shard_count": null,
+        "api_shards": "shards",
+        "api_get": "https://api.botlist.space/v1/bots/:id"
+    },
+    "lbots.org": {
+        "api_docs": "https://lbots.org/api/docs",
+        "api_post": "https://lbots.org/api/v1/bots/:id/stats",
+        "api_field": "guild_count",
+        "api_shard_id": "shard_id",
+        "api_shard_count": "shard_count",
+        "api_shards": null,
+        "api_get": null
+    }
+}
+```
+
+### Single Botlist
+Calling `.getBotlist(String)` returns a specific Botlist as JSONObject.  
+For example does `.getBotlist("lbots.org")` return the following JSONObject:  
+```json
+{
+    "api_docs": "https://lbots.org/api/docs",
+    "api_post": "https://lbots.org/api/v1/bots/:id/stats",
+    "api_field": "guild_count",
+    "api_shard_id": "shard_id",
+    "api_shard_count": "shard_count",
+    "api_shards": null,
+    "api_get": null
+}
+```
+
+### Complete Botinfo
+Calling `.getAll(...)` returns a JSONObject from all the botlists and with some general information.
+
+The JSONObject can look like this:  
+```json
+{
+    "id": "123456789012345678",
+    "name": "MyBot",
+    "discriminator": "1234",
+    "owners": [
+        "234567890123456789"
+    ],
+    "server_count": 100,
+    "invite": "https://discordapp.com/oauth2/authorize?client_id=123456789012345678&scope=bot",
+    "list_data": {
+        "botlist.space": [
+            {"data"},
+            200
+        ],
+        "lbots.org": [
+            {"data"},
+            404
+        ]
+    }
+}
+```  
+`{"data"}` is the JSON that is returned by the provided Botlist meaning it's different for each site.  
+`name`, `owners`, `server_count` and `invite` is based on the most common appearances of the data.
+
+### Botinfo from all Botlists
+You can call `.getBotInfos(...)` to only receive the bot info from all the Botlists.
+
+The returned JSONObject can look like this:  
+```json
+{
+    "botlist.space": [
+        {"data"},
+        200
+    ],
+    "lbots.org": [
+        {"data"},
+        404
+    ]
+}
+```  
+`{"data"}` is the JSON that is returned by the provided Botlist meaning it's different for each site.
+
+### Botinfo of a single site
+With `.getBotInfo(..., String)` can you receive the info of a specific site.  
+The returned data depends on the selected site and can be different for each one.
+
+### Owners
+You can call `.getOwners(...)` to get the owners of a Bot from all the Botlists.  
+The info is returned as JSONArray and is based on how often the info is provided by the botlists.
+
+## Exceptions
 When you post the guild counts you could encounter certain Exceptions.  
 You can receive the following exceptions:
 - `IOException`  
@@ -109,7 +203,7 @@ This shouldn't be the case with auto-posting since it has a minimum delay of 1 m
 - `NullPointerException`  
 Thrown when BotBlock.org sends an empty response, meaning something got messed up on their side.
 
-## Links
+# Links
 Here are some useful links:
 - [BotBlock.org][BotBlock] Site for which this wrapper was made.
   - [API] API documentation.

build.gradle

@@ -7,7 +7,7 @@ plugins{
 }
 
 group = 'com.andre601'
-version = '1.0.5'
+version = '1.1.0'
 
 sourceCompatibility = 1.8
 
@@ -21,21 +21,20 @@ repositories{
 }
 
 dependencies{
-    implementation group: 'com.squareup.okhttp3', name: 'okhttp', version: '3.11.0'
-    implementation group: 'org.json', name: 'json', version: '20180813'
-    implementation group: 'org.apache.commons', name: 'commons-lang3', version: '3.9'
-    implementation group: 'org.jetbrains', name: 'annotations', version: '16.0.2'
-    api(group: 'net.dv8tion', name: 'JDA', version: '3.8.3_463'){
+    api group: 'com.squareup.okhttp3', name: 'okhttp', version: '3.11.0'
+    api group: 'org.json', name: 'json', version: '20180813'
+    api group: 'org.jetbrains', name: 'annotations', version: '16.0.2'
+    api(group: 'net.dv8tion', name: 'JDA', version: '4.BETA.0_23'){
         exclude(module: 'opus-java')
     }
 }
 
-task sourcesJar(type: Jar, dependsOn: classes) {
+task sourcesJar(type: Jar, dependsOn: classes){
     classifier = 'sources'
     from sourceSets.main.allSource
 }
 
-task javadocJar(type: Jar, dependsOn: javadoc) {
+task javadocJar(type: Jar, dependsOn: javadoc){
     classifier = 'javadoc'
     from javadoc.destinationDir
 }

src/main/java/com/andre601/javabotblockapi/BotBlockAPI.java

@@ -18,29 +18,47 @@
  */
 package com.andre601.javabotblockapi;
 
-import org.apache.commons.lang3.ObjectUtils;
 import org.jetbrains.annotations.NotNull;
 
 import java.util.HashMap;
 import java.util.Map;
 
 /**
- * Class for handling the sites to post to and the delay for the auto-post option in
+ * Class for handling the sites to post to and the delay for the auto-post option in the
  * {@link com.andre601.javabotblockapi.RequestHandler RequestHandler}.
  */
 public class BotBlockAPI{
+    private static final int DEFAULT_DELAY = 30;
+
     private Map<String, String> authTokens;
     private int updateInterval;
 
     /**
-     * Creates an instance of BotBlockAPI with the provided api tokens (as Map) and update interval.
+     * Constructor to set the Map with the sites and tokens.
+     * <br>This will also set the update interval to 30 minutes.
+     *
+     * @param authTokens
+     *        A Map of sites and their tokens. May not be null.
+     *        <br>You may receive the API-token from your botlist.
+     */
+    public BotBlockAPI(@NotNull Map<String, String> authTokens){
+        this.authTokens = authTokens;
+        this.updateInterval = DEFAULT_DELAY;
+    }
+
+    /**
+     * Constructor to set the Map with the sites and tokens and also the update delay..
      *
      * @param authTokens
      *        A Map of sites and their tokens. May not be null.
+     *        <br>You may receive the API-token from your botlist.
      * @param updateInterval
      *        The update interval to set.
      */
     public BotBlockAPI(@NotNull Map<String, String> authTokens, int updateInterval){
+        if(updateInterval < 2)
+            throw new IllegalArgumentException("Update interval may not be less than 2.");
+
         this.authTokens = authTokens;
         this.updateInterval = updateInterval;
     }
@@ -58,7 +76,7 @@ int getUpdateInterval(){
      */
     public static class Builder{
         private Map<String, String> authTokens = new HashMap<>();
-        private int updateInterval = 30;
+        private int updateInterval = DEFAULT_DELAY;
 
         /**
          * Empty constructor to get the class.
@@ -67,22 +85,23 @@ public Builder(){}
 
         /**
          * Adds the provided Site name and token to the Map.
-         * <br>If there is already an entry with the same key, it will be overwritten.
+         * <br>Entries with the same key will be overwritten.
          *
          * @param  site
          *         The name of the site. May not be null.
          *         <br>A list of supported sites can be found <a href="https://botblock.org/api/docs#count" target="_blank">here</a>.
          * @param  token
          *         The API token you get from the corresponding botlist. May not be null.
+         *         <br>You may receive the API-token from your botlist.
          *
          * @throws NullPointerException
          *         When either the site or token are empty ({@code ""}).
          *
          * @return The Builder after the site and token were set. Useful for chaining.
          */
         public Builder addAuthToken(@NotNull String site, @NotNull String token){
-            if(ObjectUtils.isEmpty(site) || ObjectUtils.isEmpty(token))
-                throw new NullPointerException("Empty site and/or token is not allowed!");
+            Check.notEmpty(site, "Site may not be empty.");
+            Check.notEmpty(token, "Token may not be empty.");
 
             authTokens.put(site, token);
 
@@ -102,8 +121,7 @@ public Builder addAuthToken(@NotNull String site, @NotNull String token){
          * @return The Builder after the Map was set. Useful for chaining.
          */
         public Builder setAuthTokens(@NotNull Map<String, String> authTokens){
-            if(ObjectUtils.isEmpty(authTokens))
-                throw new NullPointerException("Empty Map for authTokens is not allowed!");
+            Check.notEmpty(authTokens, "AuthTokens may not be null.");
 
             this.authTokens = authTokens;
 
@@ -124,7 +142,7 @@ public Builder setAuthTokens(@NotNull Map<String, String> authTokens){
          */
         public Builder setUpdateInteval(int updateInterval){
             if(updateInterval < 2)
-                throw new IllegalArgumentException("updateInterval can't be less than 2!");
+                throw new IllegalArgumentException("Update interval may not be less than 2.");
 
             this.updateInterval = updateInterval;
 

src/main/java/com/andre601/javabotblockapi/Check.java

@@ -0,0 +1,23 @@
+package com.andre601.javabotblockapi;
+
+import java.util.Map;
+
+class Check {
+
+    static void notNull(Object target, String msg){
+        if(target == null)
+            throw new NullPointerException(msg);
+    }
+
+    static void notEmpty(CharSequence arguments, String msg){
+        notNull(arguments, msg);
+        if(arguments.length() == 0)
+            throw new NullPointerException(msg);
+    }
+
+    static void notEmpty(Map map, String msg){
+        notNull(map, msg);
+        if(map.isEmpty())
+            throw new NullPointerException(msg);
+    }
+}