Full Javadoc

Author: Zabuzard

application/src/main/java/org/togetherjava/tjbot/Application.java

@@ -10,6 +10,9 @@
 import java.nio.file.Path;
 import java.sql.SQLException;
 
+/***
+ * Main class of the application. Use {@link #main(String[])} to start an instance of it.
+ */
 public enum Application {
     ;
 
@@ -21,6 +24,7 @@ public enum Application {
      * @param args command line arguments - [the token of the bot, the path to the database]
      */
     public static void main(final String[] args) {
+        // Parse arguments
         if (args.length != 2) {
             throw new IllegalArgumentException("Expected two arguments but " + args.length
                     + " arguments were provided. The first argument must be the token of the bot"
@@ -29,13 +33,20 @@ public static void main(final String[] args) {
         String token = args[0];
         String databasePath = args[1];
 
+        // Start
         try {
             runBot(token, Path.of(databasePath));
         } catch (Exception t) {
             logger.error("Unknown error", t);
         }
     }
 
+    /**
+     * Runs an instance of the bot, connecting to the given token and using the given database.
+     *
+     * @param token the Discord Bot token to connect with
+     * @param databasePath the path to the database to use
+     */
     public static void runBot(String token, Path databasePath) {
         logger.info("Starting bot...");
         try {

application/src/main/java/org/togetherjava/tjbot/DatabaseListener.java

@@ -12,11 +12,40 @@
 
 import java.util.Optional;
 
+/**
+ * Implementation of an example command to illustrate how to use a database.
+ * <p>
+ * The implemented commands are {@code !dbput} and {@code !dbget}. They act like some sort of simple
+ * {@code Map<String, String>}, allowing the user to store and retrieve key-value pairs from the
+ * database.
+ * <p>
+ * For example:
+ *
+ * <pre>
+ * {@code
+ * !dbput hello Hello World!
+ * // TJ-Bot: Saved under 'hello'.
+ * !dbget hello
+ * // TJ-Bot: Saved message: Hello World!
+ * }
+ * </pre>
+ */
 public final class DatabaseListener extends ListenerAdapter {
+    /**
+     * Logger for this class.
+     */
     private static final Logger logger = LoggerFactory.getLogger(DatabaseListener.class);
 
+    /**
+     * The database instance used by this command.
+     */
     private final Database database;
 
+    /**
+     * Creates a new command listener, using the given database
+     *
+     * @param database the database to store the key-value pairs in
+     */
     public DatabaseListener(Database database) {
         this.database = database;
     }
@@ -38,8 +67,18 @@ public void onMessageReceived(MessageReceivedEvent event) {
         }
     }
 
+    /**
+     * Handler for the {@code !dbput} command.
+     * <p>
+     * If the message is in the wrong format, it will respond to the user instead of throwing any
+     * exceptions.
+     *
+     * @param message the message to react to. For example {@code !dbput hello Hello World!}.
+     * @param event the event the message belongs to, mainly used to respond back to the user
+     */
     private void handlePutMessage(String message, MessageReceivedEvent event) {
         // !dbput hello Hello World!
+        // Parse message
         logger.info("#{}: Received '!dbput' command", event.getResponseNumber());
         String[] data = message.split(" ", 3);
         if (data.length != 3) {
@@ -51,6 +90,7 @@ private void handlePutMessage(String message, MessageReceivedEvent event) {
         String key = data[1];
         String value = data[2];
 
+        // Save the value in the database
         try {
             database.writeTransaction(ctx -> {
                 StorageRecord storageRecord =
@@ -67,8 +107,18 @@ private void handlePutMessage(String message, MessageReceivedEvent event) {
         }
     }
 
+    /**
+     * Handler for the {@code !dbget} command.
+     * <p>
+     * If the message is in the wrong format, it will respond to the user instead of throwing any
+     * exceptions.
+     *
+     * @param message the message to react to. For example {@code !dbget hello}.
+     * @param event the event the message belongs to, mainly used to respond back to the user
+     */
     private void handleGetMessage(String message, MessageReceivedEvent event) {
         // !dbget hello
+        // Parse message
         logger.info("#{}: Received '!dbget' command", event.getResponseNumber());
         String[] data = message.split(" ", 2);
         if (data.length != 2) {
@@ -79,6 +129,7 @@ private void handleGetMessage(String message, MessageReceivedEvent event) {
         }
         String key = data[1];
 
+        // Retrieve the value from the database
         try {
             Optional<StorageRecord> foundValue = database.read(context -> {
                 return Optional.ofNullable(context.selectFrom(Storage.STORAGE)

application/src/main/java/org/togetherjava/tjbot/PingPongListener.java

@@ -6,9 +6,32 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Implementation of an example command to illustrate how to use JDA.
+ * <p>
+ * The implemented command is {@code !ping}. The bot will respond with a message {@code Pong!}.
+ * <p>
+ * For example:
+ *
+ * <pre>
+ * {@code
+ * !ping
+ * // TJ-Bot: Pong!
+ * }
+ * </pre>
+ */
 public final class PingPongListener extends ListenerAdapter {
+    /**
+     * Logger for this class
+     */
     private static final Logger logger = LoggerFactory.getLogger(PingPongListener.class);
 
+    /**
+     * Handler for the {@code !ping} command. Will ignore any message that is not exactly
+     * {@code !ping}.
+     *
+     * @param event the event the message belongs to
+     */
     @Override
     public void onMessageReceived(MessageReceivedEvent event) {
         if (event.getAuthor().isBot()) {

application/src/main/java/org/togetherjava/tjbot/db/Database.java

@@ -16,23 +16,35 @@
 import java.util.concurrent.locks.ReentrantLock;
 
 /**
- * The main database class.
+ * The main database class used by the application.
+ * <p>
+ * Create an instance using {@link #Database(String)} and prefer to re-use it. The underlying
+ * connections are handled automatically by the system.
+ * <p>
+ * Instances of this class are thread-safe and can be used to concurrently write to the database.
  */
 public final class Database {
 
+    /**
+     * The DSL context for this database.
+     */
     private final DSLContext dslContext;
+    /**
+     * Lock used to implement thread-safety across this class. Any database modifying method should
+     * use this lock.
+     */
     private final Lock writeLock = new ReentrantLock();
 
     /**
-     * Creates a new database.
+     * Creates an instance of a new database.
      *
-     * @param jdbcUrl the url to the database
+     * @param jdbcUrl the url to the database in the format expected by JDBC
      * @throws SQLException if no connection could be established
      */
     public Database(String jdbcUrl) throws SQLException {
         SQLiteConfig sqliteConfig = new SQLiteConfig();
         sqliteConfig.enforceForeignKeys(true);
-        // In WAL mode only concurrent writes pose a problem so we synchronize on those
+        // In WAL mode only concurrent writes pose a problem, so we synchronize on those
         sqliteConfig.setJournalMode(SQLiteConfig.JournalMode.WAL);
 
         SQLiteDataSource dataSource = new SQLiteDataSource(sqliteConfig);
@@ -45,10 +57,12 @@ public Database(String jdbcUrl) throws SQLException {
     }
 
     /**
-     * Acquires read access to the database.
+     * Acquires read-only access to the database.
      *
-     * @return a way to interact with the database in a read only way
-     * @throws DatabaseException if an error occurs in the passed handler function
+     * @param action the action to apply to the DSL context, e.g. a query
+     * @param <T> the type returned by the given action
+     * @return the result returned by the given action
+     * @throws DatabaseException if an error occurs in the given action
      */
     public <T> T read(
             CheckedFunction<? super DSLContext, T, ? extends DataAccessException> action) {
@@ -60,9 +74,10 @@ public <T> T read(
     }
 
     /**
-     * Acquires read access to the database.
+     * Acquires read-only access to the database.
      *
-     * @throws DatabaseException if an error occurs in the passed handler function
+     * @param action the action that consumes the DSL context, e.g. a query
+     * @throws DatabaseException if an error occurs in the given action
      */
     public void read(CheckedConsumer<? super DSLContext, ? extends DataAccessException> action) {
         read(context -> {
@@ -74,8 +89,10 @@ public void read(CheckedConsumer<? super DSLContext, ? extends DataAccessExcepti
     /**
      * Acquires read and write access to the database.
      *
-     * @return a way to interact with the database
-     * @throws DatabaseException if an error occurs in the passed handler function
+     * @param action the action to apply to the DSL context, e.g. a query
+     * @param <T> the type returned by the given action
+     * @return the result returned by the given action
+     * @throws DatabaseException if an error occurs in the given action
      */
     public <T> T write(
             CheckedFunction<? super DSLContext, T, ? extends DataAccessException> action) {
@@ -92,7 +109,8 @@ public <T> T write(
     /**
      * Acquires read and write access to the database.
      *
-     * @throws DatabaseException if an error occurs in the passed handler function
+     * @param action the action to apply to the DSL context, e.g. a query
+     * @throws DatabaseException if an error occurs in the given action
      */
     public void write(CheckedConsumer<? super DSLContext, ? extends DataAccessException> action) {
         write(context -> {
@@ -107,8 +125,8 @@ public void write(CheckedConsumer<? super DSLContext, ? extends DataAccessExcept
      * @param handler the handler that is executed within the context of the transaction. The
      *        handler will be called once and its return value returned from the transaction.
      * @param <T> the handler's return type
-     * @return whatever the handler returned
-     * @throws DatabaseException if an error occurs in the passed handler function
+     * @return the object that is returned by the given handler
+     * @throws DatabaseException if an error occurs in the given handler function
      */
     public <T> T readTransaction(
             CheckedFunction<? super DSLContext, T, DataAccessException> handler) {
@@ -128,7 +146,7 @@ public <T> T readTransaction(
      *
      * @param handler the handler that is executed within the context of the transaction. It has no
      *        return value.
-     * @throws DatabaseException if an error occurs in the passed handler function
+     * @throws DatabaseException if an error occurs in the given handler function
      */
     public void readTransaction(
             CheckedConsumer<? super DSLContext, ? extends DataAccessException> handler) {
@@ -142,10 +160,10 @@ public void readTransaction(
      * Acquires a transaction that can read and write to the database.
      *
      * @param handler the handler that is executed within the context of the transaction. The
-     *        handler will be called once and its return value returned from the transaction.
-     * @param <T> the handler's return type
-     * @return whatever the handler returned
-     * @throws DatabaseException if an error occurs in the passed handler function
+     *        handler will be called once and its return value is returned from the transaction.
+     * @param <T> the return type of the handler
+     * @return the object that is returned by the given handler
+     * @throws DatabaseException if an error occurs in the given handler function
      */
     public <T> T writeTransaction(
             CheckedFunction<? super DSLContext, T, DataAccessException> handler) {
@@ -168,7 +186,7 @@ public <T> T writeTransaction(
      *
      * @param handler the handler that is executed within the context of the transaction. It has no
      *        return value.
-     * @throws DatabaseException if an error occurs in the passed handler function
+     * @throws DatabaseException if an error occurs in the given handler function
      */
     public void writeTransaction(
             CheckedConsumer<? super DSLContext, ? extends DataAccessException> handler) {
@@ -179,7 +197,9 @@ public void writeTransaction(
     }
 
     /**
-     * @return the database dsl context
+     * Gets the DSL context for this database.
+     *
+     * @return the DSL context
      */
     private DSLContext getDslContext() {
         return dslContext;

application/src/main/java/org/togetherjava/tjbot/db/DatabaseException.java

@@ -12,6 +12,11 @@ public class DatabaseException extends RuntimeException {
     @Serial
     private static final long serialVersionUID = -4215197259643585552L;
 
+    /**
+     * Creates a new instance of this exception with the given underlying cause.
+     *
+     * @param cause The cause of the exception
+     */
     public DatabaseException(Exception cause) {
         super(cause);
     }

application/src/main/java/org/togetherjava/tjbot/db/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * This package contains the database management of the application. See
+ * {@link org.togetherjava.tjbot.db.Database} to get started.
+ */
+package org.togetherjava.tjbot.db;

application/src/main/java/org/togetherjava/tjbot/util/CheckedConsumer.java

@@ -1,10 +1,12 @@
 package org.togetherjava.tjbot.util;
 
 /**
- * Represents a function that accepts a single input argument, returns a result and could possibly
+ * {@link java.util.function.Consumer} extension that can possibly throw an exception.
+ * <p>
+ * Represents a function that accepts a single input argument, returns no result and could possibly
  * throw an exception.
  *
- * @param <T> the type of the input to the function
+ * @param <T> the type of the input to the consumer
  * @param <E> the type of the exception
  */
 @FunctionalInterface
@@ -13,10 +15,10 @@ public interface CheckedConsumer<T, E extends Throwable> {
     /**
      * Performs this operation on the given argument.
      *
-     * @param t the input argument
+     * @param input the input argument
      * @throws E an exception if any occurs during the execution of the operation
      */
-    void accept(T t) throws E;
+    void accept(T input) throws E;
 
 }
 

application/src/main/java/org/togetherjava/tjbot/util/CheckedFunction.java

@@ -1,6 +1,8 @@
 package org.togetherjava.tjbot.util;
 
 /**
+ * {@link java.util.function.Function} extension that can possibly throw an exception.
+ * <p>
  * Represents a function that accepts a single input argument, returns a result and could possibly
  * throw an exception.
  *
@@ -14,11 +16,11 @@ public interface CheckedFunction<T, R, E extends Throwable> {
     /**
      * Performs this operation on the given argument.
      *
-     * @param t the input argument
+     * @param input the input argument
      * @return R on successful evaluation
      * @throws E an exception if any occurs during the execution of the operation
      */
-    R accept(T t) throws E;
+    R accept(T input) throws E;
 
 }
 

application/src/main/java/org/togetherjava/tjbot/util/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * General utility package containing various helper classes and methods used throughout the
+ * application.
+ */
+package org.togetherjava.tjbot.util;