Merge pull request #172 from botblock/change/add-checks

Add checks and improve javadocs

Author: Andre601

build.gradle

@@ -9,7 +9,7 @@ plugins{
     id 'net.kyori.blossom' version '1.1.0'
 }
 
-def ver = new Version(major: 6, minor: 1, revision: 0)
+def ver = new Version(major: 6, minor: 2, patch: 0)
 
 allprojects {
     apply plugin: 'com.jfrog.bintray'
@@ -62,6 +62,7 @@ allprojects {
 
                             // Discord Libs
                             "https://ci.dv8tion.net/job/JDA/javadoc/",
+                            "https://docs.javacord.org/api/v/3.0.7/overview-summary.html",
 
                             // Java 8
                             "https://docs.oracle.com/javase/8/docs/api/",
@@ -255,14 +256,14 @@ publishing {
 }
 
 class Version{
-    String major, minor, revision
+    String major, minor, patch
 
     static String getBuild(){
         System.getenv("BUILD_NUMBER") ? "_" + System.getenv("BUILD_NUMBER") : 
         System.getProperty("BUILD_NUMBER") ? "_" + System.getProperty("BUILD_NUMBER") : ""
     }
 
     String toString(){
-        "$major.$minor.${revision}$build"
+        "$major.$minor.${patch}$build"
     }
 }

core/src/main/java/org/botblock/javabotblockapi/core/annotations/PlannedRemoval.java

@@ -25,7 +25,10 @@
  * <br>This is paired with the {@link java.lang.Deprecated Deprecated} and
  * {@link org.botblock.javabotblockapi.core.annotations.DeprecatedSince DeprecatedSince} annotations.
  * 
- * <p>This annotation will always contain {@link #version() the version} in which the annotated Object will be removed.
+ * <p>This annotation will always contain the {@link #major() major}, {@link #minor()} and {@link #patch() patch} version
+ * in which the annotated Object will be removed.
+ * <br>For example will {@code @PlannedRemoval(major = 6, minor = 5, patch = 0)} indocate an Object for removal on version
+ * 6.5.0.
  * 
  * @since 5.2.2
  */
@@ -35,9 +38,23 @@
 public @interface PlannedRemoval{
 
     /**
-     * The version for when the annotated Object will be removed.
+     * The major version for when the annotated Object will be removed.
      * 
-     * @return The version for when this Object will be removed.
+     * @return The major version for when this Object will be removed.
      */
-    String version();
+    int major();
+    
+    /**
+     * The minor version for when the annotated Object will be removed.
+     * 
+     * @return The minor version for when this Object will be removed.
+     */
+    int minor();
+    
+    /**
+     * The patch version for when the annotated Object will be removed.
+     *
+     * @return The path version for when this Object will be removed.
+     */
+    int patch();
 }

javacord/src/main/java/org/botblock/javabotblockapi/javacord/PostAction.java

@@ -19,6 +19,7 @@
 package org.botblock.javabotblockapi.javacord;
 
 import org.botblock.javabotblockapi.core.BotBlockAPI;
+import org.botblock.javabotblockapi.core.CheckUtil;
 import org.botblock.javabotblockapi.core.exceptions.RatelimitedException;
 import org.botblock.javabotblockapi.requests.handler.RequestHandler;
 import org.javacord.api.DiscordApi;
@@ -112,6 +113,11 @@ public void disableAutoPost(@Nullable BotBlockAPI botBlockAPI){
      * finish, or to time out after a specified time frame.
      *
      * <p>This method may throw a {@link java.lang.InterruptedException InterruptedException} in the terminal.
+     * 
+     * <p>Following Exceptions can be thrown from the {@link org.botblock.javabotblockapi.core.CheckUtil CheckUtil}:
+     * <ul>
+     *     <li>{@link java.lang.IllegalStateException IllegalStateException} - When the provided time param is 0 or lower.</li>
+     * </ul>
      *
      * @param time
      *        The amount of time to wait for scheduled executions to finish before the Scheduler would time out.
@@ -121,6 +127,8 @@ public void disableAutoPost(@Nullable BotBlockAPI botBlockAPI){
      * @see java.util.concurrent.ScheduledExecutorService#awaitTermination(long, TimeUnit)
      */
     public void disableAutoPost(long time, @Nonnull TimeUnit timeUnit){
+        CheckUtil.condition(time <= 0, "time may not be less or equal to 0!");
+        
         try{
             scheduler.shutdown();
             scheduler.awaitTermination(time, timeUnit);
@@ -139,16 +147,23 @@ public void disableAutoPost(long time, @Nonnull TimeUnit timeUnit){
      * <p>The scheduler will wait an initial delay of 1 minute and then performs a task every n minutes, where n is the
      * time set in {@link org.botblock.javabotblockapi.core.BotBlockAPI.Builder#setUpdateDelay(Integer) BotBlockAPI.Builder.setUpdateDelay(Integer)}
      * (default is 30 minutes).
+     *
+     * <p>Following Exceptions can be thrown from the {@link org.botblock.javabotblockapi.core.CheckUtil CheckUtil}:
+     * <ul>
+     *     <li>{@link java.lang.IllegalStateException IllegalStateException} - When the provided DiscordApis are 0 or less.</li>
+     * </ul>
      * 
-     * @param apis
+     * @param discordApis
      *        The {@link org.javacord.api.DiscordApi DiscordApi instances} to post stats from.
      * @param botBlockAPI
      *        The {@link org.botblock.javabotblockapi.core.BotBlockAPI BotBlockAPI instance} to use.
      */
-    public void enableAutoPost(@Nonnull BotBlockAPI botBlockAPI, @Nonnull DiscordApi... apis){
+    public void enableAutoPost(@Nonnull BotBlockAPI botBlockAPI, @Nonnull DiscordApi... discordApis){
+        CheckUtil.condition(discordApis.length <= 0, "At least one DiscordApi instance needs to be provided!");
+        
         scheduler.scheduleAtFixedRate(() -> {
             try{
-                postGuilds(botBlockAPI, apis);
+                postGuilds(botBlockAPI, discordApis);
             }catch(IOException | RatelimitedException ex){
                 ex.printStackTrace();
             }
@@ -161,8 +176,13 @@ public void enableAutoPost(@Nonnull BotBlockAPI botBlockAPI, @Nonnull DiscordApi
      * 
      * <p>If the provided DiscordApi instance is a sharded Bot (Amount of shards is larger than 1) will the request
      * contain the {@code shards} array alongside a {@code shard_count} field.
+     *
+     * <p>Following Exceptions can be thrown from the {@link org.botblock.javabotblockapi.core.CheckUtil CheckUtil}:
+     * <ul>
+     *     <li>{@link java.lang.IllegalStateException IllegalStateException} - When the provided DiscordApis are 0 or less.</li>
+     * </ul>
      * 
-     * @param apis
+     * @param discordApis
      *        The {@link org.javacord.api.DiscordApi DiscordApi instances} to post stats from.
      * @param botBlockAPI
      *        The {@link org.botblock.javabotblockapi.core.BotBlockAPI BotBlockAPI instance} to use.
@@ -172,22 +192,24 @@ public void enableAutoPost(@Nonnull BotBlockAPI botBlockAPI, @Nonnull DiscordApi
      * @throws org.botblock.javabotblockapi.core.exceptions.RatelimitedException
      *         When we get rate limited by the BotBlock API (returns error code 429).
      */
-    public void postGuilds(@Nonnull BotBlockAPI botBlockAPI, @Nonnull DiscordApi... apis) throws IOException, RatelimitedException{
+    public void postGuilds(@Nonnull BotBlockAPI botBlockAPI, @Nonnull DiscordApi... discordApis) throws IOException, RatelimitedException{
+        CheckUtil.condition(discordApis.length <= 0, "At least one DiscordApi instance needs to be provided!");
+        
         JSONObject json = new JSONObject()
-                .put("bot_id", apis[0].getYourself().getId());
+                .put("bot_id", discordApis[0].getYourself().getId());
 
-        if(apis.length > 1){
-            int guilds = Arrays.stream(apis).map(DiscordApi::getServers).mapToInt(Collection::size).sum();
+        if(discordApis.length > 1){
+            int guilds = Arrays.stream(discordApis).map(DiscordApi::getServers).mapToInt(Collection::size).sum();
             json.put("server_count", guilds)
-                .put("shard_count", apis.length);
+                .put("shard_count", discordApis.length);
 
             List<Integer> shards = new ArrayList<>();
-            for(DiscordApi api : apis)
+            for(DiscordApi api : discordApis)
                 shards.add(api.getServers().size());
 
             json.put("shards", new JSONArray(Arrays.deepToString(shards.toArray())));
         }else{
-            json.put("server_count", apis[0].getServers().size());
+            json.put("server_count", discordApis[0].getServers().size());
         }
 
         botBlockAPI.getTokens().forEach(json::put);

jda/src/main/java/org/botblock/javabotblockapi/jda/PostAction.java

@@ -134,6 +134,11 @@ public void disableAutoPost(@Nullable BotBlockAPI botBlockAPI){
      *
      * <p>This method may throw a {@link java.lang.InterruptedException InterruptedException} in the terminal.
      *
+     * <p>Following Exceptions can be thrown from the {@link org.botblock.javabotblockapi.core.CheckUtil CheckUtil}:
+     * <ul>
+     *     <li>{@link java.lang.IllegalStateException IllegalStateException} - When the provided time param is 0 or lower.</li>
+     * </ul>
+     * 
      * @param time
      *        The amount of time to wait for scheduled executions to finish before the Scheduler would time out.
      * @param timeUnit
@@ -144,6 +149,8 @@ public void disableAutoPost(@Nullable BotBlockAPI botBlockAPI){
      * @see java.util.concurrent.ScheduledExecutorService#awaitTermination(long, TimeUnit)
      */
     public void disableAutoPost(long time, @Nonnull TimeUnit timeUnit){
+        CheckUtil.condition(time <= 0, "Time may not be less or equal to 0");
+        
         try{
             scheduler.shutdown();
             scheduler.awaitTermination(time, timeUnit);
@@ -255,7 +262,7 @@ public void postGuilds(@Nonnull JDA jda, @Nonnull BotBlockAPI botBlockAPI) throw
      */
     public void postGuilds(@Nonnull ShardManager shardManager, @Nonnull BotBlockAPI botBlockAPI) throws IOException, RatelimitedException{
         JDA shard = shardManager.getShardById(0);
-        CheckUtil.condition(shard == null, "Received invalid/null Shard (Shard ID: 0)");
+        CheckUtil.condition(shard == null, "Shard 0 of ShardManager was invalid (null).");
 
         JSONObject json = new JSONObject()
                 .put("server_count", shardManager.getGuildCache().size())