#1448 Create AuthMePlayer to get player data from API with (#2000)

* #1448 Create AuthMePlayer to get player data from API with

* #1448 Add tests for new API method & AuthMePlayer

* #1448 Create AuthMePlayer to get player data from API with
- Use Optional for all values that may be null

* #1448 Add comment that AuthMePlayer data does not update itself

src/main/java/fr/xephi/authme/api/v3/AuthMeApi.java

@@ -21,6 +21,7 @@ import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Date;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * The current API of AuthMe.
@@ -133,20 +134,17 @@ public class AuthMeApi {
     }
 
     /**
-     * Get the registration ip address of a player.
+     * Returns the AuthMe info of the given player's name, or empty optional if the player doesn't exist.
      *
-     * @param playerName The name of the player to process
-     * @return The registration ip address of the player
+     * @param playerName The player name to look up
+     * @return AuthMe player info, or empty optional if the player doesn't exist
      */
-    public String getRegistrationIp(String playerName) {
+    public Optional<AuthMePlayer> getPlayerInfo(String playerName) {
         PlayerAuth auth = playerCache.getAuth(playerName);
         if (auth == null) {
             auth = dataSource.getAuth(playerName);
         }
-        if (auth != null) {
-            return auth.getRegistrationIp();
-        }
-        return null;
+        return AuthMePlayerImpl.fromPlayerAuth(auth);
     }
 
     /**
@@ -180,7 +178,6 @@ public class AuthMeApi {
      * Get the last (AuthMe) login date of a player.
      *
      * @param playerName The name of the player to process
-     *
      * @return The date of the last login, or null if the player doesn't exist or has never logged in
      * @deprecated Use Java 8's Instant method {@link #getLastLoginTime(String)}
      */
@@ -213,29 +210,6 @@ public class AuthMeApi {
         return null;
     }
 
-    /**
-     * Get the registration (AuthMe) timestamp of a player.
-     *
-     * @param playerName The name of the player to process
-     *
-     * @return The timestamp of when the player was registered, or null if the player doesn't exist or is not registered
-     */
-    public Instant getRegistrationTime(String playerName) {
-        Long registrationDate = getRegistrationMillis(playerName);
-        return registrationDate == null ? null : Instant.ofEpochMilli(registrationDate);
-    }
-
-    private Long getRegistrationMillis(String playerName) {
-        PlayerAuth auth = playerCache.getAuth(playerName);
-        if (auth == null) {
-            auth = dataSource.getAuth(playerName);
-        }
-        if (auth != null) {
-            return auth.getRegistrationDate();
-        }
-        return null;
-    }
-
     /**
      * Return whether the player is registered.
      *

src/main/java/fr/xephi/authme/api/v3/AuthMePlayer.java

@@ -0,0 +1,65 @@
+package fr.xephi.authme.api.v3;
+
+import java.time.Instant;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Read-only player info exposed in the AuthMe API. The data in this object is copied from the
+ * database and not updated afterwards. As such, it may become outdated if the player data changes
+ * in AuthMe.
+ *
+ * @see AuthMeApi#getPlayerInfo
+ */
+public interface AuthMePlayer {
+
+    /**
+     * @return the case-sensitive name of the player, e.g. "thePlayer3030" - never null
+     */
+    String getName();
+
+    /**
+     * Returns the UUID of the player as given by the server (may be offline UUID or not).
+     * The UUID is not present if AuthMe is configured not to store the UUID or if the data is not
+     * present (e.g. older record).
+     *
+     * @return player uuid, or empty optional if not available
+     */
+    Optional<UUID> getUuid();
+
+    /**
+     * Returns the email address associated with this player, or an empty optional if not available.
+     *
+     * @return player's email or empty optional
+     */
+    Optional<String> getEmail();
+
+    /**
+     * @return the registration date of the player's account - never null
+     */
+    Instant getRegistrationDate();
+
+    /**
+     * Returns the IP address with which the player's account was registered. Returns an empty optional
+     * for older accounts, or if the account was registered by someone else (e.g. by an admin).
+     *
+     * @return the ip address used during the registration of the account, or empty optional
+     */
+    Optional<String> getRegistrationIpAddress();
+
+    /**
+     * Returns the last login date of the player. An empty optional is returned if the player never logged in.
+     *
+     * @return date the player last logged in successfully, or empty optional if not applicable
+     */
+    Optional<Instant> getLastLoginDate();
+
+    /**
+     * Returns the IP address the player last logged in with successfully. Returns an empty optional if the
+     * player never logged in.
+     *
+     * @return ip address the player last logged in with successfully, or empty optional if not applicable
+     */
+    Optional<String> getLastLoginIpAddress();
+
+}

src/main/java/fr/xephi/authme/api/v3/AuthMePlayerImpl.java

@@ -0,0 +1,93 @@
+package fr.xephi.authme.api.v3;
+
+import fr.xephi.authme.data.auth.PlayerAuth;
+
+import java.time.Instant;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Implementation of {@link AuthMePlayer}. This implementation is not part of the API and
+ * may have breaking changes in subsequent releases.
+ */
+class AuthMePlayerImpl implements AuthMePlayer {
+
+    private String name;
+    private UUID uuid;
+    private String email;
+
+    private Instant registrationDate;
+    private String registrationIpAddress;
+
+    private Instant lastLoginDate;
+    private String lastLoginIpAddress;
+
+    AuthMePlayerImpl() {
+    }
+
+    /**
+     * Maps the given player auth to an AuthMePlayer instance. Returns an empty optional if
+     * the player auth is null.
+     *
+     * @param playerAuth the player auth or null
+     * @return the mapped player auth, or empty optional if the argument was null
+     */
+    static Optional<AuthMePlayer> fromPlayerAuth(PlayerAuth playerAuth) {
+        if (playerAuth == null) {
+            return Optional.empty();
+        }
+
+        AuthMePlayerImpl authMeUser = new AuthMePlayerImpl();
+        authMeUser.name = playerAuth.getRealName();
+        authMeUser.uuid = playerAuth.getUuid();
+        authMeUser.email = nullIfDefault(playerAuth.getEmail(), PlayerAuth.DB_EMAIL_DEFAULT);
+        Long lastLoginMillis = nullIfDefault(playerAuth.getLastLogin(), PlayerAuth.DB_LAST_LOGIN_DEFAULT);
+        authMeUser.registrationDate = toInstant(playerAuth.getRegistrationDate());
+        authMeUser.registrationIpAddress = playerAuth.getRegistrationIp();
+        authMeUser.lastLoginDate = toInstant(lastLoginMillis);
+        authMeUser.lastLoginIpAddress = nullIfDefault(playerAuth.getLastIp(), PlayerAuth.DB_LAST_IP_DEFAULT);
+        return Optional.of(authMeUser);
+    }
+
+    @Override
+    public String getName() {
+        return name;
+    }
+
+    public Optional<UUID> getUuid() {
+        return Optional.ofNullable(uuid);
+    }
+
+    @Override
+    public Optional<String> getEmail() {
+        return Optional.ofNullable(email);
+    }
+
+    @Override
+    public Instant getRegistrationDate() {
+        return registrationDate;
+    }
+
+    @Override
+    public Optional<String> getRegistrationIpAddress() {
+        return Optional.ofNullable(registrationIpAddress);
+    }
+
+    @Override
+    public Optional<Instant> getLastLoginDate() {
+        return Optional.ofNullable( lastLoginDate);
+    }
+
+    @Override
+    public Optional<String> getLastLoginIpAddress() {
+        return Optional.ofNullable(lastLoginIpAddress);
+    }
+
+    private static Instant toInstant(Long epochMillis) {
+        return epochMillis == null ? null : Instant.ofEpochMilli(epochMillis);
+    }
+
+    private static <T> T nullIfDefault(T value, T defaultValue) {
+        return defaultValue.equals(value) ? null : value;
+    }
+}