Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add ImageProxy#downloadAsIcon #2727

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Add ImageProxy#downloadAsIcon #2727

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
56eea3e
Update docs
freya022 Sep 8, 2024
db66d48
Add ImageProxy#downloadAsIcon
freya022 Sep 8, 2024
7b27d1a
Revert: size -> width
freya022 Oct 5, 2024
7617b66
Add link to Discord's image formatting details
freya022 Oct 5, 2024
591fb53
Add missing CheckReturnValue
freya022 Oct 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 7 additions & 20 deletions src/main/java/net/dv8tion/jda/api/utils/AttachmentProxy.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -60,6 +58,13 @@ public AttachmentProxy(@Nonnull String url)
* @param height
* The height of the image
*
* @throws IllegalArgumentException
* If any of the follow checks are true
* <ul>
* <li>The requested width is negative or 0</li>
* <li>The requested height is negative or 0</li>
* </ul>
*
* @return URL of the attachment with the specified width and height
*/
@Nonnull
Expand Down Expand Up @@ -204,24 +209,6 @@ public CompletableFuture<Path> downloadToPath(@Nonnull Path path, int width, int
return downloadToPath(getUrl(width, height), path);
}

@Nonnull
@CheckReturnValue
private CompletableFuture<Icon> downloadAsIcon(String url)
{
final CompletableFuture<InputStream> 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.
*
Expand Down
19 changes: 19 additions & 0 deletions src/main/java/net/dv8tion/jda/api/utils/FileProxy.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -184,6 +185,24 @@ private DownloadTask downloadInternal(String url)
return new DownloadTask(newCall, future);
}

@Nonnull
@CheckReturnValue
protected CompletableFuture<Icon> downloadAsIcon(String url)
{
final CompletableFuture<InputStream> 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<Path> downloadToPath(String url)
Expand Down
63 changes: 56 additions & 7 deletions src/main/java/net/dv8tion/jda/api/utils/ImageProxy.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -30,7 +31,9 @@

/**
* A utility class to retrieve images.
* <br>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).
* <br>This supports downloading the images from the normal URL, as well as downloading the image with a specific size.
*
* @see <a href="https://discord.com/developers/docs/reference#image-formatting" target="_blank">Discord docs on image formatting</a>
*/
public class ImageProxy extends FileProxy
{
Expand All @@ -55,6 +58,9 @@ public ImageProxy(@Nonnull String url)
* @param size
* The size of the image
*
* @throws IllegalArgumentException
* If the requested size is negative or 0
*
* @return URL of the image with the specified size
*/
@Nonnull
Expand All @@ -67,7 +73,8 @@ public String getUrl(int size)

/**
* Retrieves the {@link InputStream} of this image at the specified size.
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>, so numbers like 128, 256, 512..., 100 might also be a valid size.
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>,
* so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.
*
* <p>If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.
*
Expand All @@ -84,16 +91,18 @@ public CompletableFuture<InputStream> 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).
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>, 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).
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>,
* so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.
*
* <p>If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.
*
* <p><b>Implementation note:</b>
* 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 size of this image, must be positive
*
* @throws IllegalArgumentException
* If any of the follow checks are true
Expand All @@ -113,7 +122,8 @@ public CompletableFuture<Path> downloadToPath(int size)

/**
* Downloads the data of this image, at the specified size, and stores it in the specified file.
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>, so numbers like 128, 256, 512..., 100 might also be a valid size.
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>,
* so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.
*
* <p>If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.
*
Expand All @@ -122,6 +132,8 @@ public CompletableFuture<Path> downloadToPath(int size)
*
* @param file
* The file in which to download the image
* @param size
* The size of this image, must be positive
*
* @throws IllegalArgumentException
* If any of the follow checks are true
Expand All @@ -147,7 +159,8 @@ 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.
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>, so numbers like 128, 256, 512..., 100 might also be a valid size.
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>,
* so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.
*
* <p>If the image is not of a valid size, the CompletableFuture will hold an exception since the HTTP request would have returned a 404.
*
Expand All @@ -157,6 +170,8 @@ public CompletableFuture<File> downloadToFile(@Nonnull File file, int size)
*
* @param path
* The file in which to download the image
* @param size
* The size of this image, must be positive
*
* @throws IllegalArgumentException
* If any of the follow checks are true
Expand All @@ -178,4 +193,38 @@ public CompletableFuture<Path> 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
@CheckReturnValue
public CompletableFuture<Icon> downloadAsIcon()
{
return downloadAsIcon(getUrl());
}

/**
* Downloads the data of this image, at the specified size, and constructs an {@link Icon} from the data.
* <br><b>The image may not be resized at any size, usually Discord only allows for a few powers of 2</b>,
* so numbers like 128, 256, 512..., 100 and 600 might also be valid sizes.
*
* <p>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, must be positive
*
* @throws IllegalArgumentException
* If the requested size is negative or 0
*
* @return {@link CompletableFuture} which holds an {@link Icon}.
*/
@Nonnull
@CheckReturnValue
public CompletableFuture<Icon> downloadAsIcon(int size)
{
return downloadAsIcon(getUrl(size));
}
}