chore: optimize usage of webhooks (#261)

src/main/java/minevalley/core/api/Core.java

@@ -63,6 +63,7 @@
 import javax.annotation.Nonnegative;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
+import java.net.URL;
 import java.sql.SQLException;
 import java.text.SimpleDateFormat;
 import java.time.DayOfWeek;
@@ -1179,7 +1180,7 @@ public static Reminder createReminder(@Nonnegative int hours, @Nonnegative int m
      * @throws IllegalArgumentException if the URL is null
      */
     @Nonnull
-    public static Webhook createWebhook(@Nonnull String url) throws IllegalArgumentException {
+    public static Webhook createWebhook(@Nonnull URL url) throws IllegalArgumentException {
         return server.createWebhook(url);
     }
 

src/main/java/minevalley/core/api/CoreServer.java

@@ -58,6 +58,7 @@
 import javax.annotation.Nonnegative;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
+import java.net.URL;
 import java.sql.SQLException;
 import java.time.DayOfWeek;
 import java.util.List;
@@ -261,7 +262,7 @@ public interface CoreServer {
     Reminder createReminder(int hours, int minutes, @Nonnull Runnable callback, List<DayOfWeek> weekdays) throws IllegalArgumentException;
 
     @Nonnull
-    Webhook createWebhook(@Nonnull String url) throws IllegalArgumentException;
+    Webhook createWebhook(@Nonnull URL url) throws IllegalArgumentException;
 
     @Nonnull
     EmbeddedMessage createEmbeddedMessage();

src/main/java/minevalley/core/api/discord/EmbeddedMessage.java

@@ -1,24 +1,116 @@
 package minevalley.core.api.discord;
 
+import org.jetbrains.annotations.Contract;
+
+import javax.annotation.Nonnull;
 import java.awt.*;
 
+@SuppressWarnings("unused")
 public interface EmbeddedMessage {
 
-    EmbeddedMessage setTitle(String title);
+    /**
+     * Sets the title of the embedded message.
+     *
+     * @param title The title of the embedded message.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the title is null.
+     */
+    @Nonnull
+    @Contract("_ -> this")
+    EmbeddedMessage setTitle(@Nonnull String title) throws IllegalArgumentException;
 
-    EmbeddedMessage setDescription(String description);
+    /**
+     * Sets the description of the embedded message.
+     *
+     * @param description The description of the embedded message.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the description is null.
+     */
+    @Nonnull
+    @Contract("_ -> this")
+    EmbeddedMessage setDescription(@Nonnull String description) throws IllegalArgumentException;
 
-    EmbeddedMessage setAuthor(String name, String url, String iconUrl);
+    /**
+     * Sets the author of the embedded message.
+     *
+     * @param name    The name of the author.
+     * @param url     The URL of the author.
+     * @param iconUrl The URL of the author's icon.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the name, URL or icon URL is null.
+     */
+    @Nonnull
+    @Contract("_, _, _ -> this")
+    EmbeddedMessage setAuthor(@Nonnull String name, @Nonnull String url, @Nonnull String iconUrl) throws IllegalArgumentException;
 
-    EmbeddedMessage setThumbnail(String url);
+    /**
+     * Sets the thumbnail of the embedded message.
+     *
+     * @param url The URL of the thumbnail.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the URL is null.
+     */
+    @Nonnull
+    @Contract("_ -> this")
+    EmbeddedMessage setThumbnail(@Nonnull String url) throws IllegalArgumentException;
 
-    EmbeddedMessage setColor(Color color);
+    /**
+     * Sets the color of the embedded message.
+     *
+     * @param color The color of the embedded message.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the color is null.
+     */
+    @Nonnull
+    @Contract("_ -> this")
+    EmbeddedMessage setColor(@Nonnull Color color) throws IllegalArgumentException;
 
-    EmbeddedMessage addField(String title, String text, boolean inline);
+    /**
+     * Adds a field to the embedded message.
+     *
+     * @param title  The title of the field.
+     * @param text   The text of the field.
+     * @param inline Whether the field should be inline or not.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the title or text is null.
+     */
+    @Nonnull
+    @Contract("_, _, _ -> this")
+    EmbeddedMessage addField(@Nonnull String title, @Nonnull String text, boolean inline) throws IllegalArgumentException;
 
-    EmbeddedMessage setImage(String url);
+    /**
+     * Sets the image of the embedded message.
+     *
+     * @param url The URL of the image.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the URL is null.
+     */
+    @Nonnull
+    @Contract("_ -> this")
+    EmbeddedMessage setImage(@Nonnull String url) throws IllegalArgumentException;
 
-    EmbeddedMessage setFooter(String footer, String iconUrl);
+    /**
+     * Sets the footer of the embedded message.
+     *
+     * @param footer  The footer of the embedded message.
+     * @param iconUrl The URL of the footer's icon.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the footer is null.
+     */
+    @Nonnull
+    @Contract("_, _ -> this")
+    EmbeddedMessage setFooter(@Nonnull String footer, @Nonnull String iconUrl) throws IllegalArgumentException;
 
-    EmbeddedMessage setFooter(String footer);
+    /**
+     * Sets the footer of the embedded message.
+     *
+     * @param footer The footer of the embedded message.
+     * @return The current instance of the embedded message.
+     * @throws IllegalArgumentException If the footer is null.
+     */
+    @Nonnull
+    @Contract("_ -> this")
+    default EmbeddedMessage setFooter(@Nonnull String footer) throws IllegalArgumentException {
+        return setFooter(footer, "");
+    }
 }

src/main/java/minevalley/core/api/discord/Webhook.java

@@ -1,16 +1,46 @@
 package minevalley.core.api.discord;
 
+import org.jetbrains.annotations.Contract;
+
+import javax.annotation.Nonnull;
 import java.io.IOException;
 
 /**
  * This Webhook-builder is meant to help you to create discord-webhooks.
- * You can find helpful information here: <a href="https://birdie0.github.io/discord-webhooks-guide/discord_webhook.html">...</a>
+ * You can find helpful information <a href="https://birdie0.github.io/discord-webhooks-guide/discord_webhook.html">here</a>.
  */
+@SuppressWarnings("unused")
 public interface Webhook {
 
-    Webhook setUsername(String username);
+    /**
+     * Sets the username of the webhook.
+     *
+     * @param username The username of the webhook.
+     * @return The current instance of the webhook.
+     * @throws IllegalArgumentException If the username is null.
+     */
+    @Nonnull
+    @Contract("_ -> this")
+    Webhook setUsername(@Nonnull String username) throws IllegalArgumentException;
 
-    Webhook setAvatar(String url);
+    /**
+     * Sets the avatar of the webhook.
+     *
+     * @param url The URL of the avatar.
+     * @return The current instance of the webhook.
+     * @throws IllegalArgumentException If the URL is null.
+     */
+    @Nonnull
+    @Contract("_ -> this")
+    Webhook setAvatar(@Nonnull String url) throws IllegalArgumentException;
 
-    void send(EmbeddedMessage... message) throws IOException;
+    /**
+     * Sends the given messages to the discord-webhook.
+     *
+     * @param message The messages to send.
+     * @throws IOException              If an I/O error occurs.
+     * @throws IllegalArgumentException If the message is null, or the given {@code EmbeddedMessage} is another implementation than our internal.
+     */
+    @Contract(pure = true)
+    void send(@Nonnull EmbeddedMessage... message) throws IOException, IllegalArgumentException;
 }