Package net.dv8tion.jda.api.utils

Class ImageProxy

java.lang.Object
net.dv8tion.jda.api.utils.FileProxy
net.dv8tion.jda.api.utils.ImageProxy
public class ImageProxy extends FileProxy
A utility class to retrieve images.
This supports downloading the images from the normal URL, as well as downloading the image with a specific size.
See Also:

  • Constructor Details

  • Method Details

    • withClient

      @Nonnull public ImageProxy withClient(@Nonnull okhttp3.OkHttpClient customHttpClient)
      Description copied from class: FileProxy
      Sets the custom OkHttpClient used by this instance, regardless of if FileProxy.setDefaultHttpClient(OkHttpClient) has been used or not.
      Overrides:
      withClient in class FileProxy
      Parameters:
      customHttpClient - The custom OkHttpClient to use while making HTTP requests
      Returns:
      This proxy for chaining convenience.

    • getUrl

      @Nonnull public String getUrl(int size)
      Returns the image URL for the specified size.
      The size is a best-effort resize from Discord, with recommended size values as powers of 2 such as 1024 or 512.
      Parameters:
      size - The size of the image
      Returns:
      URL of the image with the specified size
      Throws:
      IllegalArgumentException - If the requested size is negative or 0

    • download

      @Nonnull @CheckReturnValue public CompletableFuture<InputStream> download(int size)
      Retrieves the InputStream of this image at the specified size.
      The image may not be resized at any size, usually Discord only allows for a few powers of 2, so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.

      If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.

      Parameters:
      size - The size of this image
      Returns:
      CompletableFuture which holds an InputStream, the InputStream must be closed manually.

    • downloadToPath

      @Nonnull @CheckReturnValue public CompletableFuture<Path> downloadToPath(int size)
      Downloads the data of this image, at the specified size, and stores it in a file with the same name as the queried file name (this would be the last segment of the URL).
      The image may not be resized at any size, usually Discord only allows for a few powers of 2, so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.

      If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.

      Implementation note: The file is first downloaded into a temporary file, the file is then moved to its real destination when the download is complete.

      Parameters:
      size - The size of this image, must be positive
      Returns:
      CompletableFuture which holds a Path which corresponds to the location the file has been downloaded.
      Throws:
      IllegalArgumentException - If any of the follow checks are true
      • The requested size is negative or 0
      • The URL's scheme is neither http or https

    • downloadToFile

      @Nonnull @CheckReturnValue public CompletableFuture<File> downloadToFile(@Nonnull File file, int size)
      Downloads the data of this image, at the specified size, and stores it in the specified file.
      The image may not be resized at any size, usually Discord only allows for a few powers of 2, so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.

      If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.

      Implementation note: The file is first downloaded into a temporary file, the file is then moved to its real destination when the download is complete.

      Parameters:
      file - The file in which to download the image
      size - The size of this image, must be positive
      Returns:
      CompletableFuture which holds a File, it is the same as the file passed in the parameters.
      Throws:
      IllegalArgumentException - If any of the follow checks are true
      • The target file is null
      • The parent folder of the target file does not exist
      • The target file exists and is not a regular file
      • The target file exists and is not writable
      • The requested size is negative or 0

    • downloadToPath

      @Nonnull @CheckReturnValue public CompletableFuture<Path> downloadToPath(@Nonnull Path path, int size)
      Downloads the data of this image, at the specified size, and stores it in the specified file.
      The image may not be resized at any size, usually Discord only allows for a few powers of 2, so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.

      If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.

      Implementation note: The file is first downloaded into a temporary file, the file is then moved to its real destination when the download is complete.
      The given path can also target filesystems such as a ZIP filesystem.

      Parameters:
      path - The file in which to download the image
      size - The size of this image, must be positive
      Returns:
      CompletableFuture which holds a Path, it is the same as the path passed in the parameters.
      Throws:
      IllegalArgumentException - If any of the follow checks are true
      • The target path is null
      • The parent folder of the target path does not exist
      • The target path exists and is not a regular file
      • The target path exists and is not writable
      • The requested size is negative or 0

    • downloadAsIcon

      @Nonnull @CheckReturnValue public CompletableFuture<Icon> downloadAsIcon()
      Downloads the data of this attachment, and constructs an Icon from the data.
      Returns:
      CompletableFuture which holds an Icon.

    • downloadAsIcon

      @Nonnull @CheckReturnValue public CompletableFuture<Icon> downloadAsIcon(int size)
      Downloads the data of this image, at the specified size, and constructs an Icon from the data.
      The image may not be resized at any size, usually Discord only allows for a few powers of 2, so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.

      If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.

      Parameters:
      size - The size of this image, must be positive
      Returns:
      CompletableFuture which holds an Icon.
      Throws:
      IllegalArgumentException - If the requested size is negative or 0

    • downloadAsFileUpload

      @Nonnull public FileUpload downloadAsFileUpload(@Nonnull String name, int size)
      Returns a FileUpload which supplies a data stream of this attachment, with the given file name and at the specified size.
      The returned FileUpload can be reused safely, and does not need to be closed.

      The image may not be resized at any size, usually Discord only allows for a few powers of 2, so numbers like 128, 256, 512..., 100 might also be a valid size.

      If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.

      Parameters:
      name - The name of the to-be-uploaded file
      size - The size of this image
      Returns:
      FileUpload from this attachment.
      Throws:
      IllegalArgumentException - If the file name is null or blank