Merge pull request #301 from andrewlalis/andrew/db_cleanup

Improved Javadoc For Db Interfaces, Added countf Function

Author: jasonlessenich

src/main/java/net/javadiscord/javabot/data/h2db/ConnectionFunction.java

@@ -4,7 +4,8 @@
 import java.sql.SQLException;
 
 /**
- * Interface for connecting to the H2 SQL Database.
+ * Functional interface for a function which produces some object using a
+ * connection.
  *
  * @param <T> The generic type that is returned.
  */

src/main/java/net/javadiscord/javabot/data/h2db/DbActions.java

@@ -84,10 +84,11 @@ public static <T> CompletableFuture<T> mapQueryAsync(String query, StatementModi
 	}
 
 	/**
-	 * Counts the amount of rows that fit the given query.
+	 * Gets a count, using a query which <strong>must</strong> return a long
+	 * integer value as the first column of the result set.
 	 *
 	 * @param query    The query.
-	 * @param modifier The {@link StatementModifier}.
+	 * @param modifier A modifier to use to set parameters for the query.
 	 * @return The column value.
 	 */
 	public static long count(String query, StatementModifier modifier) {
@@ -103,13 +104,18 @@ public static long count(String query, StatementModifier modifier) {
 	}
 
 	/**
-	 * Counts the amount of rows that fit the given query.
+	 * Gets a count, using a query which <strong>must</strong> return a long
+	 * integer value as the first column of the result set.
 	 *
 	 * @param query    The query.
 	 * @return The column value.
 	 */
 	public static long count(String query) {
-		try (var rs = Bot.dataSource.getConnection().createStatement().executeQuery(query)) {
+		try (
+				var conn = Bot.dataSource.getConnection();
+				var stmt = conn.createStatement()
+		) {
+			var rs = stmt.executeQuery(query);
 			if (!rs.next()) return 0;
 			return rs.getLong(1);
 		} catch (SQLException e) {
@@ -118,6 +124,23 @@ public static long count(String query) {
 		}
 	}
 
+	/**
+	 * Convenience method similar to {@link DbActions#count(String, StatementModifier)}
+	 * which allows for getting the count from a query using simple string
+	 * formatting instead of having to define a statement modifier.
+	 * <p>
+	 *     <strong>WARNING</strong>: This method should NEVER be called with
+	 *     user-provided data.
+	 * </p>
+	 *
+	 * @param queryFormat The format string.
+	 * @param args The set of arguments to pass to the formatter.
+	 * @return The count.
+	 */
+	public static long countf(String queryFormat, Object... args) {
+		return count(String.format(queryFormat, args));
+	}
+
 	/**
 	 * Updates a database table.
 	 *

src/main/java/net/javadiscord/javabot/data/h2db/TransactionFunction.java

@@ -3,7 +3,9 @@
 import java.sql.Connection;
 
 /**
- * Simple Interface that handles transactions.
+ * Interface that defines a function that executes using a transaction.
+ * It is possible for an exception to be thrown, in which case the transaction
+ * will attempt to roll back.
  */
 public interface TransactionFunction {
 	void execute(Connection c) throws Exception;