From bb5b1f8db4bfdccd4911290e7da941dd44c1feff Mon Sep 17 00:00:00 2001
From: "Vincent B." <79211348+Snabeldier@users.noreply.github.com>
Date: Sun, 22 Dec 2024 21:38:25 +0100
Subject: [PATCH] docs(Core): add some docs to user related methods and
 position them higher  (#252)

---
 src/main/java/minevalley/core/api/Core.java   | 100 ++++++++++++------
 .../core/api/users/OnTimeHandler.java         |  11 ++
 2 files changed, 77 insertions(+), 34 deletions(-)

diff --git a/src/main/java/minevalley/core/api/Core.java b/src/main/java/minevalley/core/api/Core.java
index 17703031..dad3aede 100644
--- a/src/main/java/minevalley/core/api/Core.java
+++ b/src/main/java/minevalley/core/api/Core.java
@@ -63,6 +63,8 @@
 import org.bukkit.plugin.java.JavaPlugin;
 import org.bukkit.util.Vector;
 
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import java.text.SimpleDateFormat;
 import java.time.DayOfWeek;
 import java.util.*;
@@ -145,6 +147,70 @@ public static void callEvent(Event event) {
         server.callEvent(event);
     }
 
+    /**
+     * Gets the user of with a specific unique id.
+     * <br>
+     * <strong>Note:</strong> If no user is found, this method returns null.
+     *
+     * @param uniqueId unique id to get user from
+     * @return user object of the given unique id
+     */
+    @Nullable
+    public static User getUser(@Nonnull UUID uniqueId) {
+        return server.getUser(uniqueId);
+    }
+
+    /**
+     * Gets the user of this specific player.
+     * <br>
+     * <strong>Note:</strong> If no user is found, a new one is created based on the player.
+     *
+     * @param player player to get user from
+     * @return user object of the given player
+     */
+    @NonNull
+    public static OnlineUser getOnlineUser(@Nonnull Player player) {
+        return server.getOnlineUser(player);
+    }
+
+    /**
+     * Gets the name of the player with the specific unique id.
+     * <br>
+     * <strong>Note:</strong> If no player is found, this method returns null.
+     * <p>
+     * <strong>Runtime Optimization</strong>
+     * <ul>
+     *     <li>This method uses an internal cache</li>
+     *     <li>If the player is online, no use of the mojang api is taken</li>
+     * </ul>
+     * </p>
+     *
+     * @param uniqueId unique id of the player
+     * @return name of the player
+     */
+    @Nullable
+    public static String getName(@Nonnull UUID uniqueId) {
+        return server.getName(uniqueId);
+    }
+
+    /**
+     * Gets the unique id of the player with the specific name.
+     * <br>
+     * <strong>Note:</strong> If no player is found, this method returns null.
+     * <p>
+     *     <strong>Runtime Optimization</strong>
+     *     <ul>
+     *         <li>This method uses an internal cache</li>
+     *         <li>If the player is online, no use of the mojang api is taken</li>
+     * </p>
+     * @param name name of the player
+     * @return unique id as UUID
+     */
+    @Nullable
+    public static UUID getUniqueId(@Nonnull String name) {
+        return server.getUniqueId(name);
+    }
+
     public static void registerCommand(PlayerCommand command) {
         server.registerCommand(command);
     }
@@ -344,40 +410,6 @@ public static List<MetadataValue> getMetadata(Metadatable metadatable, String ke
         return server.getMetadata(metadatable, key);
     }
 
-    /**
-     * Gets a players user object
-     *
-     * @param uniqueId uniqueId to get user from
-     * @return user object of the given uniqueId
-     */
-    public static User getUser(UUID uniqueId) {
-        return server.getUser(uniqueId);
-    }
-
-    public static OnlineUser getOnlineUser(Player player) {
-        return server.getOnlineUser(player);
-    }
-
-    /**
-     * Gets the name of the player with the specific unique id
-     *
-     * @param uniqueId unique id of the player
-     * @return name of the player
-     */
-    public static String getName(UUID uniqueId) {
-        return server.getName(uniqueId);
-    }
-
-    /**
-     * Gets the unique id of the player with the specific name
-     *
-     * @param name name of the player
-     * @return unique id of the player
-     */
-    public static UUID getUniqueId(String name) {
-        return server.getUniqueId(name);
-    }
-
     /**
      * Removes the color-codes from a given string
      *
diff --git a/src/main/java/minevalley/core/api/users/OnTimeHandler.java b/src/main/java/minevalley/core/api/users/OnTimeHandler.java
index 7dd8eb7b..3fd9351d 100644
--- a/src/main/java/minevalley/core/api/users/OnTimeHandler.java
+++ b/src/main/java/minevalley/core/api/users/OnTimeHandler.java
@@ -1,6 +1,7 @@
 package minevalley.core.api.users;
 
 import lombok.Setter;
+import minevalley.core.api.database.Value;
 
 import java.time.LocalDate;
 import java.util.Map;
@@ -22,6 +23,16 @@ public static int getOnTimeSinceRestartInMinutes(User user) {
         return manager.getOnTimeSinceRestartInMinutes(user);
     }
 
+    public static void purgeOnTime() {
+        // TODO 22.12.2024: purgeOnTime() (OnTimeHandler)
+//        USER_BY_UUID.values().forEach(user -> {
+//            final int delta = OnTimeHandler.getOnTimeSinceRestartInMinutes(user);
+//            if (delta != 0) {
+//                user.getEntry().changeValue(new Value("ontime", user.totalOnTimeInMinutes + delta));
+//            }
+//        });
+    }
+
     public interface Manager {
 
         int getTodayOnTimeInMinutes(User user);