From 11680e2ba818434781ac2b20b1d20b0f45fa5af0 Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Sun, 29 Dec 2024 18:47:12 +0100 Subject: [PATCH 01/14] delete database files --- src/main/java/minevalley/core/api/Core.java | 4 - .../java/minevalley/core/api/CoreServer.java | 4 - .../core/api/database/DatabaseEntry.java | 134 ------------------ .../api/database/DatabaseEntryCollection.java | 18 --- .../core/api/database/DatabaseTable.java | 25 ---- .../minevalley/core/api/database/Value.java | 12 -- .../core/api/events/StatisticCreateEvent.java | 2 - .../core/api/users/OnTimeHandler.java | 1 - 8 files changed, 200 deletions(-) delete mode 100644 src/main/java/minevalley/core/api/database/DatabaseEntry.java delete mode 100644 src/main/java/minevalley/core/api/database/DatabaseEntryCollection.java delete mode 100644 src/main/java/minevalley/core/api/database/DatabaseTable.java delete mode 100644 src/main/java/minevalley/core/api/database/Value.java diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java index 9ad74893..790ea7d5 100644 --- a/src/main/java/minevalley/core/api/Core.java +++ b/src/main/java/minevalley/core/api/Core.java @@ -4,10 +4,6 @@ import minevalley.core.api.armorstand.FakeArmorStand; import minevalley.core.api.corporations.Group; import minevalley.core.api.corporations.companies.*; -import minevalley.core.api.database.DatabaseEntry; -import minevalley.core.api.database.DatabaseEntryCollection; -import minevalley.core.api.database.DatabaseTable; -import minevalley.core.api.database.Value; import minevalley.core.api.discord.EmbeddedMessage; import minevalley.core.api.discord.Webhook; import minevalley.core.api.economy.BankAccount; diff --git a/src/main/java/minevalley/core/api/CoreServer.java b/src/main/java/minevalley/core/api/CoreServer.java index 44e6ff16..dbe54945 100644 --- a/src/main/java/minevalley/core/api/CoreServer.java +++ b/src/main/java/minevalley/core/api/CoreServer.java @@ -4,10 +4,6 @@ import minevalley.core.api.armorstand.FakeArmorStand; import minevalley.core.api.corporations.Group; import minevalley.core.api.corporations.companies.*; -import minevalley.core.api.database.DatabaseEntry; -import minevalley.core.api.database.DatabaseEntryCollection; -import minevalley.core.api.database.DatabaseTable; -import minevalley.core.api.database.Value; import minevalley.core.api.discord.EmbeddedMessage; import minevalley.core.api.discord.Webhook; import minevalley.core.api.economy.BankAccount; diff --git a/src/main/java/minevalley/core/api/database/DatabaseEntry.java b/src/main/java/minevalley/core/api/database/DatabaseEntry.java deleted file mode 100644 index f93a8a09..00000000 --- a/src/main/java/minevalley/core/api/database/DatabaseEntry.java +++ /dev/null @@ -1,134 +0,0 @@ -package minevalley.core.api.database; - -import minevalley.core.api.Registrant; -import org.bukkit.Location; -import org.bukkit.block.Block; -import org.bukkit.inventory.ItemStack; - -import java.sql.Array; - -public interface DatabaseEntry { - - /** - * Removes the specific database entry from the table. - */ - void remove(); - - /** - * Checks if the database-entry exists. - * - * @return true if the selected database entry exists in the table - */ - boolean exists(); - - /** - * Changes a value of the selected entry. - * - * @param value value object with the column and the new value - */ - void changeValue(Value value); - - /** - * Gets the string at the given column. - * - * @param column name of the column - * @return string at given column from the selected database entry - */ - String getString(String column); - - /** - * Gets the integer at the given column. - * - * @param column name of the column - * @return integer at given column from the selected database entry - */ - int getInteger(String column); - - /** - * Gets the boolean at the given column. - * - * @param column name of the column - * @return boolean at given column from the selected database entry - */ - boolean getBoolean(String column); - - /** - * Gets the double at the given column. - * - * @param column name of the column - * @return double at given column from the selected database entry - */ - double getDouble(String column); - - /** - * Gets the float at the given column. - * - * @param column name of the column - * @return float at given column from the selected database entry - */ - float getFloat(String column); - - /** - * Gets the long at the given column. - * - * @param column name of the column - * @return long at given column from the selected database entry - */ - long getLong(String column); - - /** - * Gets the byte at the given column. - * - * @param column name of the column - * @return byte at given column from the selected database entry - */ - byte getByte(String column); - - /** - * Gets the array at the given column. - * - * @param column name of the column - * @return array at given column from the selected database entry - */ - Array getArray(String column); - - /** - * Gets the location at the given column (with pitch & yaw). - * - * @param column name of the column - * @return location at given column from the selected database entry - */ - Location getLocation(String column); - - /** - * Gets the block at the given column. - * - * @param column name of the column - * @return block at given column from the selected database entry - */ - Block getBlock(String column); - - /** - * Gets the registrant at the given column. - * - * @param column name of the column - * @return registrant at given column from the selected database entry - */ - Registrant getRegistrant(String column); - - /** - * Gets the itemstack at the given column. - * - * @param column name of the column - * @return itemstack at given column from the selected database entry - */ - ItemStack getItemStack(String column); - - /** - * Gets the itemstack[] at the given column. - * - * @param column name of the column - * @return itemstack[] at given column from the selected database entry - */ - ItemStack[] getItemStacks(String column); -} \ No newline at end of file diff --git a/src/main/java/minevalley/core/api/database/DatabaseEntryCollection.java b/src/main/java/minevalley/core/api/database/DatabaseEntryCollection.java deleted file mode 100644 index 327c7196..00000000 --- a/src/main/java/minevalley/core/api/database/DatabaseEntryCollection.java +++ /dev/null @@ -1,18 +0,0 @@ -package minevalley.core.api.database; - -import java.util.List; - -public interface DatabaseEntryCollection { - - /** - * Gets a list of all entries in this collection. - * - * @return list of database entries - */ - List getEntries(); - - /** - * Removes every single entry of this collection from the database. - */ - void remove(); -} \ No newline at end of file diff --git a/src/main/java/minevalley/core/api/database/DatabaseTable.java b/src/main/java/minevalley/core/api/database/DatabaseTable.java deleted file mode 100644 index 8b54e8a4..00000000 --- a/src/main/java/minevalley/core/api/database/DatabaseTable.java +++ /dev/null @@ -1,25 +0,0 @@ -package minevalley.core.api.database; - -import java.util.List; - -public interface DatabaseTable { - - /** - * Gets all entries in the table - * - * @return list of all database-entries - */ - List getEntries(); - - /** - * Removes all entries from this table - */ - void clear(); - - /** - * Adds a new entry with the given values into the table - * - * @param entries values and their target column - */ - void addEntry(Value... entries); -} \ No newline at end of file diff --git a/src/main/java/minevalley/core/api/database/Value.java b/src/main/java/minevalley/core/api/database/Value.java deleted file mode 100644 index 880c2315..00000000 --- a/src/main/java/minevalley/core/api/database/Value.java +++ /dev/null @@ -1,12 +0,0 @@ -package minevalley.core.api.database; - -import lombok.AllArgsConstructor; -import lombok.Getter; - -@Getter -@AllArgsConstructor -public final class Value { - - private final String column; - private final Object value; -} \ No newline at end of file diff --git a/src/main/java/minevalley/core/api/events/StatisticCreateEvent.java b/src/main/java/minevalley/core/api/events/StatisticCreateEvent.java index 734c7a79..41402928 100644 --- a/src/main/java/minevalley/core/api/events/StatisticCreateEvent.java +++ b/src/main/java/minevalley/core/api/events/StatisticCreateEvent.java @@ -1,8 +1,6 @@ package minevalley.core.api.events; import lombok.RequiredArgsConstructor; -import minevalley.core.api.database.DatabaseEntry; -import minevalley.core.api.database.Value; import org.bukkit.event.Event; import org.bukkit.event.HandlerList; diff --git a/src/main/java/minevalley/core/api/users/OnTimeHandler.java b/src/main/java/minevalley/core/api/users/OnTimeHandler.java index 3fd9351d..3d0d9e63 100644 --- a/src/main/java/minevalley/core/api/users/OnTimeHandler.java +++ b/src/main/java/minevalley/core/api/users/OnTimeHandler.java @@ -1,7 +1,6 @@ package minevalley.core.api.users; import lombok.Setter; -import minevalley.core.api.database.Value; import java.time.LocalDate; import java.util.Map; From 1a416075eea63d5898c5bced08df76a773f9bc63 Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Sun, 29 Dec 2024 18:49:28 +0100 Subject: [PATCH 02/14] remove database usage --- src/main/java/minevalley/core/api/Core.java | 85 ------------------- .../java/minevalley/core/api/CoreServer.java | 14 --- .../core/api/events/StatisticCreateEvent.java | 8 +- 3 files changed, 2 insertions(+), 105 deletions(-) diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java index 790ea7d5..4b1e88df 100644 --- a/src/main/java/minevalley/core/api/Core.java +++ b/src/main/java/minevalley/core/api/Core.java @@ -314,91 +314,6 @@ public static void sendDebug(@Nonnull DebugType type, @Nonnull String message) { server.sendDebug(type, removeColorCodes(message)); } - /** - * Gets the specific database-entry from the specified table with the specified value in the column. - * If there are more than one entry, that math the given description, this gets the first one. - * If you want to get multiple entries, use database-collection, or database-table! - * - * @param tableName name of the table as string - * @param searchValue value according to which the entries are filtered in a specific column - * @return the first database-entry that matches the given description - */ - public static DatabaseEntry getDatabaseEntry(String tableName, Value searchValue) { - return server.getDatabaseEntry(tableName, searchValue); - } - - /** - * Gets the specific database-entry from the specified table with the specified value in the column. - * If there are more than one entry, that math the given description, this gets the first one. - * If you want to get multiple entries, use database-collection, or database-table! - * - * @param tableName name of the table as string - * @param searchValues value according to which the entries are filtered in a specific column - * @return the first database-entry that matches the given description - */ - public static DatabaseEntry getDatabaseEntryAnd(String tableName, Value... searchValues) { - return server.getDatabaseEntryAnd(tableName, searchValues); - } - - /** - * Gets the specific database-entry from the specified table with the specified value in the column. - * If there are more than one entry, that math the given description, this gets the first one. - * If you want to get multiple entries, use database-collection, or database-table! - * - * @param tableName name of the table as string - * @param searchValues value according to which the entries are filtered in a specific column - * @return the first database-entry that matches the given description - */ - public static DatabaseEntry getDatabaseEntryOr(String tableName, Value... searchValues) { - return server.getDatabaseEntryOr(tableName, searchValues); - } - - /** - * Gets a database-collection from the specified table with the specified value in the column. - * This gets all the entries that match the description. If you're searching for one single entry, use database-entry! - * - * @param tableName name of the table as string - * @param searchValue value according to which the entries are filtered in a specific column - * @return a collection of all database-entries in this table, that matches the given description - */ - public static DatabaseEntryCollection getDatabaseEntryCollection(String tableName, Value searchValue) { - return server.getDatabaseEntryCollection(tableName, searchValue); - } - - /** - * Gets a database-collection from the specified table with the specified value in the column. - * This gets all the entries that match the description. If you're searching for one single entry, use database-entry! - * - * @param tableName name of the table as string - * @param searchValues value according to which the entries are filtered in a specific column - * @return a collection of all database-entries in this table, that matches the given description - */ - public static DatabaseEntryCollection getDatabaseEntryCollectionAnd(String tableName, Value... searchValues) { - return server.getDatabaseEntryCollectionAnd(tableName, searchValues); - } - - /** - * Gets a database-collection from the specified table with the specified value in the column. - * This gets all the entries that match the description. If you're searching for one single entry, use database-entry! - * - * @param tableName name of the table as string - * @param searchValues value according to which the entries are filtered in a specific column - * @return a collection of all database-entries in this table, that matches the given description - */ - public static DatabaseEntryCollection getDatabaseEntryCollectionOr(String tableName, Value... searchValues) { - return server.getDatabaseEntryCollectionOr(tableName, searchValues); - } - - /** - * Gets the database-table with the specific name. - * - * @param tableName name of the database-table - * @return database-table with specific name - */ - public static DatabaseTable getDatabaseTable(String tableName) { - return server.getDatabaseTable(tableName); - } - /** * Sets the setting with the given key. *

diff --git a/src/main/java/minevalley/core/api/CoreServer.java b/src/main/java/minevalley/core/api/CoreServer.java index dbe54945..94a8b2dc 100644 --- a/src/main/java/minevalley/core/api/CoreServer.java +++ b/src/main/java/minevalley/core/api/CoreServer.java @@ -107,20 +107,6 @@ public interface CoreServer { void sendDebug(@Nonnull DebugType type, @Nonnull String message); - DatabaseEntry getDatabaseEntry(String tableName, Value searchValue); - - DatabaseEntry getDatabaseEntryAnd(String tableName, Value... searchValues); - - DatabaseEntry getDatabaseEntryOr(String tableName, Value... searchValues); - - DatabaseEntryCollection getDatabaseEntryCollection(String tableName, Value searchValue); - - DatabaseEntryCollection getDatabaseEntryCollectionAnd(String tableName, Value... searchValues); - - DatabaseEntryCollection getDatabaseEntryCollectionOr(String tableName, Value... searchValues); - - DatabaseTable getDatabaseTable(String tableName); - void setSetting(@Nonnull String key, @Nonnull String value) throws IllegalArgumentException; String getSetting(String key); diff --git a/src/main/java/minevalley/core/api/events/StatisticCreateEvent.java b/src/main/java/minevalley/core/api/events/StatisticCreateEvent.java index 41402928..d63ac323 100644 --- a/src/main/java/minevalley/core/api/events/StatisticCreateEvent.java +++ b/src/main/java/minevalley/core/api/events/StatisticCreateEvent.java @@ -7,18 +7,14 @@ @RequiredArgsConstructor public class StatisticCreateEvent extends Event { - public static final HandlerList HANDLER_LIST = new HandlerList(); + // TODO 29.12.2024: recently removed DatabaseEntry object due to rework of database util might not work anymore (StatisticCreateEvent) - private final DatabaseEntry entry; + public static final HandlerList HANDLER_LIST = new HandlerList(); public static HandlerList getHandlerList() { return HANDLER_LIST; } - public void setStatistic(String key, double value) { - entry.changeValue(new Value(key, value)); - } - @Override public HandlerList getHandlers() { return HANDLER_LIST; From a2fcef7a79fd365539acd9eae8eb9b88ec17de3c Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Tue, 31 Dec 2024 09:05:47 +0100 Subject: [PATCH 03/14] rework database --- src/main/java/minevalley/core/api/Core.java | 7 + .../java/minevalley/core/api/CoreServer.java | 5 + .../core/api/database/ColumnType.java | 207 ++++++++++ .../core/api/database/StatementBuilder.java | 389 ++++++++++++++++++ 4 files changed, 608 insertions(+) create mode 100644 src/main/java/minevalley/core/api/database/ColumnType.java create mode 100644 src/main/java/minevalley/core/api/database/StatementBuilder.java diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java index 4b1e88df..941ec72f 100644 --- a/src/main/java/minevalley/core/api/Core.java +++ b/src/main/java/minevalley/core/api/Core.java @@ -4,6 +4,7 @@ import minevalley.core.api.armorstand.FakeArmorStand; import minevalley.core.api.corporations.Group; import minevalley.core.api.corporations.companies.*; +import minevalley.core.api.database.StatementBuilder; import minevalley.core.api.discord.EmbeddedMessage; import minevalley.core.api.discord.Webhook; import minevalley.core.api.economy.BankAccount; @@ -55,6 +56,7 @@ import org.bukkit.plugin.java.JavaPlugin; import org.bukkit.scheduler.BukkitTask; import org.bukkit.util.Vector; +import org.intellij.lang.annotations.Language; import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Contract; @@ -174,6 +176,11 @@ public static BukkitTask runAsyncTaskPeriodically(long delay, long period, @Nonn return server.runAsyncTaskPeriodically(delay, period, task); } + @Nonnull + public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql) { + return server.prepareSQL(sql); + } + /** * Registers an event listener. * diff --git a/src/main/java/minevalley/core/api/CoreServer.java b/src/main/java/minevalley/core/api/CoreServer.java index 94a8b2dc..51ce38e9 100644 --- a/src/main/java/minevalley/core/api/CoreServer.java +++ b/src/main/java/minevalley/core/api/CoreServer.java @@ -4,6 +4,7 @@ import minevalley.core.api.armorstand.FakeArmorStand; import minevalley.core.api.corporations.Group; import minevalley.core.api.corporations.companies.*; +import minevalley.core.api.database.StatementBuilder; import minevalley.core.api.discord.EmbeddedMessage; import minevalley.core.api.discord.Webhook; import minevalley.core.api.economy.BankAccount; @@ -51,6 +52,7 @@ import org.bukkit.plugin.java.JavaPlugin; import org.bukkit.scheduler.BukkitTask; import org.bukkit.util.Vector; +import org.intellij.lang.annotations.Language; import org.jetbrains.annotations.ApiStatus; import javax.annotation.Nonnegative; @@ -80,6 +82,9 @@ public interface CoreServer { @Nonnull BukkitTask runAsyncTaskPeriodically(long delay, long period, @Nonnull Runnable runnable) throws IllegalArgumentException; + @Nonnull + StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql); + void registerListener(@Nonnull Class cls, @Nonnull EventListener listener) throws IllegalArgumentException; void unregisterListener(@Nonnull Class cls, @Nonnull EventListener listener) throws IllegalArgumentException; diff --git a/src/main/java/minevalley/core/api/database/ColumnType.java b/src/main/java/minevalley/core/api/database/ColumnType.java new file mode 100644 index 00000000..5ec19c1f --- /dev/null +++ b/src/main/java/minevalley/core/api/database/ColumnType.java @@ -0,0 +1,207 @@ +package minevalley.core.api.database; + +import lombok.AccessLevel; +import lombok.Getter; +import lombok.RequiredArgsConstructor; + +@Getter +@RequiredArgsConstructor(access = AccessLevel.PRIVATE) +public enum ColumnType { + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code BIT}. + */ + BIT(-7), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code TINYINT}. + */ + TINYINT(-6), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code SMALLINT}. + */ + SMALLINT(5), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code INTEGER}. + */ + INTEGER(4), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code BIGINT}. + */ + BIGINT(-5), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code FLOAT}. + */ + FLOAT(6), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code REAL}. + */ + REAL(7), + + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code DOUBLE}. + */ + DOUBLE(8), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code NUMERIC}. + */ + NUMERIC(2), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code DECIMAL}. + */ + DECIMAL(3), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code CHAR}. + */ + CHAR(1), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code VARCHAR}. + */ + VARCHAR(12), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code LONGVARCHAR}. + */ + LONGVARCHAR(-1), + + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code DATE}. + */ + DATE(91), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code TIME}. + */ + TIME(92), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code TIMESTAMP}. + */ + TIMESTAMP(93), + + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code BINARY}. + */ + BINARY(-2), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code VARBINARY}. + */ + VARBINARY(-3), + + /** + *

The constant in the Java programming language, sometimes referred + * to as a type code, that identifies the generic SQL type + * {@code LONGVARBINARY}. + */ + LONGVARBINARY(-4), + + /** + *

The constant in the Java programming language + * that identifies the generic SQL value + * {@code NULL}. + */ + NULL(0), + + /** + * The constant in the Java programming language that indicates + * that the SQL type is database-specific and + * gets mapped to a Java object that can be accessed via + * the methods {@code getObject} and {@code setObject}. + */ + OTHER(1111), + + /** + * The constant in the Java programming language, sometimes referred to + * as a type code, that identifies the generic SQL type + * {@code DISTINCT}. + * + * @since 1.2 + */ + DISTINCT(2001), + + + /** + * The constant in the Java programming language, sometimes referred to + * as a type code, that identifies the generic SQL type {@code BOOLEAN}. + * + * @since 1.4 + */ + BOOLEAN(16), + + /** + * The constant in the Java programming language, sometimes referred to + * as a type code, that identifies the generic SQL type {@code REF CURSOR}. + * + * @since 1.8 + */ + REF_CURSOR(2012), + + /** + * The constant in the Java programming language, sometimes referred to + * as a type code, that identifies the generic SQL type + * {@code TIME WITH TIMEZONE}. + * + * @since 1.8 + */ + TIME_WITH_TIMEZONE(2013), + + /** + * The constant in the Java programming language, sometimes referred to + * as a type code, that identifies the generic SQL type + * {@code TIMESTAMP WITH TIMEZONE}. + * + * @since 1.8 + */ + TIMESTAMP_WITH_TIMEZONE(2014); + + private final int type; +} diff --git a/src/main/java/minevalley/core/api/database/StatementBuilder.java b/src/main/java/minevalley/core/api/database/StatementBuilder.java new file mode 100644 index 00000000..5de5b873 --- /dev/null +++ b/src/main/java/minevalley/core/api/database/StatementBuilder.java @@ -0,0 +1,389 @@ +package minevalley.core.api.database; + +import minevalley.core.api.Core; +import org.jetbrains.annotations.Contract; + +import javax.annotation.Nonnull; +import java.math.BigDecimal; +import java.sql.*; +import java.util.concurrent.CompletableFuture; + +/** + * This interface covers some but not nearly all features of the {@link PreparedStatement} interface as provided by the JDBC API. + * It's designed to provide some improvements such as an asynchronous execution and a builder pattern for setting parameters to reduce boilerplate code. + * Such as the {@link PreparedStatement} interface, the results of the query can be retrieved using the {@link ResultSet} interface. + *

You can call {@link StatementBuilder#executeUpdate()} or {@link StatementBuilder#executeQuery()} multiple times with or without changing parameters in between. + *

Use {@link StatementBuilder#unwrap()} to get the underlying {@link PreparedStatement} object if you need to use a method that is not covered by this interface. + *

The following code snippet demonstrates a possible way to use this interface: + * 

+ * {@code
+ * Core.prepareSQL("UPDATE team SET note = ? WHERE unique_id = ?")
+ * .setString(1, "Coolest boss ever")
+ * .setString(2, "e0ae458e-214c-409e-ad6d-4091a6719bb0")
+ * .executeUpdate();
+ * }
+ *
+ * + * @see Core#prepareSQL(String) + * @see PreparedStatement + * @see ResultSet + */ +@SuppressWarnings("unused") +public interface StatementBuilder extends AutoCloseable { + + /** + * Sets the parameter at the given index to SQL {@code NULL}. + *

+ * Note: Even though JDBC handles untyped {@code NULL} values pretty well, it is mandatory to provide the {@link ColumnType} of the parameter. + * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param type the {@link ColumnType} of the parameter + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setNull(int parameterIndex, @Nonnull ColumnType type) throws IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@code boolean} value. + *

Representation: {@code boolean} values are converted to SQL {@code BIT} values

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param bool the {@code boolean} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setBoolean(int parameterIndex, boolean bool) throws IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@code byte} value. + *

Representation: {@code byte} values are converted to SQL {@code TINYINT} values

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param b the {@code byte} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setByte(int parameterIndex, byte b) throws IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@code short} value. + *

Representation: {@code short} values are converted to SQL {@code SMALLINT} values

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param s the {@code short} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setShort(int parameterIndex, short s) throws IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@code int} value. + *

Representation: {@code int} values are converted to SQL {@code INTEGER} values

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param i the {@code int} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setInt(int parameterIndex, int i) throws IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@code long} value. + *

Representation: {@code long} values are converted to SQL {@code BIGINT} values

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param l the {@code long} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setLong(int parameterIndex, long l) throws IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@code float} value. + *

Representation: {@code float} values are converted to SQL {@code FLOAT} values

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param f the {@code float} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setFloat(int parameterIndex, float f) throws IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@code double} value. + *

Representation: {@code double} values are converted to SQL {@code DOUBLE} values

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param d the {@code double} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setDouble(int parameterIndex, double d) throws IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@link BigDecimal} value. + *

Representation: {@link BigDecimal} values are converted to SQL {@code DECIMAL} values

+ *

+ * Note: This method is not meant to handle {@code NULL} values. Use {@link StatementBuilder#setNull(int, ColumnType)} instead. + * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param bd the {@link BigDecimal} value to set. + * @return this {@link StatementBuilder} object + * @throws IllegalArgumentException if {@code bd} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setBigDecimal(int parameterIndex, @Nonnull BigDecimal bd) throws IllegalArgumentException, IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@link String} value. + *

Representation: {@link String} values are converted to SQL {@code VARCHAR} values

+ *

+ * Note: This method is not meant to handle {@code NULL} values. Use {@link StatementBuilder#setNull(int, ColumnType)} instead. + * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param s the {@link String} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalArgumentException if {@code s} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setString(int parameterIndex, @Nonnull String s) throws IllegalArgumentException, IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@code byte} array. + *

Representation: {@code byte} arrays are converted to SQL {@code VARBINARY} values

+ *

+ * Note: This method is not meant to handle {@code NULL} values. Use {@link StatementBuilder#setNull(int, ColumnType)} instead. + * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param bytes the {@code byte} array to set + * @return this {@link StatementBuilder} object + * @throws IllegalArgumentException if {@code bytes} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setBytes(int parameterIndex, @Nonnull byte[] bytes) throws IllegalArgumentException, IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@link Date} value. + *

Representation: {@link Date} values are converted to SQL {@code DATE} values

+ *

+ * Note: This method is not meant to handle {@code NULL} values. Use {@link StatementBuilder#setNull(int, ColumnType)} instead. + * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param date the {@link Date} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalArgumentException if {@code date} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setDate(int parameterIndex, @Nonnull Date date) throws IllegalArgumentException, IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@link Time} value. + *

Representation: {@link Time} values are converted to SQL {@code TIME} values

+ *

+ * Note: This method is not meant to handle {@code NULL} values. Use {@link StatementBuilder#setNull(int, ColumnType)} instead. + * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param time the {@link Time} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalArgumentException if {@code time} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setTime(int parameterIndex, @Nonnull Time time) throws IllegalArgumentException, IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@link Timestamp} value. + *

Representation: {@link Timestamp} values are converted to SQL {@code TIMESTAMP} values

+ *

+ * Note: This method is not meant to handle {@code NULL} values. Use {@link StatementBuilder#setNull(int, ColumnType)} instead. + * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param timestamp the {@link Timestamp} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalArgumentException if {@code timestamp} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setTimestamp(int parameterIndex, @Nonnull Timestamp timestamp) throws IllegalArgumentException, IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@link Object} value. + *

+ * Note: + *

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param obj the {@link Object} value to set + * @return this {@link StatementBuilder} object + * @throws IllegalArgumentException if {@code obj} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _ -> this") + StatementBuilder setObject(int parameterIndex, @Nonnull Object obj) throws IllegalArgumentException, IllegalStateException, SQLException; + + /** + * Sets the parameter at the given index to the given {@link Object} value. + *

+ * Note: + *

+ * + * @param parameterIndex the index of the parameter to set, beginning with 1 + * @param obj the {@link Object} value to set + * @param type the {@link ColumnType} of the parameter + * @return this {@link StatementBuilder} object + * @throws IllegalArgumentException if {@code obj} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("_, _, _ -> this") + StatementBuilder setObject(int parameterIndex, @Nonnull Object obj, @Nonnull ColumnType type) throws IllegalArgumentException, IllegalStateException, SQLException; + + /** + * Clears all parameters that have been set so far. + * + * @return this {@link StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Nonnull + @Contract("-> this") + StatementBuilder clearParameters() throws IllegalStateException, SQLException; + + /** + * Executes the SQL query that has been built so far. + *

+ * Note: This method should be used for queries that do not return a result set. + * + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Contract(pure = true) + void executeUpdate() throws IllegalStateException, SQLException; + + /** + * Executes the SQL query that has been built so far asynchronously. + *

+ * Note: This method should be used for queries that do not return a result set. + * + * @return a {@link CompletableFuture} that will be completed once the query has been executed + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + */ + @Nonnull + @Contract(pure = true) + CompletableFuture executeUpdateAsync() throws IllegalStateException; + + /** + * Executes the SQL query that has been built so far and retrieves the generated key. + *

+ * Note: This method should be used for queries that do not return a result set. + * + * @return the generated key + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs + */ + @Contract(pure = true) + int executeUpdateAndRetrieveKey() throws IllegalStateException, SQLException; + + /** + * Executes the SQL query that has been built so far and retrieves the generated key asynchronously. + *

+ * Note: This method should be used for queries that do not return a result set. + * + * @return a {@link CompletableFuture} that will be completed once the query has been executed and the key has been retrieved + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + */ + @Nonnull + @Contract(pure = true) + CompletableFuture executeUpdateAndRetrieveKeyAsync() throws IllegalStateException; + + /** + * Executes the SQL query that has been built so far and returns the result set. + *

+ * Note: This method should be used for queries that return a result set. + * + * @return the result set + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws SQLException if a database access error occurs or the query does not return a result set + */ + @Nonnull + @Contract(pure = true) + ResultSet executeQuery() throws IllegalStateException, SQLException; + + /** + * Executes the SQL query that has been built so far and returns the result set asynchronously. + *

+ * Note: This method should be used for queries that return a result set. + * + * @return a {@link CompletableFuture} that will be completed once the query has been executed and the result set has been retrieved + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + */ + @Nonnull + @Contract(pure = true) + CompletableFuture executeQueryAsync() throws IllegalStateException; + + /** + * Returns a copy of the underlying {@link PreparedStatement} object. + *

+ * Note: + *

+ * + * @return a copy of the underlying {@link PreparedStatement} object + * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + */ + @Nonnull + @Contract(pure = true) + PreparedStatement unwrap() throws IllegalStateException; +} \ No newline at end of file From 51ef5d4ac8f49da771e971e3a39aee7b8f407bcc Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Tue, 31 Dec 2024 17:37:35 +0100 Subject: [PATCH 04/14] replace link to own class to simple code object --- .../core/api/database/StatementBuilder.java | 84 +++++++++---------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/src/main/java/minevalley/core/api/database/StatementBuilder.java b/src/main/java/minevalley/core/api/database/StatementBuilder.java index 5de5b873..6eaac5fd 100644 --- a/src/main/java/minevalley/core/api/database/StatementBuilder.java +++ b/src/main/java/minevalley/core/api/database/StatementBuilder.java @@ -38,8 +38,8 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param type the {@link ColumnType} of the parameter - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -52,8 +52,8 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param bool the {@code boolean} value to set - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -66,8 +66,8 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param b the {@code byte} value to set - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -80,8 +80,8 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param s the {@code short} value to set - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -94,8 +94,8 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param i the {@code int} value to set - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -108,8 +108,8 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param l the {@code long} value to set - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -122,8 +122,8 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param f the {@code float} value to set - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -136,8 +136,8 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param d the {@code double} value to set - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -152,9 +152,9 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param bd the {@link BigDecimal} value to set. - * @return this {@link StatementBuilder} object + * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code bd} is {@code null} - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -169,9 +169,9 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param s the {@link String} value to set - * @return this {@link StatementBuilder} object + * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code s} is {@code null} - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -186,9 +186,9 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param bytes the {@code byte} array to set - * @return this {@link StatementBuilder} object + * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code bytes} is {@code null} - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -203,9 +203,9 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param date the {@link Date} value to set - * @return this {@link StatementBuilder} object + * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code date} is {@code null} - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -220,9 +220,9 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param time the {@link Time} value to set - * @return this {@link StatementBuilder} object + * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code time} is {@code null} - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -237,9 +237,9 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param timestamp the {@link Timestamp} value to set - * @return this {@link StatementBuilder} object + * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code timestamp} is {@code null} - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -258,9 +258,9 @@ public interface StatementBuilder extends AutoCloseable { * * @param parameterIndex the index of the parameter to set, beginning with 1 * @param obj the {@link Object} value to set - * @return this {@link StatementBuilder} object + * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code obj} is {@code null} - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -279,9 +279,9 @@ public interface StatementBuilder extends AutoCloseable { * @param parameterIndex the index of the parameter to set, beginning with 1 * @param obj the {@link Object} value to set * @param type the {@link ColumnType} of the parameter - * @return this {@link StatementBuilder} object + * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code obj} is {@code null} - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -291,8 +291,8 @@ public interface StatementBuilder extends AutoCloseable { /** * Clears all parameters that have been set so far. * - * @return this {@link StatementBuilder} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @return this {@code StatementBuilder} object + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Nonnull @@ -304,7 +304,7 @@ public interface StatementBuilder extends AutoCloseable { *

* Note: This method should be used for queries that do not return a result set. * - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Contract(pure = true) @@ -316,7 +316,7 @@ public interface StatementBuilder extends AutoCloseable { * Note: This method should be used for queries that do not return a result set. * * @return a {@link CompletableFuture} that will be completed once the query has been executed - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} */ @Nonnull @Contract(pure = true) @@ -328,7 +328,7 @@ public interface StatementBuilder extends AutoCloseable { * Note: This method should be used for queries that do not return a result set. * * @return the generated key - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs */ @Contract(pure = true) @@ -340,7 +340,7 @@ public interface StatementBuilder extends AutoCloseable { * Note: This method should be used for queries that do not return a result set. * * @return a {@link CompletableFuture} that will be completed once the query has been executed and the key has been retrieved - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} */ @Nonnull @Contract(pure = true) @@ -352,7 +352,7 @@ public interface StatementBuilder extends AutoCloseable { * Note: This method should be used for queries that return a result set. * * @return the result set - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} * @throws SQLException if a database access error occurs or the query does not return a result set */ @Nonnull @@ -365,7 +365,7 @@ public interface StatementBuilder extends AutoCloseable { * Note: This method should be used for queries that return a result set. * * @return a {@link CompletableFuture} that will be completed once the query has been executed and the result set has been retrieved - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} */ @Nonnull @Contract(pure = true) @@ -377,11 +377,11 @@ public interface StatementBuilder extends AutoCloseable { * Note: *

* * @return a copy of the underlying {@link PreparedStatement} object - * @throws IllegalStateException if this method is called on a closed {@link StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} */ @Nonnull @Contract(pure = true) From cd7a4d17d5e732e96de8682ef040fdd05cdb979a Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Thu, 2 Jan 2025 02:26:46 +0100 Subject: [PATCH 05/14] add retrieveGeneratedKeys option --- src/main/java/minevalley/core/api/Core.java | 7 ++++++- src/main/java/minevalley/core/api/CoreServer.java | 2 +- .../minevalley/core/api/database/StatementBuilder.java | 2 +- 3 files changed, 8 insertions(+), 3 deletions(-) diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java index 941ec72f..a1fe29da 100644 --- a/src/main/java/minevalley/core/api/Core.java +++ b/src/main/java/minevalley/core/api/Core.java @@ -178,7 +178,12 @@ public static BukkitTask runAsyncTaskPeriodically(long delay, long period, @Nonn @Nonnull public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql) { - return server.prepareSQL(sql); + return server.prepareSQL(sql, false); + } + + @Nonnull + public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) { + return server.prepareSQL(sql, retrieveGeneratedKeys); } /** diff --git a/src/main/java/minevalley/core/api/CoreServer.java b/src/main/java/minevalley/core/api/CoreServer.java index 51ce38e9..96468f78 100644 --- a/src/main/java/minevalley/core/api/CoreServer.java +++ b/src/main/java/minevalley/core/api/CoreServer.java @@ -83,7 +83,7 @@ public interface CoreServer { BukkitTask runAsyncTaskPeriodically(long delay, long period, @Nonnull Runnable runnable) throws IllegalArgumentException; @Nonnull - StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql); + StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys); void registerListener(@Nonnull Class cls, @Nonnull EventListener listener) throws IllegalArgumentException; diff --git a/src/main/java/minevalley/core/api/database/StatementBuilder.java b/src/main/java/minevalley/core/api/database/StatementBuilder.java index 6eaac5fd..01fbffa5 100644 --- a/src/main/java/minevalley/core/api/database/StatementBuilder.java +++ b/src/main/java/minevalley/core/api/database/StatementBuilder.java @@ -8,7 +8,7 @@ import java.sql.*; import java.util.concurrent.CompletableFuture; -/** + /** * This interface covers some but not nearly all features of the {@link PreparedStatement} interface as provided by the JDBC API. * It's designed to provide some improvements such as an asynchronous execution and a builder pattern for setting parameters to reduce boilerplate code. * Such as the {@link PreparedStatement} interface, the results of the query can be retrieved using the {@link ResultSet} interface. From b331ce12068d9b0c45021c1d941d9fc88154b8ec Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Thu, 2 Jan 2025 06:40:27 +0100 Subject: [PATCH 06/14] add setSQL and getSQL --- .../core/api/database/StatementBuilder.java | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/src/main/java/minevalley/core/api/database/StatementBuilder.java b/src/main/java/minevalley/core/api/database/StatementBuilder.java index 01fbffa5..7fc84675 100644 --- a/src/main/java/minevalley/core/api/database/StatementBuilder.java +++ b/src/main/java/minevalley/core/api/database/StatementBuilder.java @@ -8,7 +8,7 @@ import java.sql.*; import java.util.concurrent.CompletableFuture; - /** +/** * This interface covers some but not nearly all features of the {@link PreparedStatement} interface as provided by the JDBC API. * It's designed to provide some improvements such as an asynchronous execution and a builder pattern for setting parameters to reduce boilerplate code. * Such as the {@link PreparedStatement} interface, the results of the query can be retrieved using the {@link ResultSet} interface. @@ -31,6 +31,27 @@ @SuppressWarnings("unused") public interface StatementBuilder extends AutoCloseable { + /** + * Gets the SQL code that will be executed when calling one of the {@code execute} methods. + * + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} + */ + @Nonnull + @Contract(pure = true) + String getSQL() throws IllegalStateException; + + /** + * Sets the SQL code that will be executed when calling one of the {@code execute} methods. + * + * @param sql the SQL code to set + * @return this {@code StatementBuilder} object + * @throws IllegalArgumentException if {@code sql} is {@code null} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} + */ + @Nonnull + @Contract("_ -> this") + StatementBuilder setSQL(@Nonnull String sql) throws IllegalArgumentException, IllegalStateException; + /** * Sets the parameter at the given index to SQL {@code NULL}. *

From f7520c43362e5773a7c38ca4d2facf1d099c330d Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Thu, 2 Jan 2025 06:41:26 +0100 Subject: [PATCH 07/14] switch and add some annotations --- .../java/minevalley/core/api/database/StatementBuilder.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/main/java/minevalley/core/api/database/StatementBuilder.java b/src/main/java/minevalley/core/api/database/StatementBuilder.java index 7fc84675..02ea1c49 100644 --- a/src/main/java/minevalley/core/api/database/StatementBuilder.java +++ b/src/main/java/minevalley/core/api/database/StatementBuilder.java @@ -1,6 +1,7 @@ package minevalley.core.api.database; import minevalley.core.api.Core; +import org.intellij.lang.annotations.Language; import org.jetbrains.annotations.Contract; import javax.annotation.Nonnull; @@ -50,7 +51,7 @@ public interface StatementBuilder extends AutoCloseable { */ @Nonnull @Contract("_ -> this") - StatementBuilder setSQL(@Nonnull String sql) throws IllegalArgumentException, IllegalStateException; + StatementBuilder setSQL(@Nonnull @Language("SQL") String sql) throws IllegalArgumentException, IllegalStateException; /** * Sets the parameter at the given index to SQL {@code NULL}. From cdec3f2f91e0524d5bd21fd0c389e5301cc1fe8f Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Thu, 2 Jan 2025 06:54:43 +0100 Subject: [PATCH 08/14] add some information about throws exeptions when asking for generated keys where no were supposed to be returned --- .../java/minevalley/core/api/database/StatementBuilder.java | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/java/minevalley/core/api/database/StatementBuilder.java b/src/main/java/minevalley/core/api/database/StatementBuilder.java index 02ea1c49..5518ee11 100644 --- a/src/main/java/minevalley/core/api/database/StatementBuilder.java +++ b/src/main/java/minevalley/core/api/database/StatementBuilder.java @@ -350,7 +350,7 @@ public interface StatementBuilder extends AutoCloseable { * Note: This method should be used for queries that do not return a result set. * * @return the generated key - * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} or this statement builder is not supposed to retrieve generated keys * @throws SQLException if a database access error occurs */ @Contract(pure = true) @@ -362,7 +362,7 @@ public interface StatementBuilder extends AutoCloseable { * Note: This method should be used for queries that do not return a result set. * * @return a {@link CompletableFuture} that will be completed once the query has been executed and the key has been retrieved - * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} + * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} or this statement builder is not supposed to retrieve generated keys */ @Nonnull @Contract(pure = true) From 3cb2b5fc73be055d2a8e339a039b2563682c2be3 Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Thu, 2 Jan 2025 07:01:18 +0100 Subject: [PATCH 09/14] added more precise java doc --- .../core/api/database/StatementBuilder.java | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/main/java/minevalley/core/api/database/StatementBuilder.java b/src/main/java/minevalley/core/api/database/StatementBuilder.java index 5518ee11..1fff6f4f 100644 --- a/src/main/java/minevalley/core/api/database/StatementBuilder.java +++ b/src/main/java/minevalley/core/api/database/StatementBuilder.java @@ -62,7 +62,7 @@ public interface StatementBuilder extends AutoCloseable { * @param type the {@link ColumnType} of the parameter * @return this {@code StatementBuilder} object * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -76,7 +76,7 @@ public interface StatementBuilder extends AutoCloseable { * @param bool the {@code boolean} value to set * @return this {@code StatementBuilder} object * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -90,7 +90,7 @@ public interface StatementBuilder extends AutoCloseable { * @param b the {@code byte} value to set * @return this {@code StatementBuilder} object * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -104,7 +104,7 @@ public interface StatementBuilder extends AutoCloseable { * @param s the {@code short} value to set * @return this {@code StatementBuilder} object * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -118,7 +118,7 @@ public interface StatementBuilder extends AutoCloseable { * @param i the {@code int} value to set * @return this {@code StatementBuilder} object * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -132,7 +132,7 @@ public interface StatementBuilder extends AutoCloseable { * @param l the {@code long} value to set * @return this {@code StatementBuilder} object * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -146,7 +146,7 @@ public interface StatementBuilder extends AutoCloseable { * @param f the {@code float} value to set * @return this {@code StatementBuilder} object * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -160,7 +160,7 @@ public interface StatementBuilder extends AutoCloseable { * @param d the {@code double} value to set * @return this {@code StatementBuilder} object * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -177,7 +177,7 @@ public interface StatementBuilder extends AutoCloseable { * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code bd} is {@code null} * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -194,7 +194,7 @@ public interface StatementBuilder extends AutoCloseable { * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code s} is {@code null} * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -211,7 +211,7 @@ public interface StatementBuilder extends AutoCloseable { * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code bytes} is {@code null} * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -228,7 +228,7 @@ public interface StatementBuilder extends AutoCloseable { * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code date} is {@code null} * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -245,7 +245,7 @@ public interface StatementBuilder extends AutoCloseable { * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code time} is {@code null} * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -262,7 +262,7 @@ public interface StatementBuilder extends AutoCloseable { * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code timestamp} is {@code null} * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -283,7 +283,7 @@ public interface StatementBuilder extends AutoCloseable { * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code obj} is {@code null} * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _ -> this") @@ -304,7 +304,7 @@ public interface StatementBuilder extends AutoCloseable { * @return this {@code StatementBuilder} object * @throws IllegalArgumentException if {@code obj} is {@code null} * @throws IllegalStateException if this method is called on a closed {@code StatementBuilder} - * @throws SQLException if a database access error occurs + * @throws SQLException if a database access error occurs or if {@code parameterIndex} does not correspond to a parameter marker in the SQL statement */ @Nonnull @Contract("_, _, _ -> this") From 7e0142665606b806f945f2383da3a841a3a4bf29 Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Thu, 2 Jan 2025 07:50:07 +0100 Subject: [PATCH 10/14] add exception throw to method signature --- src/main/java/minevalley/core/api/Core.java | 5 +++-- src/main/java/minevalley/core/api/CoreServer.java | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java index a1fe29da..28c9e334 100644 --- a/src/main/java/minevalley/core/api/Core.java +++ b/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.sql.SQLException; import java.text.SimpleDateFormat; import java.time.DayOfWeek; import java.util.*; @@ -177,12 +178,12 @@ public static BukkitTask runAsyncTaskPeriodically(long delay, long period, @Nonn } @Nonnull - public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql) { + public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql) throws SQLException { return server.prepareSQL(sql, false); } @Nonnull - public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) { + public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) throws SQLException { return server.prepareSQL(sql, retrieveGeneratedKeys); } diff --git a/src/main/java/minevalley/core/api/CoreServer.java b/src/main/java/minevalley/core/api/CoreServer.java index 96468f78..6cf1966a 100644 --- a/src/main/java/minevalley/core/api/CoreServer.java +++ b/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.sql.SQLException; import java.time.DayOfWeek; import java.util.List; import java.util.UUID; @@ -83,7 +84,7 @@ public interface CoreServer { BukkitTask runAsyncTaskPeriodically(long delay, long period, @Nonnull Runnable runnable) throws IllegalArgumentException; @Nonnull - StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys); + StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) throws SQLException; void registerListener(@Nonnull Class cls, @Nonnull EventListener listener) throws IllegalArgumentException; From 8d92d2d576be5b17336450351232f8e3cc2abe70 Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Sat, 4 Jan 2025 03:32:20 +0100 Subject: [PATCH 11/14] add close() method to specify exception --- .../minevalley/core/api/database/StatementBuilder.java | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/main/java/minevalley/core/api/database/StatementBuilder.java b/src/main/java/minevalley/core/api/database/StatementBuilder.java index 1fff6f4f..cd455401 100644 --- a/src/main/java/minevalley/core/api/database/StatementBuilder.java +++ b/src/main/java/minevalley/core/api/database/StatementBuilder.java @@ -408,4 +408,12 @@ public interface StatementBuilder extends AutoCloseable { @Nonnull @Contract(pure = true) PreparedStatement unwrap() throws IllegalStateException; + + /** + * Closes the {@code StatementBuilder} and releases any resources it holds. + * + * @throws SQLException if a database access error occurs + */ + @Override + void close() throws SQLException; } \ No newline at end of file From f815f06e852fc3fc055e3149b986a5ef9623db39 Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Sun, 5 Jan 2025 01:06:18 +0100 Subject: [PATCH 12/14] add generateUniqueId() --- src/main/java/minevalley/core/api/Core.java | 4 ++++ src/main/java/minevalley/core/api/CoreServer.java | 2 ++ 2 files changed, 6 insertions(+) diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java index 28c9e334..2f39ba89 100644 --- a/src/main/java/minevalley/core/api/Core.java +++ b/src/main/java/minevalley/core/api/Core.java @@ -187,6 +187,10 @@ public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, return server.prepareSQL(sql, retrieveGeneratedKeys); } + public static int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException { + return server.generateUniqueId(table, column, amountOfChars); + } + /** * Registers an event listener. * diff --git a/src/main/java/minevalley/core/api/CoreServer.java b/src/main/java/minevalley/core/api/CoreServer.java index 6cf1966a..9627d64f 100644 --- a/src/main/java/minevalley/core/api/CoreServer.java +++ b/src/main/java/minevalley/core/api/CoreServer.java @@ -86,6 +86,8 @@ public interface CoreServer { @Nonnull StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) throws SQLException; + int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException; + void registerListener(@Nonnull Class cls, @Nonnull EventListener listener) throws IllegalArgumentException; void unregisterListener(@Nonnull Class cls, @Nonnull EventListener listener) throws IllegalArgumentException; From 4424e6ce8f9a184203f1f9ad03ea5bc42217a22d Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Sun, 5 Jan 2025 01:16:42 +0100 Subject: [PATCH 13/14] add some documentation --- src/main/java/minevalley/core/api/Core.java | 30 ++++++++++++++++++- .../java/minevalley/core/api/CoreServer.java | 2 +- 2 files changed, 30 insertions(+), 2 deletions(-) diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java index 2f39ba89..2b8d7526 100644 --- a/src/main/java/minevalley/core/api/Core.java +++ b/src/main/java/minevalley/core/api/Core.java @@ -177,17 +177,45 @@ public static BukkitTask runAsyncTaskPeriodically(long delay, long period, @Nonn return server.runAsyncTaskPeriodically(delay, period, task); } + /** + * Create a {@link StatementBuilder} based on the given SQL code. + * + * @param sql SQL code to prepare + * @return a new {@link StatementBuilder} instance + * @throws SQLException if a database access error occurs + */ @Nonnull + @Contract("_ -> new") public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql) throws SQLException { return server.prepareSQL(sql, false); } + /** + * Create a {@link StatementBuilder} based on the given SQL code. + * + * @param sql SQL code to prepare + * @param retrieveGeneratedKeys whether to retrieve generated keys + * @return a new {@link StatementBuilder} instance + * @throws SQLException if a database access error occurs + */ @Nonnull + @Contract("_, _ -> new") public static StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) throws SQLException { return server.prepareSQL(sql, retrieveGeneratedKeys); } - public static int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException { + /** + * Generate a random id based on the given length that was not used in the given column and table. + * + * @param table table to check + * @param column column to check + * @param amountOfChars amount of chars the id should have + * @return a unique id + * @throws IllegalArgumentException if the table is null, column is null or the amount of chars is less than 1 + * @throws SQLException if a database access error occurs + */ + @Contract("_, _, _ -> _") + public static int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException, SQLException { return server.generateUniqueId(table, column, amountOfChars); } diff --git a/src/main/java/minevalley/core/api/CoreServer.java b/src/main/java/minevalley/core/api/CoreServer.java index 9627d64f..4b6eb23a 100644 --- a/src/main/java/minevalley/core/api/CoreServer.java +++ b/src/main/java/minevalley/core/api/CoreServer.java @@ -86,7 +86,7 @@ public interface CoreServer { @Nonnull StatementBuilder prepareSQL(@Nonnull @Language("SQL") String sql, boolean retrieveGeneratedKeys) throws SQLException; - int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException; + int generateUniqueId(@Nonnull String table, @Nonnull String column, int amountOfChars) throws IllegalArgumentException, SQLException; void registerListener(@Nonnull Class cls, @Nonnull EventListener listener) throws IllegalArgumentException; From c9dbe53f0a70dd69d52affd39ed9c97fbfb296c2 Mon Sep 17 00:00:00 2001 From: Snabeldier <79211348+Snabeldier@users.noreply.github.com> Date: Sun, 5 Jan 2025 01:54:05 +0100 Subject: [PATCH 14/14] change version --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 164ca433..c4c1823f 100644 --- a/pom.xml +++ b/pom.xml @@ -7,7 +7,7 @@ CoreAPI - 1.287.2 + 1.288.0 1.61.2