Class Message.Attachment

java.lang.Object
net.dv8tion.jda.api.entities.Message.Attachment
All Implemented Interfaces:
Closeable, AutoCloseable, ISnowflake, AttachedFile
Enclosing interface:
Message

public static class Message.Attachment extends Object implements ISnowflake, AttachedFile
Represents a Message file attachment.
  • Constructor Details

    • Attachment

      public Attachment(long id, String url, String proxyUrl, String fileName, String contentType, String description, int size, int height, int width, boolean ephemeral, String waveform, double duration, net.dv8tion.jda.internal.JDAImpl jda)
  • Method Details

    • getJDA

      @Nonnull public JDA getJDA()
      The corresponding JDA instance for this Attachment
      Returns:
      The corresponding JDA instance for this Attachment
    • getIdLong

      public long getIdLong()
      Description copied from interface: ISnowflake
      The Snowflake id of this entity. This is unique to every entity and will never change.
      Specified by:
      getIdLong in interface ISnowflake
      Returns:
      Long containing the Id.
    • getUrl

      @Nonnull public String getUrl()
      The url of the Attachment, most likely on the Discord servers.
      Returns:
      Non-null String containing the Attachment URL.
    • getProxyUrl

      @Nonnull public String getProxyUrl()
      Url to the resource proxied by the Discord CDN.
      Returns:
      Non-null String containing the proxied Attachment url.
    • getProxy

      @Nonnull public AttachmentProxy getProxy()
      Returns an AttachmentProxy for this attachment.
      Returns:
      Non-null AttachmentProxy of this attachment
      See Also:
    • getFileName

      @Nonnull public String getFileName()
      The file name of the Attachment when it was first uploaded.
      Returns:
      Non-null String containing the Attachment file name.
    • getFileExtension

      @Nullable public String getFileExtension()
      The file extension of the Attachment when it was first uploaded.
      Null is returned if no characters follow the last occurrence of the '.' character (or if the character is not present in getFileName()).
      Returns:
      Non-null String containing the Attachment file extension, or null if it can't be determined.
    • getContentType

      @Nullable public String getContentType()
      The Content-Type of this file.
      This is the Media type of the file that would be used in an HTTP request or similar.
      Returns:
      The content-type, or null if this isn't provided
    • getDescription

      @Nullable public String getDescription()
      The description (alt text) of this attachment.
      This description is shown when hovering over the attachment in the client.
      Returns:
      The description, or null if this isn't provided
    • retrieveInputStream

      @Nonnull @Deprecated @ForRemoval @ReplaceWith("getProxy().download()") public CompletableFuture<InputStream> retrieveInputStream()
      Deprecated.
      Enqueues a request to retrieve the contents of this Attachment.
      The receiver is expected to close the retrieved InputStream.

      Example

      
       public void printContents(Message.Attachment attachment)
       {
           attachment.retrieveInputStream().thenAccept(in -> {
               StringBuilder builder = new StringBuilder();
               byte[] buf = byte[1024];
               int count = 0;
               while ((count = in.read(buf)) > 0)
               {
                   builder.append(new String(buf, 0, count));
               }
               in.close();
               System.out.println(builder);
           }).exceptionally(t -> { // handle failure
               t.printStackTrace();
               return null;
           });
       }
       
      Returns:
      CompletableFuture - Type: InputStream
    • downloadToFile

      @Nonnull @Deprecated @ForRemoval @ReplaceWith("getProxy().downloadToFile()") public CompletableFuture<File> downloadToFile()
      Deprecated.
      Downloads the attachment into the current working directory using the file name provided by getFileName().
      This will download the file using the callback pool. Alternatively you can use retrieveInputStream() and use a continuation with a different executor.

      Example

      
       public void saveLocally(Message.Attachment attachment)
       {
           attachment.downloadToFile()
               .thenAccept(file -> System.out.println("Saved attachment to " + file.getName()))
               .exceptionally(t ->
               { // handle failure
                   t.printStackTrace();
                   return null;
               });
       }
       
      Returns:
      CompletableFuture - Type: File
    • downloadToFile

      @Nonnull @Deprecated @ForRemoval @ReplaceWith("getProxy().downloadToFile(new File(String))") public CompletableFuture<File> downloadToFile(String path)
      Deprecated.
      Downloads the attachment to a file at the specified path (relative or absolute).
      This will download the file using the callback pool. Alternatively you can use retrieveInputStream() and use a continuation with a different executor.

      Example

      
       public void saveLocally(Message.Attachment attachment)
       {
           attachment.downloadToFile("/tmp/" + attachment.getFileName())
               .thenAccept(file -> System.out.println("Saved attachment to " + file.getName()))
               .exceptionally(t ->
               { // handle failure
                   t.printStackTrace();
                   return null;
               });
       }
       
      Parameters:
      path - The path to save the file to
      Returns:
      CompletableFuture - Type: File
      Throws:
      IllegalArgumentException - If the provided path is null
    • downloadToFile

      @Nonnull @ForRemoval @ReplaceWith("getProxy().downloadToFile(File)") public CompletableFuture<File> downloadToFile(File file)
      Deprecated.
      Downloads the attachment to a file at the specified path (relative or absolute).
      This will download the file using the callback pool. Alternatively you can use retrieveInputStream() and use a continuation with a different executor.

      Example

      
       public void saveLocally(Message.Attachment attachment)
       {
           attachment.downloadToFile(new File("/tmp/" + attachment.getFileName()))
               .thenAccept(file -> System.out.println("Saved attachment to " + file.getName()))
               .exceptionally(t ->
               { // handle failure
                   t.printStackTrace();
                   return null;
               });
       }
       
      Parameters:
      file - The file to write to
      Returns:
      CompletableFuture - Type: File
      Throws:
      IllegalArgumentException - If the provided file is null or cannot be written to
    • retrieveAsIcon

      @Nonnull @ReplaceWith("getProxy().downloadAsIcon()") public CompletableFuture<Icon> retrieveAsIcon()
      Deprecated.
      Retrieves the image of this attachment and provides an Icon equivalent.
      Useful with AccountManager.setAvatar(Icon).
      This will download the file using the callback pool. Alternatively you can use retrieveInputStream() and use a continuation with a different executor.

      Example

      
       public void changeAvatar(Message.Attachment attachment)
       {
           attachment.retrieveAsIcon().thenCompose(icon -> {
               SelfUser self = attachment.getJDA().getSelfUser();
               AccountManager manager = self.getManager();
               return manager.setAvatar(icon).submit();
           }).exceptionally(t -> {
               t.printStackTrace();
               return null;
           });
       }
       
      Returns:
      CompletableFuture - Type: Icon
      Throws:
      IllegalStateException - If this is not an image (isImage())
    • getSize

      public int getSize()
      The size of the attachment in bytes.
      Example: if getSize() returns 1024, then the attachment is 1024 bytes, or 1KiB, in size.
      Returns:
      Positive int containing the size of the Attachment.
    • getHeight

      public int getHeight()
      The height of the Attachment if this Attachment is an image/video.
      If this Attachment is neither an image, nor a video, this returns -1.
      Returns:
      int containing image/video Attachment height, or -1 if attachment is neither image nor video.
    • getWidth

      public int getWidth()
      The width of the Attachment if this Attachment is an image/video.
      If this Attachment is neither an image, nor a video, this returns -1.
      Returns:
      int containing image/video Attachment width, or -1 if attachment is neither image nor video.
    • isEphemeral

      public boolean isEphemeral()
      Whether or not this attachment is from an ephemeral Message.
      If this Attachment is ephemeral, it will automatically be removed after 2 weeks. The attachment is guaranteed to be available as long as the message itself exists.
      Returns:
      True if this attachment is from an ephemeral message
    • getWaveform

      @Nullable public byte[] getWaveform()
      Gets the waveform data encoded in this attachment. This is currently only present on voice messages.
      Returns:
      A possibly-null array of integers representing the amplitude of the audio over time. Amplitude is sampled at 10Hz, but the client will decrease this to keep the waveform to at most 256 bytes. The values in this array are unsigned.
    • getDuration

      public double getDuration()
      Gets the duration of this attachment. This is currently only nonzero on voice messages.
      Returns:
      The duration of this attachment's audio in seconds, or 0 if this is not a voice message.
    • isImage

      public boolean isImage()
      Whether or not this attachment is an Image, based on getWidth(), getHeight(), and getFileExtension().
      Returns:
      True if this attachment is an image
    • isVideo

      public boolean isVideo()
      Whether or not this attachment is a video, based on getWidth(), getHeight(), and getFileExtension().
      Returns:
      True if this attachment is a video
    • isSpoiler

      public boolean isSpoiler()
      Whether or not this attachment is marked as spoiler, based on getFileName().
      Returns:
      True if this attachment is marked as spoiler
      Since:
      4.2.1
    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
    • forceClose

      public void forceClose()
      Description copied from interface: AttachedFile
      Forces the underlying resource to be closed, even if the file is already handled by a request.
      Specified by:
      forceClose in interface AttachedFile
    • addPart

      public void addPart(@Nonnull okhttp3.MultipartBody.Builder builder, int index)
      Description copied from interface: AttachedFile
      Used internally to build the multipart request.

      The index can be used as a unique identifier for the multipart name, which is required to be unique by Discord.

      Specified by:
      addPart in interface AttachedFile
      Parameters:
      builder - The MultipartBody.Builder used for the request body
      index - The index of the attachment, ignored for AttachmentUpdate
    • toAttachmentData

      @Nonnull public DataObject toAttachmentData(int index)
      Description copied from interface: AttachedFile
      Used internally to build attachment descriptions for requests.
      This contains the id/index of the attachment, and the name of the file.
      Specified by:
      toAttachmentData in interface AttachedFile
      Parameters:
      index - The reference index (should be same as AttachedFile.addPart(MultipartBody.Builder, int))
      Returns:
      DataObject for the attachment