Skip to content

Commit

Permalink
Migration to new username API (#2462)
Browse files Browse the repository at this point in the history 
* Deprecate some getters
* Add global_name support
* Update Member#getEffectiveName
* Handle potential removal of discriminator field
* Deprecate AccountManager#setName
  • Loading branch information
@MinnDevelopment
MinnDevelopment authored May 19, 2023
1 parent ad66a69 commit b877574
Show file tree
Hide file tree
Showing 19 changed files with 368 additions and 126 deletions.
17 changes: 17 additions & 0 deletions src/main/java/net/dv8tion/jda/api/JDA.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -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);
Expand Down
16 changes: 16 additions & 0 deletions src/main/java/net/dv8tion/jda/api/entities/Guild.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand Down
2 changes: 1 addition & 1 deletion src/main/java/net/dv8tion/jda/api/entities/Member.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
120 changes: 39 additions & 81 deletions src/main/java/net/dv8tion/jda/api/entities/User.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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();
Expand Down Expand Up @@ -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
Expand All @@ -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();
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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();
Expand Down
33 changes: 33 additions & 0 deletions src/main/java/net/dv8tion/jda/api/entities/UserSnowflake.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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());
}
}
Loading

0 comments on commit b877574

Please sign in to comment.