Implement punishment logs for Velocity also visually

gradle/libs.versions.toml

@@ -1,7 +1,7 @@
 # Generate from settings.gradle.kts
 
 [versions]
-velocity-api = "3.3.0-SNAPSHOT"
+velocity-api = "3.4.0-SNAPSHOT"
 luckperms-api = "5.4"
 jackson-databind = "2.18.0"
 jackson-datatype-jsr310 = "2.18.0"
@@ -48,6 +48,7 @@ slf4j-api = { group = "org.slf4j", name = "slf4j-api", version.ref = "slf4j" }
 adventure-api = { group = "net.kyori", name = "adventure-api", version.ref = "adventure" }
 adventure-text-minimessage = { group = "net.kyori", name = "adventure-text-minimessage", version.ref = "adventure" }
 adventure-text-serializer-plain = { group = "net.kyori", name = "adventure-text-serializer-plain", version.ref = "adventure" }
+adventure-text-feature-pagination = { group = "net.kyori", name = "adventure-text-feature-pagination", version = "4.0.0-SNAPSHOT" }
 
 # Cloud
 cloud-core = { group = "org.incendo", name = "cloud-core", version.ref = "cloud" }

necrify-api/src/main/java/de/jvstvshd/necrify/api/Necrify.java

@@ -54,6 +54,7 @@
  *
  *
  * }</pre>
+ *
  * @author JvstvsHD
  * @version 1.0.0
  */
