Add comments to KeyValueTable, KeyValueConnection implements KeyValueTable

Database/src/main/java/fr/altarik/toolbox/database/keyvalue/KeyValueConnection.java

@@ -2,6 +2,7 @@ package fr.altarik.toolbox.database.keyvalue;
 
 import fr.altarik.toolbox.database.SqlConnection;
 import net.minecraft.util.Pair;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.sql.PreparedStatement;
@@ -10,16 +11,17 @@ import java.sql.SQLException;
 import java.sql.Statement;
 import java.util.List;
 
-public class KeyValueConnection {
+public class KeyValueConnection implements KeyValueTable {
 
     private final SqlConnection connection;
     private final String tableName;
     private final List<KeyValueBuilder.AdditionalColumn> additionColumns;
 
-    public KeyValueConnection(SqlConnection connection, String tableName, List<KeyValueBuilder.AdditionalColumn> additionalColumns) throws SQLException {
+    public KeyValueConnection(@NotNull SqlConnection connection, @NotNull String tableName, @NotNull List<KeyValueBuilder.AdditionalColumn> additionalColumns) throws SQLException {
         this.connection = connection;
         this.tableName = tableName;
         this.additionColumns = additionalColumns;
+        connection.checkConnection();
 
         try(Statement statement = connection.getConnection().createStatement()) {
             StringBuilder sql = new StringBuilder("CREATE TABLE IF NOT EXISTS ").append(tableName).append("(id SERIAL,");
@@ -47,7 +49,9 @@ public class KeyValueConnection {
         }
     }
 
+    @Override
     public @Nullable String getValueById(int id) throws SQLException {
+        connection.checkConnection();
         try(PreparedStatement preparedStatement = connection.getConnection().prepareStatement("SELECT value FROM " + tableName + " WHERE id=?")) {
             preparedStatement.setInt(1, id);
             ResultSet resultSet = preparedStatement.executeQuery();
@@ -58,8 +62,10 @@ public class KeyValueConnection {
         }
     }
 
-    public @Nullable String getValueByAdditionalColumnAndKey(String key, List<Pair<KeyValueBuilder.AdditionalColumn, Object>> additionalColumns) throws SQLException {
-        StringBuilder sql = new StringBuilder("SELECT value FROM ").append(tableName).append(" WHERE key=? AND ");
+    @Override
+    public @Nullable Result getValueByAdditionalColumnAndKey(String key, List<Pair<KeyValueBuilder.AdditionalColumn, Object>> additionalColumns) throws SQLException {
+        connection.checkConnection();
+        StringBuilder sql = new StringBuilder("SELECT id, value FROM ").append(tableName).append(" WHERE key=? AND ");
         for(int i = 0; i < additionalColumns.size(); ++i) {
             sql.append(additionalColumns.get(i).getLeft().columnName()).append("=?");
             if(i != additionalColumns.size() - 1) {
@@ -74,12 +80,14 @@ public class KeyValueConnection {
             }
             ResultSet resultSet = preparedStatement.executeQuery();
             if(resultSet.next())
-                return resultSet.getString(1);
+                return new Result(resultSet.getString(1), resultSet.getString(2));
             return null;
         }
     }
 
+    @Override
     public long insertValue(String key, String value, List<Pair<KeyValueBuilder.AdditionalColumn, Object>> additionalColumns) throws SQLException {
+        connection.checkConnection();
         StringBuilder sql = new StringBuilder("INSERT INTO " + tableName + "(key, value");
         for(int i = 0; i < additionalColumns.size(); ++i) {
             if(i != additionalColumns.size() - 1) {
@@ -112,7 +120,9 @@ public class KeyValueConnection {
         }
     }
 
+    @Override
     public void updateValueById(String key, String value) throws SQLException {
+        connection.checkConnection();
         try(PreparedStatement preparedStatement = connection.getConnection().prepareStatement("UPDATE " + tableName + " SET value=? WHERE key=?")) {
             preparedStatement.setString(1, value);
             preparedStatement.setString(2, key);
@@ -121,7 +131,9 @@ public class KeyValueConnection {
 
     }
 
+    @Override
     public void updateValue(String key, String value, List<Pair<KeyValueBuilder.AdditionalColumn, Object>> additionalColumns) throws SQLException {
+        connection.checkConnection();
         StringBuilder sql = new StringBuilder("UPDATE " + tableName + " SET value=? WHERE key=?");
         for(int i = 0; i < additionalColumns.size(); ++i) {
             if(i != additionalColumns.size() - 1) {
@@ -140,6 +152,7 @@ public class KeyValueConnection {
         }
     }
 
+    @Override
     public List<KeyValueBuilder.AdditionalColumn> getAdditionColumns() {
         return additionColumns;
     }

Database/src/main/java/fr/altarik/toolbox/database/keyvalue/KeyValueTable.java

@@ -0,0 +1,72 @@
+package fr.altarik.toolbox.database.keyvalue;
+
+import net.minecraft.util.Pair;
+import org.jetbrains.annotations.Nullable;
+
+import java.sql.SQLException;
+import java.util.List;
+
+public interface KeyValueTable {
+
+    /**
+     * Return the value which correspond to the given id
+     * @param id primary key, unique id of the key value table
+     * @return the correspond value
+     * @throws SQLException when connection is lost
+     */
+    @Nullable String getValueById(int id) throws SQLException;
+
+    /**
+     * <p>Return the first value associated with the key and all the additional columns values given.</p>
+     * <p>In a perfect context, key and additional columns combinaison return a pseudo unique result.</p>
+     *
+     * @param key               String key of associated to the value, doesn't require to be unique
+     * @param additionalColumns Object keys of associated to the value, doesn't require to be unique
+     * @return first (id, value) pair associated with the key and additonal columns combinaison
+     * @throws SQLException if connection is lost, or if additional columns name or value format is incorrect
+     */
+    @Nullable Result getValueByAdditionalColumnAndKey(String key, List<Pair<KeyValueBuilder.AdditionalColumn, Object>> additionalColumns) throws SQLException;
+
+    /**
+     * <p>Insert a new value in the table, associate key and additional columns with the value</p>
+     * <p>Key and additional columns doesn't need to be unique, the combinaison of them have the goal to be unique or it isn't a hard requirement</p>
+     * @param key String key which will be associated with the value, doesn't require to be unique
+     * @param value String value which will be stored in the database
+     * @param additionalColumns Additional columns which will be associated with the value, doesn't require to be unique
+     * @return the id (unique id) of the newly inserted value
+     * @throws SQLException if connection is lost, or if additional columns name or value format is incorrect
+     */
+    long insertValue(String key, String value, List<Pair<KeyValueBuilder.AdditionalColumn, Object>> additionalColumns) throws SQLException;
+
+    /**
+     * Update a row associated with the unique key {@code id} with the new value given in parameter
+     * @param key unique key associated with the value
+     * @param value new value
+     * @throws SQLException if connection is lost
+     */
+    void updateValueById(String key, String value) throws SQLException;
+
+    /**
+     * Update all rows associated with the key and additional columns combinaisons with the new value given in parameter
+     * @param key String key which will is associated with the value, doesn't require to be unique
+     * @param value new value
+     * @param additionalColumns Additional columns which are associated with the value, doesn't require to be unique
+     * @throws SQLException if connection is lost, or if additional columns name or value format is incorrect
+     */
+    void updateValue(String key, String value, List<Pair<KeyValueBuilder.AdditionalColumn, Object>> additionalColumns) throws SQLException;
+
+    /**
+     * Give the declared additional columns given during initialisation of the class
+     * @return list of declared additional columns
+     */
+    List<KeyValueBuilder.AdditionalColumn> getAdditionColumns();
+
+    /**
+     * Result unique id and value pair stored in the table when using {@link KeyValueTable#getValueByAdditionalColumnAndKey(String, List)}
+     * @param id unique id the row
+     * @param value value store in the same row as {@code id}
+     */
+    record Result(String id, String value) {
+
+    }
+}