net.dv8tion.jda.api.entities.channel.concrete.ThreadChannel Maven / Gradle / Ivy
Show all versions of JDA Show documentation
/*
* 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.channel.concrete;
import net.dv8tion.jda.api.entities.*;
import net.dv8tion.jda.api.entities.channel.ChannelField;
import net.dv8tion.jda.api.entities.channel.ChannelFlag;
import net.dv8tion.jda.api.entities.channel.ChannelType;
import net.dv8tion.jda.api.entities.channel.attribute.IMemberContainer;
import net.dv8tion.jda.api.entities.channel.attribute.ISlowmodeChannel;
import net.dv8tion.jda.api.entities.channel.attribute.IThreadContainer;
import net.dv8tion.jda.api.entities.channel.forums.ForumTag;
import net.dv8tion.jda.api.entities.channel.middleman.GuildMessageChannel;
import net.dv8tion.jda.api.entities.channel.unions.GuildMessageChannelUnion;
import net.dv8tion.jda.api.entities.channel.unions.IThreadContainerUnion;
import net.dv8tion.jda.api.managers.channel.concrete.ThreadChannelManager;
import net.dv8tion.jda.api.requests.RestAction;
import net.dv8tion.jda.api.requests.restaction.CacheRestAction;
import net.dv8tion.jda.api.requests.restaction.pagination.ThreadMemberPaginationAction;
import net.dv8tion.jda.api.utils.MiscUtil;
import net.dv8tion.jda.internal.utils.Checks;
import javax.annotation.CheckReturnValue;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.time.OffsetDateTime;
import java.util.FormattableFlags;
import java.util.Formatter;
import java.util.List;
/**
* Represents Discord Message Threads of all kinds.
*
These are also referred to as "posts" in the context of {@link ForumChannel Forum Channels}.
*
* This includes all thread channel types, namely:
*
* - {@link ChannelType#GUILD_PUBLIC_THREAD}
* - {@link ChannelType#GUILD_PRIVATE_THREAD}
* - {@link ChannelType#GUILD_NEWS_THREAD}
*
*
* When a thread channel is {@link #isArchived() archived}, no new members can be added.
* You can use the {@link #getManager() manager} to {@link ThreadChannelManager#setArchived(boolean) unarchive} the thread.
*
* @see Guild#getThreadChannels()
* @see Guild#getThreadChannelById(long)
* @see Guild#getThreadChannelCache()
*/
public interface ThreadChannel extends GuildMessageChannel, IMemberContainer, ISlowmodeChannel
{
/**
* Whether this thread is public or not.
*
*
Public threads can be read and joined by anyone with read access to its {@link net.dv8tion.jda.api.entities.channel.attribute.IThreadContainer parent channel}.
*
* @return true if this thread is public, false otherwise.
*/
default boolean isPublic()
{
ChannelType type = getType();
return type == ChannelType.GUILD_PUBLIC_THREAD || type == ChannelType.GUILD_NEWS_THREAD;
}
/**
* Gets the current number of messages present in this thread.
*
Threads started from seed messages in the {@link net.dv8tion.jda.api.entities.channel.attribute.IThreadContainer parent channel} will not count that seed message.
*
This will be capped at 50 for threads created before July 1, 2022.
*
* @return The number of messages sent in this thread
*/
int getMessageCount();
/**
* The total number of messages sent in this thread, including all deleted messages.
*
This might be inaccurate for threads created before July 1, 2022.
*
* @return The total number of messages ever sent in this thread
*/
int getTotalMessageCount();
/**
* Gets the current number of members that have joined this thread.
*
This is capped at 50, meaning any additional members will not affect this count.
*
* @return The number of members that have joined this thread, capping at 50.
*/
int getMemberCount();
/**
* Whether the currently logged in member has joined this thread.
*
* @return true if the self member has joined this thread, false otherwise.
*/
default boolean isJoined()
{
return getSelfThreadMember() != null;
}
/**
* Whether this thread is locked or not.
*
*
Locked threads cannot have new messages posted to them, or members join or leave them.
* Threads can only be locked and unlocked by moderators.
*
* @return true if this thread is locked, false otherwise.
*
* @see ChannelField#LOCKED
*/
boolean isLocked();
/**
* Whether this thread is invitable.
*
* A thread that is invitable can have non-moderators invite other non-moderators to it.
* A thread that is not invitable can only have moderators invite others to it.
*
*
This property is exclusive to private threads.
*
* @throws UnsupportedOperationException
* If this thread is not a private thread.
*
* @return true if this thread is invitable, false otherwise.
*
* @see ChannelField#INVITABLE
*/
boolean isInvitable();
/**
* Whether this thread is a pinned forum post.
*
* @return True, if this is a pinned forum post.
*/
default boolean isPinned()
{
return getFlags().contains(ChannelFlag.PINNED);
}
/**
* Gets the {@link IThreadContainer parent channel} of this thread.
*
* @return The parent channel of this thread.
*
* @see IThreadContainer#getThreadChannels()
*/
@Nonnull
IThreadContainerUnion getParentChannel();
/**
* Gets the {@link GuildMessageChannelUnion parent channel} of this thread, if it is a {@link TextChannel}, {@link NewsChannel}, or {@link VoiceChannel}.
*
This is a convenience method that will perform the cast if possible, throwing otherwise.
*
* @throws UnsupportedOperationException
* If the parent channel is not a {@link GuildMessageChannel}.
*
* @return The parent channel of this thread, as a {@link GuildMessageChannelUnion}.
*/
@Nonnull
default GuildMessageChannelUnion getParentMessageChannel()
{
if (getParentChannel() instanceof GuildMessageChannel)
return (GuildMessageChannelUnion) getParentChannel();
throw new UnsupportedOperationException("Parent of this thread is not a MessageChannel. Parent: " + getParentChannel());
}
/**
* The {@link net.dv8tion.jda.api.entities.channel.forums.ForumTag forum tags} applied to this thread.
*
This will be an empty list if the thread was not created in a {@link net.dv8tion.jda.api.entities.channel.concrete.ForumChannel ForumChannel}.
*
* @return Immutable {@link List} of {@link net.dv8tion.jda.api.entities.channel.forums.ForumTag ForumTags} applied to this post
*/
@Nonnull
List getAppliedTags();
/**
* Attempts to get the {@link net.dv8tion.jda.api.entities.Message Message} that this thread was started from.
*
The parent message was posted in the {@link #getParentChannel() parent channel} and a thread was started on it.
*
* The {@link Message#getMember() Message.getMember()} method will always return null for the resulting message.
* To retrieve the member you can use {@code getGuild().retrieveMember(message.getAuthor())}.
*
*
The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or after {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL}
* was revoked in the {@link GuildMessageChannel GuildMessageChannel}
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
*
The request was attempted after the account lost {@link net.dv8tion.jda.api.Permission#MESSAGE_HISTORY Permission.MESSAGE_HISTORY}
* in the {@link GuildMessageChannel GuildMessageChannel}.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
*
The message has already been deleted.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the parent channel was deleted.
*
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If this is a {@link GuildMessageChannel GuildMessageChannel} and the logged in account does not have
*
* - {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL}
* - {@link net.dv8tion.jda.api.Permission#MESSAGE_HISTORY Permission.MESSAGE_HISTORY}
*
* @throws UnsupportedOperationException
* If the parent channel is not a {@link GuildMessageChannel GuildMessageChannel}.
*
* @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: Message
*
The Message that started this thread
*/
@Nonnull
@CheckReturnValue
RestAction retrieveParentMessage();
/**
* Attempts to get the {@link net.dv8tion.jda.api.entities.Message Message} that was posted when this thread was created.
*
Unlike {@link #retrieveParentMessage()}, the message was posted only inside the thread channel.
* This is common for {@link ForumChannel} posts.
*
* The {@link Message#getMember() Message.getMember()} method will always return null for the resulting message.
* To retrieve the member you can use {@code getGuild().retrieveMember(message.getAuthor())}.
*
*
This is equivalent to {@code channel.retrieveMessageById(channel.getId())}.
*
*
The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or after {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL}
* was revoked in the {@link GuildMessageChannel GuildMessageChannel}
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
*
The request was attempted after the account lost {@link net.dv8tion.jda.api.Permission#MESSAGE_HISTORY Permission.MESSAGE_HISTORY}
* in the {@link GuildMessageChannel GuildMessageChannel}.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_MESSAGE UNKNOWN_MESSAGE}
*
The message has already been deleted or there was no starting message.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the parent channel was deleted.
*
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If this is a {@link GuildMessageChannel GuildMessageChannel} and the logged in account does not have
*
* - {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL}
* - {@link net.dv8tion.jda.api.Permission#MESSAGE_HISTORY Permission.MESSAGE_HISTORY}
*
*
* @return {@link net.dv8tion.jda.api.requests.RestAction RestAction} - Type: Message
*/
@Nonnull
@CheckReturnValue
RestAction retrieveStartMessage();
/**
* Gets the self member, as a member of this thread.
*
* If the current account is not a member of this thread, this will return null.
*
* @return The self member of this thread, null if the current account is not a member of this thread.
*
* @see #isJoined()
*/
@Nullable
default ThreadMember getSelfThreadMember()
{
return getThreadMember(getJDA().getSelfUser());
}
/**
* Gets a List of all cached {@link ThreadMember members} of this thread.
*
*
The thread owner is not included in this list, unless the current account is the owner.
* Any updates to this cache are lost when JDA is shutdown, and this list is not sent to JDA on startup.
* For this reason, {@link #retrieveThreadMembers()} should be used instead in most cases.
*
*
The cache this method relies on is empty until JDA sees a member join via a {@link net.dv8tion.jda.api.events.thread.member.ThreadMemberJoinEvent}.
*
If the current account is a member of this ThreadChannel, this cache will contain the current account, even after a restart.
*
In order for this cache to be updated, the following requirements must be met:
*
* - the {@link net.dv8tion.jda.api.requests.GatewayIntent#GUILD_MEMBERS} intent must be enabled.
* - the bot must be able to join the thread (either via the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS MANAGE_THREADS} permission, or a public thread)
* - the bot must have be online to receive the update
*
*
* @return List of all {@link ThreadMember members} of this thread. This list may be empty, but not null.
*
* @see #retrieveThreadMembers()
*/
@Nonnull
List getThreadMembers();
/**
* Gets a {@link ThreadMember} of this thread by their {@link Member}.
*
* Note that this operation relies on the {@link #getThreadMembers() ThreadMember cache} for this ThreadChannel.
* As the cache is likely to be unpopulated, this method is likely to return null.
*
*
Use of {@link #retrieveThreadMember(Member)} is preferred instead, once it is released.
*
* @param member
* The member to get the {@link ThreadMember} for.
*
* @throws IllegalArgumentException
* If the given member is null.
*
* @return The {@link ThreadMember} of this thread for the given member.
*
* @see #retrieveThreadMember(Member)
*/
@Nullable
default ThreadMember getThreadMember(@Nonnull Member member)
{
Checks.notNull(member, "Member");
return getThreadMemberById(member.getId());
}
/**
* Gets a {@link ThreadMember} of this thread by their {@link Member}.
*
*
Note that this operation relies on the {@link #getThreadMembers() ThreadMember cache} for this ThreadChannel.
* As the cache is likely to be unpopulated, this method is likely to return null.
*
*
Use of {@link #retrieveThreadMember(Member)} is preferred instead, once it is released.
*
* @param user
* The user to get the {@link ThreadMember} for.
*
* @throws IllegalArgumentException
* If the given user is null.
*
* @return The {@link ThreadMember} of this thread for the given member.
*
* @see #retrieveThreadMember(Member)
*/
@Nullable
default ThreadMember getThreadMember(@Nonnull User user)
{
Checks.notNull(user, "User");
return getThreadMemberById(user.getId());
}
/**
* Gets a {@link ThreadMember} of this thread by their {@link Member}.
*
*
Note that this operation relies on the {@link #getThreadMembers() ThreadMember cache} for this ThreadChannel.
* As the cache is likely to be unpopulated, this method is likely to return null.
*
*
Use of {@link #retrieveThreadMember(Member)} is preferred instead, once it is released.
*
* @param id
* The ID of the member to get the {@link ThreadMember} for.
*
* @throws IllegalArgumentException
* If the given id is null or empty.
*
* @return The {@link ThreadMember} of this thread for the given member.
*
* @see #retrieveThreadMember(Member)
*/
@Nullable
default ThreadMember getThreadMemberById(@Nonnull String id)
{
return getThreadMemberById(MiscUtil.parseSnowflake(id));
}
/**
* Gets a {@link ThreadMember} of this thread by their {@link Member}.
*
*
Note that this operation relies on the {@link #getThreadMembers() ThreadMember cache} for this ThreadChannel.
* As the cache is likely to be unpopulated, this method is likely to return null.
*
*
Use of {@link #retrieveThreadMember(Member)} is preferred instead, once it is released.
*
* @param id
* The member to get the {@link ThreadMember} for.
*
* @return The {@link ThreadMember} of this thread for the given member.
*
* @see #retrieveThreadMember(Member)
*/
@Nullable
ThreadMember getThreadMemberById(long id);
/**
* Load the thread-member for the specified user.
*
If the thread-member is already loaded it, will be retrieved from {@link #getThreadMemberById(long)}
* and immediately provided if the thread-member information is consistent. If the bot hasn't joined the thread,
* {@link net.dv8tion.jda.api.requests.GatewayIntent#GUILD_MEMBERS GatewayIntent.GUILD_MEMBERS} is required to keep the cache updated.
*
* @param member
* The member to load the thread-member from
*
* @throws IllegalArgumentException
* If provided with null
*
* @return {@link CacheRestAction} - Type: {@link ThreadMember}
*/
@Nonnull
@CheckReturnValue
default CacheRestAction retrieveThreadMember(@Nonnull Member member)
{
Checks.notNull(member, "Member");
return retrieveThreadMemberById(member.getIdLong());
}
/**
* Load the thread-member for the specified user.
*
If the thread-member is already loaded, it will be retrieved from {@link #getThreadMemberById(long)}
* and immediately provided if the thread-member information is consistent. If the bot hasn't joined the thread,
* {@link net.dv8tion.jda.api.requests.GatewayIntent#GUILD_MEMBERS GatewayIntent.GUILD_MEMBERS} is required to keep the cache updated.
*
* @param user
* The user to load the thread-member from
*
* @throws IllegalArgumentException
* If provided with null
*
* @return {@link CacheRestAction} - Type: {@link ThreadMember}
*/
@Nonnull
@CheckReturnValue
default CacheRestAction retrieveThreadMember(@Nonnull User user)
{
Checks.notNull(user, "User");
return retrieveThreadMemberById(user.getIdLong());
}
/**
* Load the thread-member for the user with the specified id.
*
If the thread-member is already loaded, it will be retrieved from {@link #getThreadMemberById(long)}
* and immediately provided if the thread-member information is consistent. If the bot hasn't joined the thread,
* {@link net.dv8tion.jda.api.requests.GatewayIntent#GUILD_MEMBERS GatewayIntent.GUILD_MEMBERS} is required to keep the cache updated.
*
* @param id
* The user id to load the thread-member from
*
* @throws IllegalArgumentException
* If the provided id is empty or null
* @throws NumberFormatException
* If the provided id is not a snowflake
*
* @return {@link CacheRestAction} - Type: {@link ThreadMember}
*/
@Nonnull
@CheckReturnValue
default CacheRestAction retrieveThreadMemberById(@Nonnull String id)
{
return retrieveThreadMemberById(MiscUtil.parseSnowflake(id));
}
/**
* Load the thread-member for the user with the specified id.
*
If the thread-member is already loaded, it will be retrieved from {@link #getThreadMemberById(long)}
* and immediately provided if the thread-member information is consistent. If the bot hasn't joined the thread,
* {@link net.dv8tion.jda.api.requests.GatewayIntent#GUILD_MEMBERS GatewayIntent.GUILD_MEMBERS} is required to keep the cache updated.
*
* @param id
* The user id to load the thread-member from
*
* @return {@link CacheRestAction} - Type: {@link ThreadMember}
*/
@Nonnull
@CheckReturnValue
CacheRestAction retrieveThreadMemberById(long id);
/**
* Retrieves the {@link ThreadMember ThreadMembers} of this thread.
*
* This requires the {@link net.dv8tion.jda.api.requests.GatewayIntent#GUILD_MEMBERS} intent to be enabled
* in the Application Dashboard.
*
* @return {@link ThreadMemberPaginationAction}
*/
@Nonnull
@CheckReturnValue
ThreadMemberPaginationAction retrieveThreadMembers();
/**
* Whether the current account is the owner of this thread.
*
* @return true if the self account is the owner of this thread, false otherwise.
*/
default boolean isOwner()
{
return getJDA().getSelfUser().getIdLong() == getOwnerIdLong();
}
/**
* Gets the ID of the owner of this thread as a long.
*
* @return the ID of the member who created this thread as a long.
*/
long getOwnerIdLong();
/**
* Gets the {@link User} of the owner of this thread as a String.
*
* @return The {@link User} of the member who created this thread as a String.
*/
@Nonnull
default String getOwnerId()
{
return Long.toUnsignedString(getOwnerIdLong());
}
/**
* Gets the {@link Member} that created and owns this thread.
*
This will be null if the member is not cached,
* and so it is recommended to {@link Guild#retrieveMemberById(long) retrieve this member from the guild}
* using {@link #getOwnerIdLong() the owner'd ID}.
*
* @return The {@link Member} of the member who created this thread.
*
* @see #getThreadMemberById(long)
* @see Guild#retrieveMemberById(long)
*/
@Nullable
default Member getOwner()
{
return getGuild().getMemberById(getOwnerIdLong());
}
/**
* Gets the owner of this thread as a {@link ThreadMember}.
*
This will be null if the member is not cached, and so it is recommended to retrieve the owner instead.
*
*
This method relies on the {@link #getThreadMembers()} cache,
* and so it is recommended to {@link #retrieveThreadMemberById(long) retrieve the ThreadMember}
* by {@link #getOwnerIdLong() their ID} instead.
*
* @return The owner of this thread as a {@link ThreadMember}.
*
* @see #getThreadMemberById(long)
*/
@Nullable
default ThreadMember getOwnerThreadMember()
{
return getThreadMemberById(getOwnerIdLong());
}
/**
* Whether this thread has been archived.
*
*
This method will consider locked channels to also be archived.
*
*
Archived threads are not deleted threads, but are considered inactive.
* They are not shown to clients in the channels list, but can still be navigated to and read.
* ThreadChannels may be unarchived as long as there is space for a new active thread.
*
* @return true if this thread has been archived, false otherwise.
*
* @see #isLocked()
* @see ThreadChannelManager#setArchived(boolean)
* @see #getAutoArchiveDuration()
* @see ChannelField#ARCHIVED
*/
boolean isArchived();
/**
* The last time the archive info of this thread was updated.
*
*
This timestamp will be updated when any of the following happen:
*
* - The channel is archived
* - The channel is unarchived
* - The AUTO_ARCHIVE_DURATION is changed.
*
*
* @return the time of the last archive info update.
*
* @see ChannelField#ARCHIVED_TIMESTAMP
*/
@Nonnull
OffsetDateTime getTimeArchiveInfoLastModified();
/**
* The inactivity timeout of this thread.
*
* If a message is not sent within this amount of time, the thread will be automatically hidden.
*
*
A thread archived this way can be unarchived by any member.
*
* @return The inactivity timeframe until a thread is automatically hidden.
*
* @see ChannelField#AUTO_ARCHIVE_DURATION
*/
@Nonnull
AutoArchiveDuration getAutoArchiveDuration();
/**
* The timestamp when this thread was created.
*
This will only be valid for threads created after 2022-01-09.
* Otherwise, this will return the timestamp of creation based on the {@link #getIdLong() thread's id.}
*
* @return The timestamp when this thread was created
*/
@Nonnull
OffsetDateTime getTimeCreated();
/**
* Joins this thread, adding the current account to the member list of this thread.
*
*
Note that joining threads is not a requirement of getting events about the thread.
*
*
This will have no effect if the current account is already a member of this thread.
*
*
The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or after access was lost to this ThreadChannel (either by losing access to the parent of a public ThreadChannel,
* or losing {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS MANAGE_THREADS} to a private channel).
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
*
* @throws IllegalStateException
* If this thread is locked or archived.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
RestAction join();
/**
* Leaves this thread, removing the current account from the member list of this thread.
*
This will have no effect if the current account is not a member of this thread.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
*
* @throws IllegalStateException
* If this thread is locked or archived.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
RestAction leave();
//TODO-v5: re-document this method as permission checks are included in the impl.
//this is probably also affected by private threads that are not invitable
/**
* Adds a member to this thread.
*
This will have no effect if the member is already a member of this thread.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
This can be caused by any of the following:
*
* - The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild},
* typically due to being kicked or removed.
* - The user supplied is not a member of this ThreadChannel's {@link net.dv8tion.jda.api.entities.Guild Guild}
* - The thread is not {@link #isInvitable() invitable}, and the current account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS MANAGE_THREADS} permission.
*
*
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_USER UNKNOWN_USER}
*
The provided User ID does not belong to a user.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#INVALID_FORM_BODY INVALID_FORM_BODY}
*
The provided User ID is not a valid snowflake.
*
*
*
* @param id
* The id of the member to add.
*
* @throws IllegalStateException
* If this thread is locked or archived.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
RestAction addThreadMemberById(long id);
/**
* Adds a member to this thread.
*
*
This will have no effect if the member is already a member of this thread.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
This can be caused by any of the following:
*
* - The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild},
* typically due to being kicked or removed.
* - The user supplied is not a member of this ThreadChannel's {@link net.dv8tion.jda.api.entities.Guild Guild}
* - The thread is not {@link #isInvitable() invitable}, and the current account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS MANAGE_THREADS} permission.
*
*
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_USER UNKNOWN_USER}
*
The provided User ID does not belong to a user.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#INVALID_FORM_BODY INVALID_FORM_BODY}
*
The provided User ID is not a valid snowflake.
*
*
* @param id
* The id of the member to add.
*
* @throws IllegalStateException
* If this thread is locked or archived
* @throws IllegalArgumentException
* If the provided id is not a valid snowflake.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction addThreadMemberById(@Nonnull String id)
{
return addThreadMemberById(MiscUtil.parseSnowflake(id));
}
/**
* Adds a member to this thread.
*
This will have no effect if the member is already a member of this thread.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
This can be caused by any of the following:
*
* - The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild},
* typically due to being kicked or removed.
* - The user supplied is not a member of this ThreadChannel's {@link net.dv8tion.jda.api.entities.Guild Guild}
* - The thread is not {@link #isInvitable() invitable}, and the current account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS MANAGE_THREADS} permission.
*
*
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
*
* @param user
* The {@link User} to add.
*
* @throws IllegalStateException
* If this thread is locked or archived.
* @throws IllegalArgumentException
* If the provided user is null.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction addThreadMember(@Nonnull User user)
{
Checks.notNull(user, "User");
return addThreadMemberById(user.getIdLong());
}
/**
* Adds a member to this thread.
*
This will have no effect if the member is already a member of this thread.
*
* The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
This can be caused by any of the following:
*
* - The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild},
* typically due to being kicked or removed.
* - The user supplied is not a member of this ThreadChannel's {@link net.dv8tion.jda.api.entities.Guild Guild}
* - The thread is not {@link #isInvitable() invitable}, and the current account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS MANAGE_THREADS} permission.
*
*
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
*
* @param member
* The {@link Member} to add.
*
* @throws IllegalStateException
* If this thread is locked or archived.
* @throws IllegalArgumentException
* If the provided member is null.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction addThreadMember(@Nonnull Member member)
{
Checks.notNull(member, "Member");
return addThreadMemberById(member.getIdLong());
}
/**
* Removes a member from this thread.
*
* Removing members from threads requires the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission unless the thread is private and owned by the current account.
*
*
The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or the bot losing permissions to perform this action.
*
This can also be caused if the user supplied is not a member of this ThreadChannel's {@link net.dv8tion.jda.api.entities.Guild Guild}
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_USER UNKNOWN_USER}
*
The provided User ID does not belong to a user.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#INVALID_FORM_BODY INVALID_FORM_BODY}
*
The provided User ID is not a valid snowflake.
*
*
*
* @param id
* The id of the member to remove from this thread.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission,
* and this is not a private thread channel this account owns.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
RestAction removeThreadMemberById(long id);
/**
* Removes a member from this thread.
*
* Removing members from threads requires the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission unless the thread is private and owned by the current account.
*
*
The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or the bot losing permissions to perform this action.
*
This can also be caused if the user supplied is not a member of this ThreadChannel's {@link net.dv8tion.jda.api.entities.Guild Guild}
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_USER UNKNOWN_USER}
*
The provided User ID does not belong to a user.
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#INVALID_FORM_BODY INVALID_FORM_BODY}
*
The provided User ID is not a valid snowflake.
*
*
*
* @param id
* The id of the member to remove from this thread.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission,
* and this is not a private thread channel this account owns.
* @throws IllegalArgumentException
* If the provided id is not a valid snowflake.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction removeThreadMemberById(@Nonnull String id)
{
return removeThreadMemberById(MiscUtil.parseSnowflake(id));
}
/**
* Removes a member from this thread.
*
* Removing members from threads requires the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission unless the thread is private and owned by the current account.
*
*
The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or the bot losing permissions to perform this action.
*
This can also be caused if the user supplied is not a member of this ThreadChannel's {@link net.dv8tion.jda.api.entities.Guild Guild}
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
*
*
* @param user
* The user to remove from this thread.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission,
* and this is not a private thread channel this account owns.
* @throws IllegalArgumentException
* If the provided user is null.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction removeThreadMember(@Nonnull User user)
{
Checks.notNull(user, "User");
return removeThreadMemberById(user.getId());
}
/**
* Removes a member from this thread.
* Removing members from threads requires the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission unless the thread is private and owned by the current account.
*
*
The following {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} are possible:
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
*
The request was attempted after the account lost access to the {@link net.dv8tion.jda.api.entities.Guild Guild}
* typically due to being kicked or removed, or the bot losing permissions to perform this action.
*
This can also be caused if the member supplied is not a member of this ThreadChannel's {@link net.dv8tion.jda.api.entities.Guild Guild}
*
* - {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
*
The request was attempted after the channel was deleted.
*
*
*
* Removing members from public threads or private threads this account does not own requires the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission.
*
* @param member
* The member to remove from this thread.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_THREADS} permission, and this isn't a private thread channel this account owns.
* @throws IllegalArgumentException
* If the provided member is null.
*
* @return {@link RestAction}
*/
@Nonnull
@CheckReturnValue
default RestAction removeThreadMember(@Nonnull Member member)
{
Checks.notNull(member, "Member");
return removeThreadMemberById(member.getIdLong());
}
@Override
@Nonnull
ThreadChannelManager getManager();
@Override
default void formatTo(Formatter formatter, int flags, int width, int precision)
{
boolean leftJustified = (flags & FormattableFlags.LEFT_JUSTIFY) == FormattableFlags.LEFT_JUSTIFY;
boolean upper = (flags & FormattableFlags.UPPERCASE) == FormattableFlags.UPPERCASE;
boolean alt = (flags & FormattableFlags.ALTERNATE) == FormattableFlags.ALTERNATE;
String out;
if (alt)
out = "#" + (upper ? getName().toUpperCase(formatter.locale()) : getName());
else
out = getAsMention();
MiscUtil.appendTo(formatter, width, precision, leftJustified, out);
}
/**
* The values permitted for the auto archive duration of a {@link ThreadChannel}.
*
* This is the time before an idle thread will be automatically hidden.
*
*
Sending a message to the thread will reset the timer.
*
* @see ChannelField#AUTO_ARCHIVE_DURATION
*/
enum AutoArchiveDuration
{
TIME_1_HOUR(60),
TIME_24_HOURS(1440),
TIME_3_DAYS(4320),
TIME_1_WEEK(10080);
private final int minutes;
AutoArchiveDuration(int minutes)
{
this.minutes = minutes;
}
/**
* The number of minutes before an idle thread will be automatically hidden.
*
* @return The number of minutes
*/
public int getMinutes()
{
return minutes;
}
/**
* Provides the corresponding enum constant for the provided number of minutes.
*
* @param minutes
* The number of minutes. (must be one of the valid values)
*
* @throws IllegalArgumentException
* If the provided minutes is not a valid value.
*
* @return The corresponding enum constant.
*/
@Nonnull
public static AutoArchiveDuration fromKey(int minutes)
{
for (AutoArchiveDuration duration : values())
{
if (duration.getMinutes() == minutes)
return duration;
}
throw new IllegalArgumentException("Provided key was not recognized. Minutes: " + minutes);
}
}
}