@@ -110,6 +111,7 @@ public interface Necrify {
     /**
      * Returns the message provider used by this system. A message provider provides localized messages for users based
      * on a key and optional arguments.
+     *
      * @return the message provider.
      */
     @NotNull
@@ -120,13 +122,15 @@ public interface Necrify {
      * on a key and optional arguments.
      * <p>
      * This may does not affect anything after the system has been initialized fully.
+     *
      * @param messageProvider the message provider to set.
      */
     void setMessageProvider(@NotNull MessageProvider messageProvider);
 
     /**
      * Returns the user manager used by this system. The user manager is responsible for loading and saving users and
      * keeping their data accurate and up-to-date.
+     *
      * @return the user manager.
      */
     @NotNull
@@ -137,16 +141,25 @@ public interface Necrify {
      * keeping their data accurate and up-to-date.
      * <p>
      * This may does not affect anything after the system has been initialized fully.
+     *
      * @param userManager the user manager to set.
      */
     void setUserManager(@NotNull UserManager userManager);
 
     /**
      * Retrieves a punishment by its id. This will also completely load the user this punishment is affecting.
+     * <p>
+     * As of <b>1.2.2</b>, this method may return a punishment object that only contains historical data about it. Thus, this
+     * punishment cannot be manipulated any further. To check whether the punishment is historical, you may use
+     * {@link Punishment#isOngoing()}. If it returns true, the punishment is still active and can be manipulated in any
+     * way. If it returns false, the punishment probably is historical and cannot be manipulated. You can still retrieve
+     * log entries of historical punishments. Historical punishments are not added to the user's list of active punishments.
+     * </p>
      *
      * @param punishmentId the id of the punishment.
      * @param <T>          the type of the punishment.
      * @return a future containing the punishment or {@link Optional#empty()} if not found.
+     * @throws IllegalArgumentException if the punishment id is null
      * @since 1.2.0
      */
     <T extends Punishment> CompletableFuture<Optional<T>> getPunishment(@NotNull UUID punishmentId);
@@ -168,4 +181,4 @@ public interface Necrify {
      * @param eventDispatcher the event dispatcher to set.
      */
     void setEventDispatcher(@NotNull EventDispatcher eventDispatcher);
-}
+}

necrify-api/src/main/java/de/jvstvshd/necrify/api/message/MessageProvider.java

@@ -98,19 +98,15 @@ default String provideString(@NotNull String key, @Nullable Locale locale, Compo
     }
 
     /**
-     * Prefixes the provided components into one component.
+     * Prefixes the provided components with this system's prefix into one component containing firstly the prefix and then
+     * all provided components in order of the array.
      *
      * @param args the components to prefix.
      * @return one prefixed component.
      */
     @NotNull
     default Component prefixed(Component... args) {
-        Component comp;
-        if (autoPrefixed()) {
-            comp = prefix();
-        } else {
-            comp = Component.empty();
-        }
+        Component comp = prefix();
         for (Component arg : args) {
             comp = comp.append(arg);
         }

necrify-api/src/main/java/de/jvstvshd/necrify/api/punishment/log/PunishmentLog.java

@@ -33,7 +33,10 @@
 public interface PunishmentLog {
 
     /**
-     * Returns the punishment this log belongs to.
+     * Returns the punishment this log belongs to or even if the punishment this log refers to does no longer exist.
+     * If the punishment no longer exists, this method returns a {@link Punishment} instance with the UUID of the punishment
+     * but no other information. If the user this punishment belongs to does not exist anymore, this method's return value
+     * will contain no target user.
      *
      * @return the punishment this log belongs to.
      */
@@ -94,6 +97,9 @@ default PunishmentLogEntry getLatestEntry() {
      * @param message the message to log
      * @param actor   the actor that performed the action
      * @throws IllegalArgumentException if the action can only be logged once and has already been logged
+     * @apiNote Standard actions (all of the action types in {@link PunishmentLogAction}) are directly logged through
+     * means like SQL triggers so that this method does not have to be called explicitly. This method is only meant to
+     * be used for custom actions.
      */
     void log(@NotNull PunishmentLogAction action, @NotNull String message, @NotNull NecrifyUser actor);
 }

necrify-api/src/main/java/de/jvstvshd/necrify/api/punishment/log/PunishmentLogAction.java

@@ -45,7 +45,8 @@ public interface PunishmentLogAction {
     boolean onlyOnce();
 
     /**
-     * A punishment was created (it was created on the storage and enforced - no instantiation). This action can only be logged once.
+     * A punishment was created (it was created on the storage and enforced - no instantiation). This action can only be logged once
+     * but is guaranteed to be logged for each punishment.
      */
     PunishmentLogAction CREATED = new SimplePunishmentLogAction("created", true);
 
@@ -61,6 +62,13 @@ public interface PunishmentLogAction {
      */
     PunishmentLogAction CHANGE_DURATION = new SimplePunishmentLogAction("change_duration", false);
 
+    /**
+     * Indicates that the temporal fix points of a punishment were changed, such as delay by x to allow another punishment
+     * to fully pass before. This usually happens around the same time as a change in succession.
+     * This action can be logged multiple times. The time stored in the associated
+     */
+    PunishmentLogAction CHANGE_TIME = new SimplePunishmentLogAction("change_time", false);
+
     /**
      * The predecessor of a punishment was changed. This action can be logged multiple times. The predecessor stored in the associated
      * {@link PunishmentLogEntry} is the new predecessor. The old predecessor can be retrieved from the previous entry.
@@ -78,6 +86,12 @@ public interface PunishmentLogAction {
      */
     PunishmentLogAction REMOVED = new SimplePunishmentLogAction("removed", true);
 
+    /**
+     * This action indicates that information about a punishment was logged. This action can be logged multiple times but
+     * is guaranteed to be logged at least once for each punishment.
+     */
+    PunishmentLogAction INFORMATION = new SimplePunishmentLogAction("information", false);
+
     /**
      * An unknown action was performed. This action is returned as default if the stored action type cannot be resolved to
      * a proper type. This action can be logged multiple times.
@@ -86,11 +100,20 @@ public interface PunishmentLogAction {
 
     /**
      * A simple implementation of {@link PunishmentLogAction}. This class only contains the name and whether the action can only be logged once or more.
-     * @param name the name of the action
+     *
+     * @param name     the name of the action
      * @param onlyOnce whether the action can only be logged once
      */
     record SimplePunishmentLogAction(String name, boolean onlyOnce) implements PunishmentLogAction {
 
+        @Override
+        public boolean equals(Object obj) {
+            if (this == obj) return true;
+            if (obj == null || getClass() != obj.getClass()) return false;
+            SimplePunishmentLogAction that = (SimplePunishmentLogAction) obj;
+            return name.equals(that.name);
+        }
+
         @Override
         public @NotNull String name() {
             return name;

necrify-api/src/main/java/de/jvstvshd/necrify/api/punishment/log/PunishmentLogActionRegistry.java

@@ -27,23 +27,28 @@
 
 /**
  * A central registry for {@link PunishmentLogAction}s. This class is used to register and retrieve punishment log actions by their names.
+ *
  * @since 1.2.2
  */
 public class PunishmentLogActionRegistry {
 
     static {
+        actions = new HashMap<>();
         registerAction(PunishmentLogAction.CREATED);
         registerAction(PunishmentLogAction.CHANGE_REASON);
         registerAction(PunishmentLogAction.CHANGE_DURATION);
         registerAction(PunishmentLogAction.CHANGE_PREDECESSOR);
         registerAction(PunishmentLogAction.CHANGE_SUCCESSOR);
         registerAction(PunishmentLogAction.REMOVED);
+        registerAction(PunishmentLogAction.INFORMATION);
+        registerAction(PunishmentLogAction.CHANGE_TIME);
     }
 
-    private final static Map<String, PunishmentLogAction> actions = new HashMap<>();
+    private final static Map<String, PunishmentLogAction> actions;
 
     /**
      * Registers a new {@link PunishmentLogAction}. If an action with the same name is already registered, it will be replaced.
+     *
      * @param action the action to register
      */
     public static void registerAction(@NotNull PunishmentLogAction action) {
@@ -52,6 +57,7 @@ public static void registerAction(@NotNull PunishmentLogAction action) {
 
     /**
      * Retrieves a {@link PunishmentLogAction} by its name. If no action with the given name is registered, an empty optional is returned.
+     *
      * @param name the name of the action
      * @return the action or an empty optional if not found
      */
@@ -61,6 +67,7 @@ public static Optional<PunishmentLogAction> getAction(@NotNull String name) {
 
     /**
      * Unregisters a {@link PunishmentLogAction} by its name. If no action with the given name is registered, null is returned.
+     *
      * @param name the name of the action
      * @return the unregistered action or null if not found
      */
@@ -71,6 +78,7 @@ public static PunishmentLogAction unregisterAction(String name) {
 
     /**
      * Returns a copy of all registered {@link PunishmentLogAction}s.
+     *
      * @return a copy of all registered actions
      */
     public static Map<String, PunishmentLogAction> getActions() {

necrify-api/src/main/java/de/jvstvshd/necrify/api/user/CommandSender.java

@@ -19,6 +19,7 @@
 package de.jvstvshd.necrify.api.user;
 
 import de.jvstvshd.necrify.api.message.MessageProvider;
+import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.format.NamedTextColor;
 import net.kyori.adventure.text.format.TextColor;
@@ -30,14 +31,7 @@
  * Represents an entity that is able to interact with the server via messages and may send commands to it. It is also
  * able to hold permissions.
  */
-public interface CommandSender {
-
-    /**
-     * Sends a message to the command sender. The message may be given in form of a {@link net.kyori.adventure.text.TranslatableComponent},
-     * which will be translated to the correct language when being displayed.
-     * @param message a non-null component that represents the message to be sent.
-     */
-    void sendMessage(@NotNull Component message);
+public interface CommandSender extends Audience {
 
     /**
      * Sends a message to the command sender. The message must contain a valid translation key that is present in the

necrify-api/src/main/java/de/jvstvshd/necrify/api/user/NecrifyUser.java

@@ -42,7 +42,6 @@
  *
  * @since 1.2.0
  */
-@ApiStatus.Experimental
 public interface NecrifyUser extends CommandSender {
 
     /**

necrify-api/src/main/java/de/jvstvshd/necrify/api/user/UserManager.java

@@ -20,6 +20,7 @@
 
 import org.jetbrains.annotations.NotNull;
 
+import java.util.Collection;
 import java.util.Optional;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
@@ -94,6 +95,7 @@ public interface UserManager {
     /**
      * Loads the user with the given uuid or creates a new user if not found. At first, the cache is checked for the user.
      * If there is no result, the user is loaded from the underlying storage. If the user is not found, a new user is created.
+     *
      * @param uuid the uuid of the user
      * @return a future containing the user or an empty Optional if there is no Minecraft account associated with the uuid
      */
@@ -109,4 +111,11 @@ public interface UserManager {
      */
     @NotNull
     CompletableFuture<Optional<NecrifyUser>> loadOrCreateUser(@NotNull String player);
+
+    /**
+     * Returns all loaded users.
+     *
+     * @return a collection of all loaded users
+     */
+    @NotNull Collection<? extends NecrifyUser> getLoadedUsers();
 }

necrify-common/build.gradle.kts

@@ -34,6 +34,7 @@ dependencies {
     compileOnly(libs.slf4j.api)
     compileOnly("com.google.code.gson:gson:2.11.0")
     compileOnly(libs.bundles.adventure)
+    api(libs.adventure.text.feature.pagination)
     testImplementation(libs.junit.jupiter.api)
     testRuntimeOnly(libs.junit.jupiter.engine)
 }