Class FileUpload
- All Implemented Interfaces:
Closeable,AutoCloseable,AttachedFile
This is used to upload data to discord for various purposes.
The InputStream will be closed on consumption by the request.
You can use close() to close the stream manually.
-
Field Summary
Fields inherited from interface net.dv8tion.jda.api.utils.AttachedFile
MAX_DESCRIPTION_LENGTH -
Method Summary
Modifier and TypeMethodDescriptionvoidaddPart(okhttp3.MultipartBody.Builder builder, int index) Used internally to build the multipart request.Changes the name of this file, to be prefixed asSPOILER_.asVoiceMessage(okhttp3.MediaType mediaType, byte[] waveform, double durationSeconds) Turns this attachment into a voice message with the provided waveform.asVoiceMessage(okhttp3.MediaType mediaType, byte[] waveform, Duration duration) Turns this attachment into a voice message with the provided waveform.voidclose()voidForces the underlying resource to be closed, even if the file is already handled by a request.static FileUploadCreate a newFileUploadfor a byte array.static FileUploadCreate a newFileUploadfor a local file.static FileUploadCreate a newFileUploadfor a local file.static FileUploadfromData(InputStream data, String name) Create a newFileUploadfor an input stream.static FileUploadfromData(Path path, String name, OpenOption... options) Create a newFileUploadfor a local file.static FileUploadfromData(Path path, OpenOption... options) Create a newFileUploadfor a local file.static FileUploadfromSourceSupplier(String name, Supplier<? extends okio.Source> supplier) Creates a FileUpload that sources its data from the supplier.static FileUploadfromStreamSupplier(String name, Supplier<? extends InputStream> supplier) Creates a FileUpload that sources its data from the supplier.getData()TheInputStreamrepresenting the data to upload as a file.The description for the file.getName()The filename for the file.okhttp3.RequestBodygetRequestBody(okhttp3.MediaType type) Creates a re-usable instance ofRequestBodywith the specified content-type.booleanWhether this attachment is a valid voice message attachment.setDescription(String description) Set the file description used as ALT text for screenreaders.Changes the name of this file.toAttachmentData(int index) Used internally to build attachment descriptions for requests.toString()
-
Method Details
-
fromStreamSupplier
@Nonnull public static FileUpload fromStreamSupplier(@Nonnull String name, @Nonnull Supplier<? extends InputStream> supplier) Creates a FileUpload that sources its data from the supplier.
The supplier must return a new stream on every call.The streams are expected to always be at the beginning, when they are taken from the supplier. If the supplier returned the same stream instance, the reader would start at the wrong position when re-attempting a request.
When this supplier factory is used,
getData()will return a new instance on each call. It is the responsibility of the caller to close that stream.- Parameters:
name- The file namesupplier- The resource supplier, which returns a new stream on each call- Returns:
FileUpload- Throws:
IllegalArgumentException- If null is provided or the name is blank
-
fromSourceSupplier
@Nonnull public static FileUpload fromSourceSupplier(@Nonnull String name, @Nonnull Supplier<? extends okio.Source> supplier) Creates a FileUpload that sources its data from the supplier.
The supplier must return a new stream on every call.The streams are expected to always be at the beginning, when they are taken from the supplier. If the supplier returned the same stream instance, the reader would start at the wrong position when re-attempting a request.
When this supplier factory is used,
getData()will return a new instance on each call. It is the responsibility of the caller to close that stream.- Parameters:
name- The file namesupplier- The resource supplier, which returns a newSourceon each call- Returns:
FileUpload- Throws:
IllegalArgumentException- If null is provided or the name is blank
-
fromData
Create a newFileUploadfor an input stream.
This is used to upload data to discord for various purposes.The
InputStreamwill be closed on consumption by the request. You can useclose()to close the stream manually.- Parameters:
data- TheInputStreamto uploadname- The representative name to use for the file- Returns:
FileUpload- Throws:
IllegalArgumentException- If null is provided or the name is empty- See Also:
-
fromData
Create a newFileUploadfor a byte array.
This is used to upload data to discord for various purposes.- Parameters:
data- Thebyte[]to uploadname- The representative name to use for the file- Returns:
FileUpload- Throws:
IllegalArgumentException- If null is provided or the name is empty
-
fromData
Create a newFileUploadfor a local file.
This is used to upload data to discord for various purposes.This opens a
FileInputStream, which will be closed on consumption by the request. You can useclose()to close the stream manually.- Parameters:
file- TheFileto uploadname- The representative name to use for the file- Returns:
FileUpload- Throws:
IllegalArgumentException- If null is provided or the name is emptyUncheckedIOException- If an IOException is thrown while opening the file- See Also:
-
fromData
Create a newFileUploadfor a local file.
This is used to upload data to discord for various purposes.This opens a
FileInputStream, which will be closed on consumption by the request. You can useclose()to close the stream manually.- Parameters:
file- TheFileto upload- Returns:
FileUpload- Throws:
IllegalArgumentException- If null is providedUncheckedIOException- If an IOException is thrown while opening the file- See Also:
-
fromData
@Nonnull public static FileUpload fromData(@Nonnull Path path, @Nonnull String name, @Nonnull OpenOption... options) Create a newFileUploadfor a local file.
This is used to upload data to discord for various purposes.This opens the path using
Files.newInputStream(Path, OpenOption...), which will be closed on consumption by the request. You can useclose()to close the stream manually.- Parameters:
path- ThePathof the file to uploadname- The representative name to use for the fileoptions- TheOpenOptionsspecifying how the file is opened- Returns:
FileUpload- Throws:
IllegalArgumentException- If null is provided or the name is emptyUncheckedIOException- If an IOException is thrown while opening the file
-
fromData
Create a newFileUploadfor a local file.
This is used to upload data to discord for various purposes. UsesPath.getFileName()to specify the name of the file, to customize the filename usefromData(Path, String, OpenOption...).This opens the path using
Files.newInputStream(Path, OpenOption...), which will be closed on consumption by the request. You can useclose()to close the stream manually.- Parameters:
path- ThePathof the file to uploadoptions- TheOpenOptionsspecifying how the file is opened- Returns:
FileUpload- Throws:
IllegalArgumentException- If null is providedUncheckedIOException- If an IOException is thrown while opening the file
-
asSpoiler
Changes the name of this file, to be prefixed asSPOILER_.
This will cause the file to be rendered as a spoiler attachment in the client.- Returns:
- The updated FileUpload instance
-
setName
Changes the name of this file.- Parameters:
name- The new filename- Returns:
- The updated FileUpload instance
- Throws:
IllegalArgumentException- If the name is null, blank, or empty
-
setDescription
Set the file description used as ALT text for screenreaders.- Parameters:
description- The alt text describing this file attachment (up to 1024 characters)- Returns:
- The same FileUpload instance with the new description
- Throws:
IllegalArgumentException- If the description is longer than 1024 characters
-
asVoiceMessage
@Nonnull public FileUpload asVoiceMessage(@Nonnull okhttp3.MediaType mediaType, @Nonnull byte[] waveform, @Nonnull Duration duration) Turns this attachment into a voice message with the provided waveform.- Parameters:
mediaType- The audio type for the attached audio file. Should beaudio/oggor similar.waveform- The waveform of the audio, which is a low frequency sampling up to 256 bytes.duration- The actual duration of the audio data.- Returns:
- The same FileUpload instance configured as a voice message attachment
- Throws:
IllegalArgumentException- If null is provided or the waveform is not between 1 and 256 bytes long.
-
asVoiceMessage
@Nonnull public FileUpload asVoiceMessage(@Nonnull okhttp3.MediaType mediaType, @Nonnull byte[] waveform, double durationSeconds) Turns this attachment into a voice message with the provided waveform.- Parameters:
mediaType- The audio type for the attached audio file. Should beaudio/oggor similar.waveform- The waveform of the audio, which is a low frequency sampling up to 256 bytes.durationSeconds- The actual duration of the audio data in seconds.- Returns:
- The same FileUpload instance configured as a voice message attachment
- Throws:
IllegalArgumentException- If null is provided or the waveform is not between 1 and 256 bytes long.
-
isVoiceMessage
public boolean isVoiceMessage()Whether this attachment is a valid voice message attachment.- Returns:
- True, if this is a voice message attachment.
-
getName
The filename for the file.- Returns:
- The filename
-
getDescription
The description for the file.- Returns:
- The description
-
getData
TheInputStreamrepresenting the data to upload as a file.- Returns:
- The
InputStream
-
getRequestBody
Creates a re-usable instance ofRequestBodywith the specified content-type.This body will automatically close the
resourcewhen the request is done. However, since the body buffers the data, it can be used multiple times regardless.- Parameters:
type- The content-type to use for the body (e.g."application/octet-stream")- Returns:
RequestBody- Throws:
IllegalArgumentException- If the content-type is null
-
addPart
Description copied from interface:AttachedFileUsed 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:
addPartin interfaceAttachedFile- Parameters:
builder- TheMultipartBody.Builderused for the request bodyindex- The index of the attachment, ignored forAttachmentUpdate
-
toAttachmentData
Description copied from interface:AttachedFileUsed internally to build attachment descriptions for requests.
This contains the id/index of the attachment, and the name of the file.- Specified by:
toAttachmentDatain interfaceAttachedFile- Parameters:
index- The reference index (should be same asAttachedFile.addPart(MultipartBody.Builder, int))- Returns:
DataObjectfor the attachment
-
close
- Specified by:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable- Throws:
IOException
-
forceClose
Description copied from interface:AttachedFileForces the underlying resource to be closed, even if the file is already handled by a request.- Specified by:
forceClosein interfaceAttachedFile- Throws:
IOException- If an IOException is thrown while closing the resource
-
toString
-