Add UserSnowflake and improve User#fromId (#2065)

src/main/java/net/dv8tion/jda/api/JDA.java

@@ -965,7 +965,7 @@ default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
      *
      * @return Immutable list of all {@link Guild Guild} instances which have all {@link net.dv8tion.jda.api.entities.User Users} in them.
      *
-     * @see    Guild#isMember(net.dv8tion.jda.api.entities.User)
+     * @see    Guild#isMember(UserSnowflake)
      */
     @Nonnull
     List<Guild> getMutualGuilds(@Nonnull User... users);

src/main/java/net/dv8tion/jda/api/entities/Member.java

@@ -40,7 +40,7 @@
  *
  * @since 3.0
  *
- * @see   Guild#getMember(User)
+ * @see   Guild#getMember(UserSnowflake)
  * @see   Guild#getMemberCache()
  * @see   Guild#getMemberById(long)
  * @see   Guild#getMemberByTag(String)
@@ -51,7 +51,7 @@
  * @see   Guild#getMembersWithRoles(Role...)
  * @see   Guild#getMembers()
  */
-public interface Member extends IMentionable, IPermissionHolder
+public interface Member extends IMentionable, IPermissionHolder, UserSnowflake
 {
     /** Template for {@link #getAvatarUrl()}. */
     String AVATAR_URL = "https://cdn.discordapp.com/guilds/%s/users/%s/avatars/%s.%s";
@@ -285,16 +285,16 @@ default String getEffectiveAvatarUrl()
      * <br>The roles are ordered based on their position. The highest role being at index 0
      * and the lowest at the last index.
      *
-     * <p>A Member's roles can be changed using the {@link Guild#addRoleToMember(Member, Role)}, {@link Guild#removeRoleFromMember(Member, Role)}, and {@link Guild#modifyMemberRoles(Member, Collection, Collection)}
+     * <p>A Member's roles can be changed using the {@link Guild#addRoleToMember(UserSnowflake, Role)}, {@link Guild#removeRoleFromMember(UserSnowflake, Role)}, and {@link Guild#modifyMemberRoles(Member, Collection, Collection)}
      * methods in {@link net.dv8tion.jda.api.entities.Guild Guild}.
      *
      * <p><b>The Public Role ({@code @everyone}) is not included in the returned immutable list of roles
      * <br>It is implicit that every member holds the Public Role in a Guild thus it is not listed here!</b>
      *
      * @return An immutable List of {@link net.dv8tion.jda.api.entities.Role Roles} for this Member.
      *
-     * @see    Guild#addRoleToMember(Member, Role)
-     * @see    Guild#removeRoleFromMember(Member, Role)
+     * @see    Guild#addRoleToMember(UserSnowflake, Role)
+     * @see    Guild#removeRoleFromMember(UserSnowflake, Role)
      * @see    Guild#modifyMemberRoles(Member, Collection, Collection)
      */
     @Nonnull
@@ -410,7 +410,7 @@ default String getEffectiveAvatarUrl()
      * Bans this Member and deletes messages sent by the user based on the amount of delDays.
      * <br>If you wish to ban a member without deleting any messages, provide delDays with a value of 0.
      *
-     * <p>You can unban a user with {@link net.dv8tion.jda.api.entities.Guild#unban(User) Guild.unban(User)}.
+     * <p>You can unban a user with {@link net.dv8tion.jda.api.entities.Guild#unban(UserSnowflake) Guild.unban(UserSnowflake)}.
      *
      * <p><b>Note:</b> {@link net.dv8tion.jda.api.entities.Guild#getMembers()} will still contain the
      * {@link net.dv8tion.jda.api.entities.Member Member} until Discord sends the
@@ -455,7 +455,7 @@ default AuditableRestAction<Void> ban(int delDays)
      * Bans this Member and deletes messages sent by the user based on the amount of delDays.
      * <br>If you wish to ban a member without deleting any messages, provide delDays with a value of 0.
      *
-     * <p>You can unban a user with {@link net.dv8tion.jda.api.entities.Guild#unban(User) Guild.unban(User)}.
+     * <p>You can unban a user with {@link net.dv8tion.jda.api.entities.Guild#unban(UserSnowflake) Guild.unban(UserSnowflake)}.
      *
      * <p><b>Note:</b> {@link net.dv8tion.jda.api.entities.Guild#getMembers()} will still contain the
      * {@link net.dv8tion.jda.api.entities.Member Member} until Discord sends the

src/main/java/net/dv8tion/jda/api/entities/User.java

@@ -19,7 +19,7 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.requests.RestAction;
 import net.dv8tion.jda.api.utils.MiscUtil;
-import net.dv8tion.jda.internal.entities.UserById;
+import net.dv8tion.jda.internal.entities.UserSnowflakeImpl;
 import net.dv8tion.jda.internal.utils.Checks;
 
 import javax.annotation.CheckReturnValue;
@@ -71,7 +71,7 @@
  *
  * @see JDA#retrieveUserById(String)
  */
-public interface User extends IMentionable
+public interface User extends UserSnowflake
 {
     /**
      * Compiled pattern for a Discord Tag: {@code (.{2,32})#(\d{4})}
@@ -90,41 +90,37 @@ public interface User extends IMentionable
 
     /**
      * Creates a User instance which only wraps an ID.
-     * <br>All other methods beside {@link #getIdLong()} and {@link #getId()} will throw {@link UnsupportedOperationException}.
      *
      * @param  id
      *         The user id
      *
-     * @return A user instance
+     * @return A {@link UserSnowflake} instance
      *
      * @see    JDA#retrieveUserById(long)
-     *
-     * @since  4.2.1
+     * @see    UserSnowflake#fromId(long)
      */
     @Nonnull
-    static User fromId(long id)
+    static UserSnowflake fromId(long id)
     {
-        return new UserById(id);
+        return new UserSnowflakeImpl(id);
     }
 
     /**
      * Creates a User instance which only wraps an ID.
-     * <br>All other methods beside {@link #getIdLong()} and {@link #getId()} will throw {@link UnsupportedOperationException}.
      *
      * @param  id
      *         The user id
      *
      * @throws IllegalArgumentException
      *         If the provided ID is not a valid snowflake
      *
-     * @return A user instance
+     * @return A {@link UserSnowflake} instance
      *
      * @see    JDA#retrieveUserById(String)
-     *
-     * @since  4.2.1
+     * @see    UserSnowflake#fromId(String)
      */
     @Nonnull
-    static User fromId(@Nonnull String id)
+    static UserSnowflake fromId(@Nonnull String id)
     {
         return fromId(MiscUtil.parseSnowflake(id));
     }

src/main/java/net/dv8tion/jda/api/entities/UserSnowflake.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dv8tion.jda.api.entities;
+
+import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.utils.MiscUtil;
+import net.dv8tion.jda.internal.entities.UserSnowflakeImpl;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Represents an abstract user reference by only the user ID.
+ *
+ * <p>This is used for methods which only need a user ID to function, you cannot use this for getting names or similar.
+ * To get information about a user by their ID you can use {@link JDA#retrieveUserById(long)} or {@link JDA#getUserById(long)} instead.
+ */
+public interface UserSnowflake extends IMentionable // Make this a value type whenever that's finally released!
+{
+    /**
+     * Creates a User instance which only wraps an ID.
+     *
+     * @param  id
+     *         The user id
+     *
+     * @return A user snowflake instance
+     *
+     * @see    JDA#retrieveUserById(long)
+     */
+    @Nonnull
+    static UserSnowflake fromId(long id)
+    {
+        return new UserSnowflakeImpl(id);
+    }
+
+    /**
+     * Creates a User instance which only wraps an ID.
+     *
+     * @param  id
+     *         The user id
+     *
+     * @throws IllegalArgumentException
+     *         If the provided ID is not a valid snowflake
+     *
+     * @return A user snowflake instance
+     *
+     * @see    JDA#retrieveUserById(String)
+     */
+    @Nonnull
+    static UserSnowflake fromId(@Nonnull String id)
+    {
+        return fromId(MiscUtil.parseSnowflake(id));
+    }
+}

src/main/java/net/dv8tion/jda/api/requests/restaction/AuditableRestAction.java

@@ -17,6 +17,7 @@
 package net.dv8tion.jda.api.requests.restaction;
 
 import net.dv8tion.jda.api.audit.ThreadLocalReason;
+import net.dv8tion.jda.api.entities.UserSnowflake;
 import net.dv8tion.jda.api.requests.RestAction;
 import net.dv8tion.jda.api.requests.restaction.pagination.AuditLogPaginationAction;
 
@@ -49,7 +50,7 @@ public interface AuditableRestAction<T> extends RestAction<T>
      *
      * <p>This will specify the reason via the {@code X-Audit-Log-Reason} Request Header.
      * <br>Using methods with a reason parameter will always work and <u>override</u> this header.
-     * (ct. {@link net.dv8tion.jda.api.entities.Guild#ban(net.dv8tion.jda.api.entities.User, int, String) Guild.ban(User, int, String)})
+     * (ct. {@link net.dv8tion.jda.api.entities.Guild#ban(UserSnowflake, int, String) Guild.ban(UserSnowflake, int, String)})
      *
      * @param  reason
      *         The reason for this action which should be logged in the Guild's AuditLogs

src/main/java/net/dv8tion/jda/api/requests/restaction/MemberAction.java

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.Role;
 import net.dv8tion.jda.api.entities.User;
+import net.dv8tion.jda.api.entities.UserSnowflake;
 import net.dv8tion.jda.api.requests.RestAction;
 
 import javax.annotation.CheckReturnValue;
@@ -35,9 +36,7 @@
  *
  * @since  3.7.0
  *
- * @see    Guild#addMember(String, User)
- * @see    Guild#addMember(String, long)
- * @see    Guild#addMember(String, String)
+ * @see    Guild#addMember(String, UserSnowflake)
  * @see    <a href="https://discord.com/developers/docs/topics/oauth2" target="_blank">Discord OAuth2 Documentation</a>
  */
 public interface MemberAction extends RestAction<Void>

src/main/java/net/dv8tion/jda/api/requests/restaction/pagination/AuditLogPaginationAction.java

@@ -20,6 +20,7 @@
 import net.dv8tion.jda.api.audit.AuditLogEntry;
 import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.User;
+import net.dv8tion.jda.api.entities.UserSnowflake;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
@@ -89,43 +90,15 @@ public interface AuditLogPaginationAction extends PaginationAction<AuditLogEntry
     AuditLogPaginationAction type(@Nullable ActionType type);
 
     /**
-     * Filters retrieved entities by the specified {@link net.dv8tion.jda.api.entities.User User}.
+     * Filters retrieved entities by the specified {@link UserSnowflake}.
      * <br>This specified the action issuer and not the target of an action. (Targets need not be users)
      *
      * @param  user
-     *         {@link net.dv8tion.jda.api.entities.User User} used to filter,
-     *         or {@code null} to remove user filtering
+     *         The {@link UserSnowflake} used to filter or {@code null} to remove user filtering.
+     *         This can be a member or user instance or {@link User#fromId(long)}.
      *
      * @return The current AuditLogPaginationAction for chaining convenience
      */
     @Nonnull
-    AuditLogPaginationAction user(@Nullable User user);
-
-    /**
-     * Filters retrieved entities by the specified {@link net.dv8tion.jda.api.entities.User User} id.
-     * <br>This specified the action issuer and not the target of an action. (Targets need not be users)
-     *
-     * @param  userId
-     *         {@link net.dv8tion.jda.api.entities.User User} id used to filter,
-     *         or {@code null} to remove user filtering
-     *
-     * @throws IllegalArgumentException
-     *         If the provided userId is not valid
-     *
-     * @return The current AuditLogPaginationAction for chaining convenience
-     */
-    @Nonnull
-    AuditLogPaginationAction user(@Nullable String userId);
-
-    /**
-     * Filters retrieved entities by the specified {@link net.dv8tion.jda.api.entities.User User} id.
-     *
-     * @param  userId
-     *         {@link net.dv8tion.jda.api.entities.User User} id used to filter,
-     *         or {@code null} to remove user filtering
-     *
-     * @return The current AuditLogPaginationAction for chaining convenience
-     */
-    @Nonnull
-    AuditLogPaginationAction user(long userId);
+    AuditLogPaginationAction user(@Nullable UserSnowflake user);
 }