Package net.dv8tion.jda.api.utils.messages

Interface MessageEditRequest<R extends MessageEditRequest<R>>

Type Parameters:
R - The return type for method chaining convenience
All Superinterfaces:
MessageData, MessageRequest<R>
All Known Subinterfaces:
MessageEditAction, MessageEditCallbackAction, WebhookMessageEditAction<T>
All Known Implementing Classes:
MessageEditBuilder
public interface MessageEditRequest<R extends MessageEditRequest<R>> extends MessageRequest<R>
Specialized abstraction of setters for editing existing messages throughout the API.
See Also:

  • Method Details

    • setAttachments

      @Nonnull R setAttachments(@Nullable Collection<? extends AttachedFile> attachments)
      The AttachedFiles that should be attached to the message.
      This will replace all the existing attachments on the message, you can use Collections.emptyList() or null to clear all attachments.

      Resource Handling Note: Once the request is handed off to the requester, for example when you call 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 FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

      Example

      
 // Here "message" is an instance of the Message interface

 // Creates a list of the currently attached files of the message, important to get the generic parameter of the list right
 List<AttachedFile> attachments = new ArrayList<>(message.getAttachments());

 // The name here will be "cat.png" to discord, what the file is called on your computer is irrelevant and only used to read the data of the image.
 FileUpload file = FileUpload.fromData(new File("mycat-final-copy.png"), "cat.png"); // Opens the file called "cat.png" and provides the data used for sending

 // Adds another file to upload in addition the current attachments of the message
 attachments.add(file);

 message.editMessage("New content")
        .setAttachments(attachments)
        .queue();
      Parameters:
      attachments - The AttachedFiles to attach to the message, null or an empty list will set the attachments to an empty list and remove them from the message
      Returns:
      The same instance for chaining
      Throws:
      IllegalArgumentException - If null is provided inside the collection
      See Also:

    • setAttachments

      @Nonnull default R setAttachments(@Nonnull AttachedFile... attachments)
      The AttachedFiles that should be attached to the message.
      This will replace all the existing attachments on the message, you can use new FileAttachment[0] to clear all attachments.

      Resource Handling Note: Once the request is handed off to the requester, for example when you call 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 FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

      Example

      
 // Here "message" is an instance of the Message interface

 // Take the first attachment of the message, all others will be removed
 AttachedFile attachment = message.getAttachments().get(0);

 // The name here will be "cat.png" to discord, what the file is called on your computer is irrelevant and only used to read the data of the image.
 FileUpload file = FileUpload.fromData(new File("mycat-final-copy.png"), "cat.png"); // Opens the file called "cat.png" and provides the data used for sending

 // Edit request to keep the first attachment, and add one more file to the message
 message.editMessage("New content")
        .setAttachments(attachment, file)
        .queue();
      Parameters:
      attachments - The AttachedFiles to attach to the message, null or an empty array will set the attachments to an empty list and remove them from the message
      Returns:
      The same instance for chaining
      Throws:
      IllegalArgumentException - If null is provided
      See Also:

    • setFiles

      @Nonnull default R setFiles(@Nullable Collection<? extends FileUpload> files)
      Description copied from interface: MessageRequest
      The FileUploads that should be attached to the message.
      This will replace all the existing attachments on the message, if this is an edit request. You can use setAttachments(Collection) to keep existing attachments, instead of this method.

      Resource Handling Note: Once the request is handed off to the requester, for example when you call 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 FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

      Example
      Create an embed with a custom image, uploaded alongside the message: 

      
 MessageEmbed embed = new EmbedBuilder()
         .setDescription("Image of a cute cat")
         .setImage("attachment://cat.png") // here "cat.png" is the name used in the FileUpload.fromData factory method
         .build();

 // The name here will be "cat.png" to discord, what the file is called on your computer is irrelevant and only used to read the data of the image.
 FileUpload file = FileUpload.fromData(new File("mycat-final-copy.png"), "cat.png"); // Opens the file called "cat.png" and provides the data used for sending

 channel.sendMessageEmbeds(embed)
        .setFiles(file)
        .queue();
      Specified by:
      setFiles in interface MessageRequest<R extends MessageEditRequest<R>>
      Parameters:
      files - The FileUploads to attach to the message, null or an empty list will set the attachments to an empty list and remove them from the message
      Returns:
      The same instance for chaining

    • setReplace

      @Nonnull R setReplace(boolean isReplace)
      Whether to replace the existing message completely.

      By default, edit requests will only update the message fields which were explicitly set. Changing this to true, will instead replace everything and remove all unset fields.

      Example Default
      A request such as this will only edit the content of the message, and leave any existing embeds or attachments intact. 

      
 message.editMessage("hello").queue();

      Example Replace
      A request such as this will replace the entire message, and remove any existing embeds, attachments, components, etc. 

      
 message.editMessage("hello").setReplace(true).queue();
      Parameters:
      isReplace - True, if only things explicitly set on this request should be present after the message is edited.
      Returns:
      The same message edit request builder

    • isReplace

      boolean isReplace()
      Whether this request will replace the message and remove everything that is not currently set.

      If this is false, the request will only edit the message fields which were explicitly set.

      Returns:
      True, if this is a replacing request
      See Also:

    • applyData

      @Nonnull R applyData(@Nonnull MessageEditData data)
      Applies the provided MessageEditData to this request.

      Note that this method will only call the setters which were also configured when building the message edit data instance, unless it was set to replace.

      Parameters:
      data - The message edit data to apply
      Returns:
      The same instance for chaining
      Throws:
      IllegalArgumentException - If the data is null

    • applyCreateData

      @Nonnull default R applyCreateData(@Nonnull MessageCreateData data)
      Replaces all the fields configured on this request with the data provided by MessageCreateData.
      This will make this request a replace request.
      Parameters:
      data - The message create data to apply
      Returns:
      The same instance for chaining
      Throws:
      IllegalArgumentException - If the data is null

    • applyMessage

      @Nonnull default R applyMessage(@Nonnull Message message)
      Description copied from interface: MessageRequest
      Applies all the data of the provided Message and attempts to copy it.
      This cannot copy the file attachments of the message, they must be manually downloaded and provided to MessageRequest.setFiles(FileUpload...).
      The allowed mentions are not updated to reflect the provided message, and might mention users that the message did not.

      For edit requests, this will set setReplace(boolean) to true, and replace the existing message completely.

      Specified by:
      applyMessage in interface MessageRequest<R extends MessageEditRequest<R>>
      Parameters:
      message - The message to copy the data from
      Returns:
      The same instance for chaining