Start migration to new username API

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

@@ -16,6 +16,8 @@
 
 package net.dv8tion.jda.api;
 
+import net.dv8tion.jda.annotations.ForRemoval;
+import net.dv8tion.jda.annotations.Incubating;
 import net.dv8tion.jda.api.entities.*;
 import net.dv8tion.jda.api.entities.channel.Channel;
 import net.dv8tion.jda.api.entities.channel.attribute.IGuildChannelContainer;
@@ -1028,8 +1030,14 @@ default User getUserById(long id)
      *         If the provided tag is null or not in the described format
      *
      * @return The {@link net.dv8tion.jda.api.entities.User} for the discord tag or null if no user has the provided tag
+     *
+     * @deprecated This will become obsolete in the future.
+     *             Discriminators are being phased out and replaced by globally unique usernames.
+     *             For more information, see <a href="https://support.discord.com/hc/en-us/articles/12620128861463" target="_blank">New Usernames &amp; Display Names</a>.
      */
     @Nullable
+    @Deprecated
+    @ForRemoval
     default User getUserByTag(@Nonnull String tag)
     {
         Checks.notNull(tag, "Tag");
@@ -1061,8 +1069,14 @@ default User getUserByTag(@Nonnull String tag)
      *         If the provided arguments are null or not in the described format
      *
      * @return The {@link net.dv8tion.jda.api.entities.User} for the discord tag or null if no user has the provided tag
+     *
+     * @deprecated This will become obsolete in the future.
+     *             Discriminators are being phased out and replaced by globally unique usernames.
+     *             For more information, see <a href="https://support.discord.com/hc/en-us/articles/12620128861463" target="_blank">New Usernames &amp; Display Names</a>.
      */
     @Nullable
+    @Deprecated
+    @ForRemoval
     default User getUserByTag(@Nonnull String username, @Nonnull String discriminator)
     {
         Checks.notNull(username, "Username");
@@ -1092,8 +1106,11 @@ default User getUserByTag(@Nonnull String username, @Nonnull String discriminato
      *         Whether to ignore case or not when comparing the provided name to each {@link net.dv8tion.jda.api.entities.User#getName()}.
      *
      * @return Possibly-empty immutable list of {@link net.dv8tion.jda.api.entities.User Users} that all have the same name as the provided name.
+     *
+     * @incubating This will be replaced in the future when the rollout of globally unique usernames has been completed.
      */
     @Nonnull
+    @Incubating
     default List<User> getUsersByName(@Nonnull String name, boolean ignoreCase)
     {
         return getUserCache().getElementsByName(name, ignoreCase);

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

@@ -17,6 +17,7 @@
 
 import net.dv8tion.jda.annotations.DeprecatedSince;
 import net.dv8tion.jda.annotations.ForRemoval;
+import net.dv8tion.jda.annotations.Incubating;
 import net.dv8tion.jda.annotations.ReplaceWith;
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.Permission;
@@ -1075,8 +1076,14 @@ default Member getMemberById(long userId)
      * @return The {@link net.dv8tion.jda.api.entities.Member} for the discord tag or null if no member has the provided tag
      *
      * @see    net.dv8tion.jda.api.JDA#getUserByTag(String)
+     *
+     * @deprecated This will become obsolete in the future.
+     *             Discriminators are being phased out and replaced by globally unique usernames.
+     *             For more information, see <a href="https://support.discord.com/hc/en-us/articles/12620128861463" target="_blank">New Usernames &amp; Display Names</a>.
      */
     @Nullable
+    @Deprecated
+    @ForRemoval
     default Member getMemberByTag(@Nonnull String tag)
     {
         User user = getJDA().getUserByTag(tag);
@@ -1109,8 +1116,14 @@ default Member getMemberByTag(@Nonnull String tag)
      * @return The {@link net.dv8tion.jda.api.entities.Member} for the discord tag or null if no member has the provided tag
      *
      * @see    #getMemberByTag(String)
+     *
+     * @deprecated This will become obsolete in the future.
+     *             Discriminators are being phased out and replaced by globally unique usernames.
+     *             For more information, see <a href="https://support.discord.com/hc/en-us/articles/12620128861463" target="_blank">New Usernames &amp; Display Names</a>.
      */
     @Nullable
+    @Deprecated
+    @ForRemoval
     default Member getMemberByTag(@Nonnull String username, @Nonnull String discriminator)
     {
         User user = getJDA().getUserByTag(username, discriminator);
@@ -1158,8 +1171,11 @@ default List<Member> getMembers()
      * @return Possibly-empty immutable list of all Members with the same name as the name provided.
      *
      * @see    #retrieveMembersByPrefix(String, int)
+     *
+     * @incubating This will be replaced in the future when the rollout of globally unique usernames has been completed.
      */
     @Nonnull
+    @Incubating
     default List<Member> getMembersByName(@Nonnull String name, boolean ignoreCase)
     {
         return getMemberCache().getElementsByUsername(name, ignoreCase);

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

@@ -252,7 +252,7 @@ default boolean isTimedOut()
     /**
      * Retrieves the Name displayed in the official Discord Client.
      *
-     * @return The Nickname of this Member or the Username if no Nickname is present.
+     * @return The guild nickname of this Member or the {@link User#getEffectiveName() effective user name} if no guild nickname is present.
      */
     @Nonnull
     String getEffectiveName();

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

@@ -16,6 +16,8 @@
 package net.dv8tion.jda.api.entities;
 
 
+import net.dv8tion.jda.annotations.ForRemoval;
+import net.dv8tion.jda.annotations.ReplaceWith;
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.channel.concrete.PrivateChannel;
 import net.dv8tion.jda.api.requests.restaction.CacheRestAction;
@@ -131,34 +133,54 @@ static UserSnowflake fromId(@Nonnull String id)
     /**
      * The username of the {@link net.dv8tion.jda.api.entities.User User}. Length is between 2 and 32 characters (inclusive).
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return Never-null String containing the {@link net.dv8tion.jda.api.entities.User User}'s username.
      */
     @Nonnull
     String getName();
 
+    /**
+     * The global display name of the user.
+     * <br>This name is not unique and allows more characters.
+     *
+     * <p>This name is usually displayed in the UI.
+     *
+     * @return The global display name or null if unset.
+     */
+    @Nullable
+    String getGlobalName();
+
+    /**
+     * The name visible in the UI.
+     * <br>If the {@link #getGlobalName() global name} is {@code null}, this returns the {@link #getName() username} instead.
+     *
+     * @return The effective display name
+     */
+    @Nonnull
+    default String getEffectiveName()
+    {
+        String globalName = getGlobalName();
+        return globalName != null ? globalName : getName();
+    }
+
     /**
      * <br>The discriminator of the {@link net.dv8tion.jda.api.entities.User User}. Used to differentiate between users with the same usernames.
      * <br>This only contains the 4 digits after the username and the #.
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     * Ex: 6297
-     *
      * @return Never-null String containing the {@link net.dv8tion.jda.api.entities.User User} discriminator.
+     *
+     * @deprecated This will become obsolete in the future.
+     *             Discriminators are being phased out and replaced by globally unique usernames.
+     *             For more information, see <a href="https://support.discord.com/hc/en-us/articles/12620128861463" target="_blank">New Usernames &amp; Display Names</a>.
      */
     @Nonnull
+    @Deprecated
+    @ForRemoval
     String getDiscriminator();
 
     /**
      * The Discord ID for this user's avatar image.
      * If the user has not set an image, this will return null.
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return Possibly-null String containing the {@link net.dv8tion.jda.api.entities.User User} avatar id.
      */
     @Nullable
@@ -168,9 +190,6 @@ static UserSnowflake fromId(@Nonnull String id)
      * The URL for the user's avatar image.
      * If the user has not set an image, this will return null.
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return Possibly-null String containing the {@link net.dv8tion.jda.api.entities.User User} avatar url.
      */
     @Nullable
@@ -194,52 +213,11 @@ default ImageProxy getAvatar()
         return avatarUrl == null ? null : new ImageProxy(avatarUrl);
     }
 
-    /**
-     * The Discord ID for this user's default avatar image.
-     *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
-     * @return Never-null String containing the {@link net.dv8tion.jda.api.entities.User User} default avatar id.
-     */
-    @Nonnull
-    String getDefaultAvatarId();
-
-    /**
-     * The URL for the user's default avatar image.
-     *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
-     * @return Never-null String containing the {@link net.dv8tion.jda.api.entities.User User} default avatar url.
-     */
-    @Nonnull
-    default String getDefaultAvatarUrl()
-    {
-        return String.format(DEFAULT_AVATAR_URL, getDefaultAvatarId());
-    }
-
-    /**
-     * Returns an {@link ImageProxy} for this user's default avatar.
-     *
-     * @return Never-null {@link ImageProxy} of this user's default avatar
-     *
-     * @see    #getDefaultAvatarUrl()
-     */
-    @Nonnull
-    default ImageProxy getDefaultAvatar()
-    {
-        return new ImageProxy(getDefaultAvatarUrl());
-    }
-
     /**
      * The URL for the user's avatar image.
      * If they do not have an avatar set, this will return the URL of their
      * default avatar
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return  Never-null String containing the {@link net.dv8tion.jda.api.entities.User User} effective avatar url.
      */
     @Nonnull
@@ -268,9 +246,6 @@ default ImageProxy getEffectiveAvatar()
      * Returns a completed RestAction if this User has been retrieved using {@link JDA#retrieveUserById(long)}.
      * You can use {@link CacheRestAction#useCache(boolean) useCache(false)} to force the request for a new profile with up-to-date information.
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return {@link CacheRestAction} - Type: {@link User.Profile}
      */
     @Nonnull
@@ -281,21 +256,22 @@ default ImageProxy getEffectiveAvatar()
      * The "tag" for this user
      * <p>This is the equivalent of calling {@link java.lang.String#format(String, Object...) String.format}("%#s", user)
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return Never-null String containing the tag for this user, for example DV8FromTheWorld#6297
+     *
+     * @deprecated This will become obsolete in the future.
+     *             Discriminators are being phased out and replaced by globally unique usernames.
+     *             For more information, see <a href="https://support.discord.com/hc/en-us/articles/12620128861463" target="_blank">New Usernames &amp; Display Names</a>.
      */
     @Nonnull
+    @Deprecated
+    @ForRemoval
+    @ReplaceWith("getName()")
     String getAsTag();
 
     /**
      * Whether or not the currently logged in user and this user have a currently open
      * {@link net.dv8tion.jda.api.entities.channel.concrete.PrivateChannel PrivateChannel} or not.
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return True if the logged in account shares a PrivateChannel with this user.
      */
     boolean hasPrivateChannel();
@@ -342,9 +318,6 @@ default ImageProxy getEffectiveAvatar()
      * Finds and collects all {@link net.dv8tion.jda.api.entities.Guild Guild} instances that contain this {@link net.dv8tion.jda.api.entities.User User} within the current {@link net.dv8tion.jda.api.JDA JDA} instance.<br>
      * <p>This method is a shortcut for {@link net.dv8tion.jda.api.JDA#getMutualGuilds(User...) JDA.getMutualGuilds(User)}.</p>
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return Immutable list of all {@link net.dv8tion.jda.api.entities.Guild Guilds} that this user is a member of.
      */
     @Nonnull
@@ -353,9 +326,6 @@ default ImageProxy getEffectiveAvatar()
     /**
      * Returns whether or not the given user is a Bot-Account (special badge in client, some different behaviour)
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return If the User's Account is marked as Bot
      */
     boolean isBot();
@@ -364,19 +334,13 @@ default ImageProxy getEffectiveAvatar()
      * Returns whether or not the given user is a System account, which includes the urgent message account
      * and the community updates bot.
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return Whether the User's account is marked as System
      */
     boolean isSystem();
 
     /**
      * Returns the {@link net.dv8tion.jda.api.JDA JDA} instance of this User
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return the corresponding JDA instance
      */
     @Nonnull
@@ -385,9 +349,6 @@ default ImageProxy getEffectiveAvatar()
     /**
      * Returns the {@link net.dv8tion.jda.api.entities.User.UserFlag UserFlags} of this user.
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return EnumSet containing the flags of the user.
      */
     @Nonnull
@@ -396,9 +357,6 @@ default ImageProxy getEffectiveAvatar()
     /**
      * Returns the bitmask representation of the {@link net.dv8tion.jda.api.entities.User.UserFlag UserFlags} of this user.
      *
-     * @throws UnsupportedOperationException
-     *         If this User was created with {@link #fromId(long)}
-     *
      * @return bitmask representation of the user's flags.
      */
     int getFlagsRaw();

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

@@ -17,6 +17,7 @@
 package net.dv8tion.jda.api.entities;
 
 import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.utils.ImageProxy;
 import net.dv8tion.jda.api.utils.MiscUtil;
 import net.dv8tion.jda.internal.entities.UserSnowflakeImpl;
 
@@ -64,4 +65,36 @@ static UserSnowflake fromId(@Nonnull String id)
     {
         return fromId(MiscUtil.parseSnowflake(id));
     }
+
+    /**
+     * The Discord ID for this user's default avatar image.
+     *
+     * @return Never-null String containing the user's default avatar id.
+     */
+    @Nonnull
+    String getDefaultAvatarId();
+
+    /**
+     * The URL for the user's default avatar image.
+     *
+     * @return Never-null String containing the user's default avatar url.
+     */
+    @Nonnull
+    default String getDefaultAvatarUrl()
+    {
+        return String.format(User.DEFAULT_AVATAR_URL, getDefaultAvatarId());
+    }
+
+    /**
+     * Returns an {@link ImageProxy} for this user's default avatar.
+     *
+     * @return Never-null {@link ImageProxy} of this user's default avatar
+     *
+     * @see    #getDefaultAvatarUrl()
+     */
+    @Nonnull
+    default ImageProxy getDefaultAvatar()
+    {
+        return new ImageProxy(getDefaultAvatarUrl());
+    }
 }