feat(core): abstract receive methods

add functionality by abstracting receive methods.
add #receiveAction() to allow developers to handle queuing
add documentation

Signed-off-by: Jasper Lutz Severino <jasperlutzseverino@gmail.com>

core/src/main/java/com/lutzseverino/discordbooks/discord/channel/Receivable.java

@@ -5,9 +5,13 @@
 import org.jetbrains.annotations.NotNull;
 
 public interface Receivable {
-    void receive(Sendable message);
+    void receive(@NotNull Sendable message);
 
-    void receive(Book book);
+    void receive(@NotNull Book book);
 
     void receive(@NotNull Book book, int index);
+
+    void receivePerm(@NotNull Book book, int index);
+
+    void receiveTemp(@NotNull Book book, int index);
 }

jda/src/main/java/com/lutzseverino/discordbooks/jda/discord/channel/JDAReceivable.java

@@ -10,6 +10,8 @@
 import net.dv8tion.jda.api.requests.restaction.MessageAction;
 import org.jetbrains.annotations.NotNull;
 
+import javax.annotation.CheckReturnValue;
+
 public class JDAReceivable implements Receivable {
     private final MessageChannel channel;
 
@@ -21,20 +23,70 @@ public JDAReceivable(@NotNull Guild guild, String channelId) {
         this(guild.getTextChannelById(channelId));
     }
 
+    /**
+     * Builds a JDA message and sends it.
+     *
+     * @param sendable the {@link Sendable} to send
+     */
     @Override public void receive(@NotNull Sendable sendable) {
         channel.sendMessage(JDAMessage.buildMessage(sendable)).queue();
     }
 
-    @Override public void receive(Book book) {
+    /**
+     * If the book is permanent, the first page will be sent and
+     * queued, otherwise, it will additionally be set in the
+     * temporary database.
+     *
+     * @param book the {@link Book} to send
+     */
+    @Override public void receive(@NotNull Book book) {
         receive(book, 0);
     }
 
+    /**
+     * If the book is permanent, the page at the provided index
+     * will be sent and queued, otherwise, it will additionally
+     * be set in the temporary database.
+     *
+     * @param book  the {@link Book} to send
+     * @param index the page index
+     */
     @Override public void receive(@NotNull Book book, int index) {
-        MessageAction action = channel.sendMessage(JDAMessage.buildMessage(book.getPage(index)));
+        if (!book.getId().isEmpty()) receivePerm(book, index);
+        else receiveTemp(book, index);
+    }
 
-        if (book.getId().isEmpty())
-            action.queue(message -> DiscordBooks.getTemporaryDatabase().set(message.getId(), book));
-        else action.queue();
+    /**
+     * Sends the book's page at the provided index and queues it.
+     *
+     * @param book  the {@link Book} to send
+     * @param index the page index
+     */
+    @Override public void receivePerm(@NotNull Book book, int index) {
+        receiveAction(book, index).queue();
     }
 
+    /**
+     * Sends the book's page at the provided index, sets it to
+     * the temporary database and queues it.
+     *
+     * @param book  the {@link Book} to send
+     * @param index the page index
+     */
+    @Override public void receiveTemp(@NotNull Book book, int index) {
+        channel.sendMessage(JDAMessage.buildMessage(book.getPage(index)))
+                .queue(message -> DiscordBooks.getTemporaryDatabase().set(message.getId(), book));
+    }
+
+    /**
+     * Sends the book's page at the provided index.
+     *
+     * @param book  the {@link Book} to send
+     * @param index the page index
+     * @return the created {@link MessageAction}
+     */
+    @CheckReturnValue
+    public MessageAction receiveAction(@NotNull Book book, int index) {
+        return channel.sendMessage(JDAMessage.buildMessage(book.getPage(index)));
+    }
 }