Add basic structure of punishment logs/history

necrify-api/src/main/java/de/jvstvshd/necrify/api/punishment/PunishmentTypeRegistry.java

@@ -25,7 +25,7 @@
 
 /**
  * A central registry for {@link PunishmentType}s. This class is used to register and retrieve punishment types by their integer IDs.
- * @since 1.2.0
+ * @since 1.2.2
  */
 public final class PunishmentTypeRegistry {
 

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

@@ -0,0 +1,88 @@
+/*
+ * This file is part of Necrify (formerly Velocity Punishment), a plugin designed to manage player's punishments for the platforms Velocity and partly Paper.
+ * Copyright (C) 2022-2024 JvstvsHD
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package de.jvstvshd.necrify.api.punishment.log;
+
+import de.jvstvshd.necrify.api.punishment.Punishment;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.List;
+
+/**
+ * Represents a log of a punishment, containing all actions that have been performed on the punishment.
+ * @since 1.2.2
+ */
+public interface PunishmentLog {
+
+    /**
+     * Returns the punishment this log belongs to.
+     * @return the punishment this log belongs to.
+     */
+    @NotNull
+    Punishment getPunishment();
+
+    /**
+     * Returns a list containing all entries of this log.
+     * @return a list containing all entries of this log.
+     */
+    @NotNull
+    List<PunishmentLogEntry> getEntries();
+
+    /**
+     * Returns a list containing all entries of this log with the given action. If no entries with the given action are found, an empty list is returned.
+     * @param action the action to filter the entries by
+     * @return a list containing all entries of this log with the given action.
+     */
+    @NotNull
+    List<PunishmentLogEntry> getEntries(@NotNull PunishmentLogAction action);
+
+    /**
+     * Returns the first entry of this log with the given action. If no entry with the given action is found, null is returned.
+     * @param action the action to filter the entries by
+     * @return the first entry of this log with the given action.
+     */
+    @Nullable
+    PunishmentLogEntry getEntry(@NotNull PunishmentLogAction action);
+
+    /**
+     * Returns the entry at the given index. If the index is out of bounds, an exception is thrown.
+     * @param index the index of the entry
+     * @return the entry at the given index.
+     * @throws IndexOutOfBoundsException if the index is out of bounds
+     */
+    @NotNull
+    PunishmentLogEntry getEntry(int index);
+
+    /**
+     * Returns the latest entry of this log. If the log is empty, an exception is thrown.
+     * @return the latest entry of this log.
+     * @throws IndexOutOfBoundsException if the log is empty
+     */
+    @NotNull
+    default PunishmentLogEntry getLatestEntry() {
+        return getEntry(getEntries().size() - 1);
+    }
+
+    /**
+     * Logs a new action with the given message. The action is automatically associated with the punishment of this log.
+     * @param action the action to log
+     * @param message the message to log
+     */
+    void log(@NotNull PunishmentLogAction action, @NotNull String message);
+}

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

@@ -0,0 +1,93 @@
+/*
+ * This file is part of Necrify (formerly Velocity Punishment), a plugin designed to manage player's punishments for the platforms Velocity and partly Paper.
+ * Copyright (C) 2022-2024 JvstvsHD
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package de.jvstvshd.necrify.api.punishment.log;
+
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Represents an action that has been performed on a punishment. This only contains what type of action has been performed,
+ * not the actual action itself.
+ *
+ * @since 1.2.2
+ */
+public interface PunishmentLogAction {
+
+    /**
+     * Returns the name of this action.
+     *
+     * @return the name of this action.
+     */
+    @NotNull
+    String name();
+
+    /**
+     * Returns whether this action can only be logged once. If this is true, the action can not be logged multiple times for the same punishment.
+     * This also makes using {@link PunishmentLog#getEntry(PunishmentLogAction)} possible.
+     *
+     * @return whether this action can only be logged once.
+     */
+    boolean onlyOnce();
+
+    /**
+     * A punishment was created. This action can only be logged once.
+     */
+    PunishmentLogAction CREATED = new SimplePunishmentLogAction("created", true);
+
+    /**
+     * The reason of a punishment was changed. This action can be logged multiple times. The reason stored in the associated
+     * {@link PunishmentLogEntry} is the new reason. The old reason can be retrieved from the previous entry.
+     */
+    PunishmentLogAction CHANGE_REASON = new SimplePunishmentLogAction("change_reason", false);
+
+    /**
+     * The duration of a punishment was changed. This action can be logged multiple times. The duration stored in the associated
+     * {@link PunishmentLogEntry} is the new duration. The old duration can be retrieved from the previous entry.
+     */
+    PunishmentLogAction CHANGE_DURATION = new SimplePunishmentLogAction("change_duration", 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.
+     */
+    PunishmentLogAction CHANGE_PREDECESSOR = new SimplePunishmentLogAction("change_predecessor", false);
+
+    /**
+     * The successor of a punishment was changed. This action can be logged multiple times. The successor stored in the associated
+     * {@link PunishmentLogEntry} is the new successor. The old successor can be retrieved from the previous entry.
+     */
+    PunishmentLogAction CHANGE_SUCCESSOR = new SimplePunishmentLogAction("change_successor", false);
+
+    /**
+     * A punishment was removed. This action can only be logged once.
+     */
+    PunishmentLogAction REMOVED = new SimplePunishmentLogAction("removed", true);
+
+    /**
+     * 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 onlyOnce whether the action can only be logged once
+     */
+    record SimplePunishmentLogAction(String name, boolean onlyOnce) implements PunishmentLogAction {
+
+        @Override
+        public @NotNull String name() {
+            return name;
+        }
+    }
+}

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

@@ -0,0 +1,79 @@
+/*
+ * This file is part of Necrify (formerly Velocity Punishment), a plugin designed to manage player's punishments for the platforms Velocity and partly Paper.
+ * Copyright (C) 2022-2024 JvstvsHD
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package de.jvstvshd.necrify.api.punishment.log;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * 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 {
+        registerAction(PunishmentLogAction.CREATED);
+        registerAction(PunishmentLogAction.CHANGE_REASON);
+        registerAction(PunishmentLogAction.CHANGE_DURATION);
+        registerAction(PunishmentLogAction.CHANGE_PREDECESSOR);
+        registerAction(PunishmentLogAction.CHANGE_SUCCESSOR);
+        registerAction(PunishmentLogAction.REMOVED);
+    }
+
+    private final static Map<String, PunishmentLogAction> actions = new HashMap<>();
+
+    /**
+     * 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) {
+        actions.put(action.name(), 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
+     */
+    public static Optional<PunishmentLogAction> getAction(@NotNull String name) {
+        return Optional.ofNullable(actions.get(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
+     */
+    @Nullable
+    public static PunishmentLogAction unregisterAction(String name) {
+        return actions.remove(name);
+    }
+
+    /**
+     * Returns a copy of all registered {@link PunishmentLogAction}s.
+     * @return a copy of all registered actions
+     */
+    public static Map<String, PunishmentLogAction> getActions() {
+        return new HashMap<>(actions);
+    }
+}

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

@@ -0,0 +1,76 @@
+/*
+ * This file is part of Necrify (formerly Velocity Punishment), a plugin designed to manage player's punishments for the platforms Velocity and partly Paper.
+ * Copyright (C) 2022-2024 JvstvsHD
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package de.jvstvshd.necrify.api.punishment.log;
+
+import de.jvstvshd.necrify.api.duration.PunishmentDuration;
+import de.jvstvshd.necrify.api.punishment.Punishment;
+import de.jvstvshd.necrify.api.user.NecrifyUser;
+import net.kyori.adventure.text.Component;
+import org.jetbrains.annotations.NotNull;
+
+import java.time.Instant;
+import java.util.Objects;
+
+/**
+ * Represents an entry in a {@link PunishmentLog}. This contains all information about a punishment log entry.
+ * There is no information about old values if they have been changed, this has to be done by using {@link #previous() the previous entry}.
+ * @param actor the actor who performed the action
+ * @param message the message of the action
+ * @param duration the duration of the punishment
+ * @param reason the reason of the punishment
+ * @param predecessor the predecessor of the punishment or null if there is none
+ * @param punishment the punishment this entry belongs to
+ * @param successor the successor of the punishment or null if there is none
+ * @param action the action that was performed
+ * @param log the log this entry belongs to
+ * @param instant the instant the action was performed
+ * @param index the index of this entry in the log (0-based)
+ */
+public record PunishmentLogEntry(NecrifyUser actor, String message, PunishmentDuration duration, Component reason,
+                                 Punishment predecessor, Punishment punishment, Punishment successor,
+                                 PunishmentLogAction action, PunishmentLog log, Instant instant, int index) {
+
+    /**
+     * Returns the previous entry in the log. If this is the first entry, this entry is returned.
+     * @return the previous entry in the log
+     */
+    @NotNull
+    public PunishmentLogEntry previous() {
+        return Objects.requireNonNullElse(log.getEntries().get(index - 1), this);
+    }
+
+    /**
+     * Returns the next entry in the log. If this is the last entry, this entry is returned.
+     * @return the next entry in the log
+     */
+    @NotNull
+    public PunishmentLogEntry next() {
+        return Objects.requireNonNullElse(log.getEntries().get(index + 1), this);
+    }
+
+    /**
+     * Returns the affected user of the punishment. This is the user who is affected by the punishment and equivalent
+     * to {@link #punishment()}.{@link Punishment#getUser() getUser()}.
+     * @return the affected user of the punishment
+     */
+    @NotNull
+    public NecrifyUser getAffectedUser() {
+        return punishment.getUser();
+    }
+}

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

@@ -20,6 +20,7 @@
 
 import de.jvstvshd.necrify.api.duration.PunishmentDuration;
 import de.jvstvshd.necrify.api.punishment.*;
+import de.jvstvshd.necrify.api.punishment.log.PunishmentLog;
 import net.kyori.adventure.text.Component;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
@@ -201,4 +202,13 @@ default Optional<Punishment> getPunishment(@NotNull UUID punishmentUuid) {
      */
     @NotNull
     Locale getLocale();
+
+    /**
+     * Loads the punishment log of this user. The punishment log contains all actions that were performed on this user.
+     * This method may take some time to complete. The returned future will complete exceptionally with {@link java.util.NoSuchElementException}
+     * if the user does not exist in the system.
+     * @return a {@link CompletableFuture} containing the punishment log of this user.
+     */
+    @NotNull
+    CompletableFuture<PunishmentLog> loadPunishmentLog();
 }

necrify-common/src/main/java/de/jvstvshd/necrify/common/user/AbstractConsoleUser.java

@@ -21,6 +21,7 @@
 import de.jvstvshd.necrify.api.duration.PunishmentDuration;
 import de.jvstvshd.necrify.api.message.MessageProvider;
 import de.jvstvshd.necrify.api.punishment.*;
+import de.jvstvshd.necrify.api.punishment.log.PunishmentLog;
 import de.jvstvshd.necrify.api.user.NecrifyUser;
 import de.jvstvshd.necrify.api.user.UserDeletionReason;
 import net.kyori.adventure.text.Component;
@@ -130,4 +131,9 @@ public void sendMessage(@NotNull String key, TextColor color, Component... args)
     public MessageProvider provider() {
         return provider;
     }
+
+    @Override
+    public @NotNull CompletableFuture<PunishmentLog> loadPunishmentLog() {
+        return throwUnsupported();
+    }
 }