Package net.dv8tion.jda.api.utils

Class FileUpload

java.lang.Object
net.dv8tion.jda.api.utils.FileUpload
All Implemented Interfaces:
Closeable, AutoCloseable, AttachedFile
public class FileUpload extends Object implements Closeable, AttachedFile
Represents a file that is intended to be uploaded to Discord for arbitrary requests.
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.

  • 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 name
      supplier - 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 name
      supplier - The resource supplier, which returns a new Source on each call
      Returns:
      FileUpload
      Throws:
      IllegalArgumentException - If null is provided or the name is blank

    • fromData

      @Nonnull public static FileUpload fromData(@Nonnull InputStream data, @Nonnull String name)
      Create a new FileUpload for an input stream.
      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.

      Parameters:
      data - The InputStream to upload
      name - The representative name to use for the file
      Returns:
      FileUpload
      Throws:
      IllegalArgumentException - If null is provided or the name is empty
      See Also:

    • fromData

      @Nonnull public static FileUpload fromData(@Nonnull byte[] data, @Nonnull String name)
      Create a new FileUpload for a byte array.
      This is used to upload data to discord for various purposes.
      Parameters:
      data - The byte[] to upload
      name - The representative name to use for the file
      Returns:
      FileUpload
      Throws:
      IllegalArgumentException - If null is provided or the name is empty

    • fromData

      @Nonnull public static FileUpload fromData(@Nonnull File file, @Nonnull String name)
      Create a new FileUpload for 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 use close() to close the stream manually.

      Parameters:
      file - The File to upload
      name - The representative name to use for the file
      Returns:
      FileUpload
      Throws:
      IllegalArgumentException - If null is provided or the name is empty
      UncheckedIOException - If an IOException is thrown while opening the file
      See Also:

    • fromData

      @Nonnull public static FileUpload fromData(@Nonnull File file)
      Create a new FileUpload for 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 use close() to close the stream manually.

      Parameters:
      file - The File to upload
      Returns:
      FileUpload
      Throws:
      IllegalArgumentException - If null is provided
      UncheckedIOException - 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 new FileUpload for 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 use close() to close the stream manually.

      Parameters:
      path - The Path of the file to upload
      name - The representative name to use for the file
      options - The OpenOptions specifying how the file is opened
      Returns:
      FileUpload
      Throws:
      IllegalArgumentException - If null is provided or the name is empty
      UncheckedIOException - If an IOException is thrown while opening the file

    • fromData

      @Nonnull public static FileUpload fromData(@Nonnull Path path, @Nonnull OpenOption... options)
      Create a new FileUpload for a local file.
      This is used to upload data to discord for various purposes. Uses Path.getFileName() to specify the name of the file, to customize the filename use fromData(Path, String, OpenOption...).

      This opens the path using Files.newInputStream(Path, OpenOption...), which will be closed on consumption by the request. You can use close() to close the stream manually.

      Parameters:
      path - The Path of the file to upload
      options - The OpenOptions specifying how the file is opened
      Returns:
      FileUpload
      Throws:
      IllegalArgumentException - If null is provided
      UncheckedIOException - If an IOException is thrown while opening the file

    • asSpoiler

      @Nonnull public FileUpload asSpoiler()
      Changes the name of this file, to be prefixed as SPOILER_.
      This will cause the file to be rendered as a spoiler attachment in the client.
      Returns:
      The updated FileUpload instance

    • setName

      @Nonnull public FileUpload setName(@Nonnull String name)
      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

      @Nonnull public FileUpload setDescription(@Nullable String description)
      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 be audio/ogg or 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 be audio/ogg or 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

      @Nonnull public String getName()
      The filename for the file.
      Returns:
      The filename

    • getDescription

      @Nullable public String getDescription()
      The description for the file.
      Returns:
      The description

    • getData

      @Nonnull public InputStream getData()
      The InputStream representing the data to upload as a file.
      Returns:
      The InputStream

    • getRequestBody

      @Nonnull public okhttp3.RequestBody getRequestBody(@Nonnull okhttp3.MediaType type)
      Creates a re-usable instance of RequestBody with the specified content-type.

      This body will automatically close the resource when 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

      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

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • forceClose

      public void forceClose() throws IOException
      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
      Throws:
      IOException - If an IOException is thrown while closing the resource

    • toString

      public String toString()
      Overrides:
      toString in class Object