net.dv8tion.jda.api.interactions.callbacks.IMessageEditCallback 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.interactions.callbacks;
import net.dv8tion.jda.api.entities.Message;
import net.dv8tion.jda.api.entities.MessageEmbed;
import net.dv8tion.jda.api.interactions.InteractionHook;
import net.dv8tion.jda.api.interactions.components.ActionRow;
import net.dv8tion.jda.api.interactions.components.LayoutComponent;
import net.dv8tion.jda.api.requests.RestAction;
import net.dv8tion.jda.api.requests.restaction.interactions.MessageEditCallbackAction;
import net.dv8tion.jda.api.utils.AttachedFile;
import net.dv8tion.jda.api.utils.FileUpload;
import net.dv8tion.jda.api.utils.messages.MessageEditData;
import net.dv8tion.jda.internal.requests.restaction.interactions.MessageEditCallbackActionImpl;
import net.dv8tion.jda.internal.utils.Checks;
import javax.annotation.CheckReturnValue;
import javax.annotation.Nonnull;
import java.io.File;
import java.io.InputStream;
import java.util.Arrays;
import java.util.Collection;
import java.util.List;
import java.util.stream.Collectors;
/**
* Interactions which allow a target message to be edited on use.
*
* Editing a message using these methods will automatically acknowledge the interaction.
*
*
Deferred Edits
*
* Similar to {@link IReplyCallback}, message edits can be deferred and performed later with {@link #deferEdit()}.
* A deferred edit tells Discord, that you intend to edit the message this interaction was performed on, but will do so later.
* However, you can defer the edit and never do it, which is effectively a no-operation acknowledgement of the interaction.
*
*
If an edit is {@link #deferEdit() deferred}, it becomes the original message of the interaction hook.
* This means all the methods with {@code original} in the name, such as {@link InteractionHook#editOriginal(String)},
* will affect that original message you edited.
*/
public interface IMessageEditCallback extends IDeferrableCallback
{
/**
* No-op acknowledgement of this interaction.
*
This tells discord you intend to update the message that the triggering component is a part of using the {@link #getHook() InteractionHook} instead of sending a reply message.
* You are not required to actually update the message, this will simply acknowledge that you accepted the interaction.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
Use {@link #editMessage(String)} to edit it directly.
*
* @return {@link MessageEditCallbackAction} that can be used to update the message
*
* @see #editMessage(String)
*/
@Nonnull
@CheckReturnValue
MessageEditCallbackAction deferEdit();
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
*
You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
* @param message
* The new message content to use
*
* @throws IllegalArgumentException
* If the provided message is null
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editMessage(@Nonnull MessageEditData message)
{
Checks.notNull(message, "Message");
MessageEditCallbackActionImpl action = (MessageEditCallbackActionImpl) deferEdit();
return action.applyData(message);
}
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
*
You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
* @param content
* The new message content to use
*
* @throws IllegalArgumentException
* If the provided content is null or longer than {@value Message#MAX_CONTENT_LENGTH} characters
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editMessage(@Nonnull String content)
{
Checks.notNull(content, "Content");
return deferEdit().setContent(content);
}
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
*
You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
* @param components
* The new message components, such as {@link ActionRow}
*
* @throws IllegalArgumentException
*
* - If any of the provided LayoutComponents is null
* - If any of the provided Components are not compatible with messages
* - If more than {@value Message#MAX_COMPONENT_COUNT} component layouts are provided
*
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*
* @see LayoutComponent#isMessageCompatible()
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editComponents(@Nonnull Collection components)
{
Checks.noneNull(components, "Components");
if (components.stream().anyMatch(it -> !(it instanceof ActionRow)))
throw new UnsupportedOperationException("The provided component layout is not supported");
List actionRows = components.stream().map(ActionRow.class::cast).collect(Collectors.toList());
return deferEdit().setComponents(actionRows);
}
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
* You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
* @param components
* The new message components, such as {@link ActionRow}
*
* @throws IllegalArgumentException
*
* - If any of the provided LayoutComponents are null
* - If any of the provided Components are not compatible with messages
* - If more than {@value Message#MAX_COMPONENT_COUNT} component layouts are provided
*
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*
* @see LayoutComponent#isMessageCompatible()
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editComponents(@Nonnull LayoutComponent... components)
{
Checks.noneNull(components, "LayoutComponents");
return editComponents(Arrays.asList(components));
}
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
* You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
* @param embeds
* The new {@link MessageEmbed MessageEmbeds}
*
* @throws IllegalArgumentException
* If null or more than {@value Message#MAX_EMBED_COUNT} embeds are provided
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editMessageEmbeds(@Nonnull Collection embeds)
{
Checks.noneNull(embeds, "MessageEmbed");
return deferEdit().setEmbeds(embeds);
}
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
*
You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
* @param embeds
* The new message embeds to include in the message
*
* @throws IllegalArgumentException
* If null or more than {@value Message#MAX_EMBED_COUNT} embeds are provided
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editMessageEmbeds(@Nonnull MessageEmbed... embeds)
{
Checks.noneNull(embeds, "MessageEmbed");
return deferEdit().setEmbeds(embeds);
}
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
*
You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
* @param format
* The format string for the new message content
* @param args
* The format arguments
*
* @throws IllegalArgumentException
* If the provided format is null
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editMessageFormat(@Nonnull String format, @Nonnull Object... args)
{
Checks.notNull(format, "Format String");
return editMessage(String.format(format, args));
}
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
*
You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
*
Resource Handling Note: Once the request is handed off to the requester, for example when you call {@link RestAction#queue()},
* the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly.
* For instance, if an exception occurs after using {@link FileUpload#fromData(File)}, before calling {@link RestAction#queue()}.
* You can safely use a try-with-resources to handle this, since {@link FileUpload#close()} becomes ineffective once the request is handed off.
*
* @param attachments
* The new attachments of the message (Can be {@link FileUpload FileUploads} or {@link net.dv8tion.jda.api.utils.AttachmentUpdate AttachmentUpdates})
*
* @throws IllegalArgumentException
* If null is provided
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*
* @see AttachedFile#fromAttachment(Message.Attachment)
* @see FileUpload#fromData(InputStream, String)
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editMessageAttachments(@Nonnull Collection attachments)
{
Checks.noneNull(attachments, "Attachments");
return deferEdit().setAttachments(attachments);
}
/**
* Acknowledgement of this interaction with a message update.
*
You can use {@link #getHook()} to edit the message further.
*
*
You can only use deferEdit() or editMessage() once per interaction! Use {@link #getHook()} for any additional updates.
*
*
You only have 3 seconds to acknowledge an interaction!
*
When the acknowledgement is sent after the interaction expired, you will receive {@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_INTERACTION ErrorResponse.UNKNOWN_INTERACTION}.
*
*
Resource Handling Note: Once the request is handed off to the requester, for example when you call {@link RestAction#queue()},
* the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly.
* For instance, if an exception occurs after using {@link FileUpload#fromData(File)}, before calling {@link RestAction#queue()}.
* You can safely use a try-with-resources to handle this, since {@link FileUpload#close()} becomes ineffective once the request is handed off.
*
* @param attachments
* The new attachments of the message (Can be {@link FileUpload FileUploads} or {@link net.dv8tion.jda.api.utils.AttachmentUpdate AttachmentUpdates})
*
* @throws IllegalArgumentException
* If null is provided
*
* @return {@link MessageEditCallbackAction} that can be used to further update the message
*
* @see AttachedFile#fromAttachment(Message.Attachment)
* @see FileUpload#fromData(InputStream, String)
*/
@Nonnull
@CheckReturnValue
default MessageEditCallbackAction editMessageAttachments(@Nonnull AttachedFile... attachments)
{
Checks.noneNull(attachments, "Attachments");
return deferEdit().setAttachments(attachments);
}
}