From 56eea3e8beebfb6192ecf9334a5c01e591c1521e Mon Sep 17 00:00:00 2001 From: freya02 <41875020+freya022@users.noreply.github.com> Date: Sun, 8 Sep 2024 12:58:29 +0200 Subject: [PATCH 1/5] Update docs --- .../jda/api/utils/AttachmentProxy.java | 7 +++++ .../net/dv8tion/jda/api/utils/ImageProxy.java | 30 +++++++++++++------ 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java b/src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java index 04420a2283..58b79b022f 100644 --- a/src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java +++ b/src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java @@ -60,6 +60,13 @@ public AttachmentProxy(@Nonnull String url) * @param height * The height of the image * + * @throws IllegalArgumentException + * If any of the follow checks are true + * + * * @return URL of the attachment with the specified width and height */ @Nonnull diff --git a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java index 4261a2e556..4a9e2b0439 100644 --- a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java +++ b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java @@ -30,7 +30,7 @@ /** * 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 (width is the same as the height). + *
This supports downloading the images from the normal URL, as well as downloading the image with a specific width. */ public class ImageProxy extends FileProxy { @@ -53,7 +53,10 @@ public ImageProxy(@Nonnull String url) *
The size is a best-effort resize from Discord, with recommended size values as powers of 2 such as 1024 or 512. * * @param size - * The size of the image + * The width of the image + * + * @throws IllegalArgumentException + * If the requested size is negative or 0 * * @return URL of the image with the specified size */ @@ -67,12 +70,13 @@ public String getUrl(int size) /** * Retrieves the {@link 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 might also be a valid 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. * * @param size - * The size of this image + * The width of this image * * @return {@link CompletableFuture} which holds an {@link InputStream}, the {@link InputStream} must be closed manually. */ @@ -84,8 +88,10 @@ public CompletableFuture download(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 might also be a valid 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. * @@ -93,7 +99,7 @@ public CompletableFuture download(int size) * The file is first downloaded into a temporary file, the file is then moved to its real destination when the download is complete. * * @param size - * The width and height of this image, must be positive + * The width of this image, must be positive * * @throws IllegalArgumentException * If any of the follow checks are true @@ -113,7 +119,8 @@ public CompletableFuture downloadToPath(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 might also be a valid 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. * @@ -122,6 +129,8 @@ public CompletableFuture downloadToPath(int size) * * @param file * The file in which to download the image + * @param size + * The width of this image, must be positive * * @throws IllegalArgumentException * If any of the follow checks are true @@ -147,7 +156,8 @@ public CompletableFuture 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 might also be a valid 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. * @@ -157,6 +167,8 @@ public CompletableFuture downloadToFile(@Nonnull File file, int size) * * @param path * The file in which to download the image + * @param size + * The width of this image, must be positive * * @throws IllegalArgumentException * If any of the follow checks are true From db66d485abe7d01a52e275eaaf7721b77534a038 Mon Sep 17 00:00:00 2001 From: freya02 <41875020+freya022@users.noreply.github.com> Date: Sun, 8 Sep 2024 13:02:17 +0200 Subject: [PATCH 2/5] Add ImageProxy#downloadAsIcon --- .../jda/api/utils/AttachmentProxy.java | 20 ----------- .../net/dv8tion/jda/api/utils/FileProxy.java | 19 +++++++++++ .../net/dv8tion/jda/api/utils/ImageProxy.java | 33 +++++++++++++++++++ 3 files changed, 52 insertions(+), 20 deletions(-) diff --git a/src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java b/src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java index 58b79b022f..807a51f05b 100644 --- a/src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java +++ b/src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java @@ -23,9 +23,7 @@ import javax.annotation.CheckReturnValue; import javax.annotation.Nonnull; import java.io.File; -import java.io.IOException; import java.io.InputStream; -import java.io.UncheckedIOException; import java.nio.file.Files; import java.nio.file.LinkOption; import java.nio.file.Path; @@ -211,24 +209,6 @@ public CompletableFuture downloadToPath(@Nonnull Path path, int width, int return downloadToPath(getUrl(width, height), path); } - @Nonnull - @CheckReturnValue - private CompletableFuture downloadAsIcon(String url) - { - final CompletableFuture downloadFuture = download(url); - return FutureUtil.thenApplyCancellable(downloadFuture, stream -> - { - try (final InputStream ignored = stream) - { - return Icon.from(stream); - } - catch (IOException e) - { - throw new UncheckedIOException(e); - } - }); - } - /** * Downloads the data of this attachment, and constructs an {@link Icon} from the data. * diff --git a/src/main/java/net/dv8tion/jda/api/utils/FileProxy.java b/src/main/java/net/dv8tion/jda/api/utils/FileProxy.java index 78180a13b5..0600a15407 100644 --- a/src/main/java/net/dv8tion/jda/api/utils/FileProxy.java +++ b/src/main/java/net/dv8tion/jda/api/utils/FileProxy.java @@ -15,6 +15,7 @@ */ package net.dv8tion.jda.api.utils; +import net.dv8tion.jda.api.entities.Icon; import net.dv8tion.jda.api.exceptions.HttpException; import net.dv8tion.jda.api.requests.RestConfig; import net.dv8tion.jda.internal.requests.FunctionalCallback; @@ -184,6 +185,24 @@ private DownloadTask downloadInternal(String url) return new DownloadTask(newCall, future); } + @Nonnull + @CheckReturnValue + protected CompletableFuture downloadAsIcon(String url) + { + final CompletableFuture downloadFuture = download(url); + return FutureUtil.thenApplyCancellable(downloadFuture, stream -> + { + try (final InputStream ignored = stream) + { + return Icon.from(stream); + } + catch (IOException e) + { + throw new UncheckedIOException(e); + } + }); + } + @Nonnull @CheckReturnValue protected CompletableFuture downloadToPath(String url) diff --git a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java index 4a9e2b0439..5224b2cce4 100644 --- a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java +++ b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java @@ -15,6 +15,7 @@ */ package net.dv8tion.jda.api.utils; +import net.dv8tion.jda.api.entities.Icon; import net.dv8tion.jda.internal.utils.Checks; import net.dv8tion.jda.internal.utils.FutureUtil; import net.dv8tion.jda.internal.utils.IOUtil; @@ -190,4 +191,36 @@ public CompletableFuture downloadToPath(@Nonnull Path path, int size) return downloadToPath(getUrl(size), path); } + + /** + * Downloads the data of this attachment, and constructs an {@link Icon} from the data. + * + * @return {@link CompletableFuture} which holds an {@link Icon}. + */ + @Nonnull + public CompletableFuture downloadAsIcon() + { + return downloadAsIcon(getUrl()); + } + + /** + * Downloads the data of this image, at the specified size, and constructs an {@link 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. + * + * @param size + * The width of this image, must be positive + * + * @throws IllegalArgumentException + * If the requested size is negative or 0 + * + * @return {@link CompletableFuture} which holds an {@link Icon}. + */ + @Nonnull + public CompletableFuture downloadAsIcon(int size) + { + return downloadAsIcon(getUrl(size)); + } } From 7b27d1aaa464b61c1445ed6616926ab978242d4e Mon Sep 17 00:00:00 2001 From: freya02 <41875020+freya022@users.noreply.github.com> Date: Sat, 5 Oct 2024 19:11:01 +0200 Subject: [PATCH 3/5] Revert: size -> width --- .../java/net/dv8tion/jda/api/utils/ImageProxy.java | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java index 5224b2cce4..bd1c3ca92d 100644 --- a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java +++ b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java @@ -31,7 +31,7 @@ /** * A utility class to retrieve images. - *
This supports downloading the images from the normal URL, as well as downloading the image with a specific width. + *
This supports downloading the images from the normal URL, as well as downloading the image with a specific size. */ public class ImageProxy extends FileProxy { @@ -54,7 +54,7 @@ public ImageProxy(@Nonnull String url) *
The size is a best-effort resize from Discord, with recommended size values as powers of 2 such as 1024 or 512. * * @param size - * The width of the image + * The size of the image * * @throws IllegalArgumentException * If the requested size is negative or 0 @@ -77,7 +77,7 @@ public String getUrl(int 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. * * @param size - * The width of this image + * The size of this image * * @return {@link CompletableFuture} which holds an {@link InputStream}, the {@link InputStream} must be closed manually. */ @@ -100,7 +100,7 @@ public CompletableFuture download(int size) * The file is first downloaded into a temporary file, the file is then moved to its real destination when the download is complete. * * @param size - * The width of this image, must be positive + * The size of this image, must be positive * * @throws IllegalArgumentException * If any of the follow checks are true @@ -131,7 +131,7 @@ public CompletableFuture downloadToPath(int size) * @param file * The file in which to download the image * @param size - * The width of this image, must be positive + * The size of this image, must be positive * * @throws IllegalArgumentException * If any of the follow checks are true @@ -169,7 +169,7 @@ public CompletableFuture downloadToFile(@Nonnull File file, int size) * @param path * The file in which to download the image * @param size - * The width of this image, must be positive + * The size of this image, must be positive * * @throws IllegalArgumentException * If any of the follow checks are true @@ -211,7 +211,7 @@ public CompletableFuture downloadAsIcon() *

If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404. * * @param size - * The width of this image, must be positive + * The size of this image, must be positive * * @throws IllegalArgumentException * If the requested size is negative or 0 From 7617b669ca968133968a3d07ec0086583e261ce0 Mon Sep 17 00:00:00 2001 From: freya02 <41875020+freya022@users.noreply.github.com> Date: Sat, 5 Oct 2024 19:12:46 +0200 Subject: [PATCH 4/5] Add link to Discord's image formatting details --- src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java index bd1c3ca92d..45520a7d35 100644 --- a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java +++ b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java @@ -32,6 +32,8 @@ /** * 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 Discord docs on image formatting */ public class ImageProxy extends FileProxy { From 591fb53dea87c4b1dfc2285e800fa759e7912132 Mon Sep 17 00:00:00 2001 From: freya02 <41875020+freya022@users.noreply.github.com> Date: Sat, 5 Oct 2024 19:41:36 +0200 Subject: [PATCH 5/5] Add missing CheckReturnValue --- src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java index 45520a7d35..5adeae004f 100644 --- a/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java +++ b/src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java @@ -200,6 +200,7 @@ public CompletableFuture downloadToPath(@Nonnull Path path, int size) * @return {@link CompletableFuture} which holds an {@link Icon}. */ @Nonnull + @CheckReturnValue public CompletableFuture downloadAsIcon() { return downloadAsIcon(getUrl()); @@ -221,6 +222,7 @@ public CompletableFuture downloadAsIcon() * @return {@link CompletableFuture} which holds an {@link Icon}. */ @Nonnull + @CheckReturnValue public CompletableFuture downloadAsIcon(int size) { return downloadAsIcon(getUrl(size));