Interface AttachedFile

All Superinterfaces:
AutoCloseable, Closeable
All Known Implementing Classes:
AttachmentUpdate, FileUpload, Message.Attachment
public interface AttachedFile extends Closeable
Represents files that are attached to requests.

  • Field Details

  • Method Details

    • fromData

      @Nonnull 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 FileUpload.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 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 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 FileUpload.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 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 FileUpload.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 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 FileUpload.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 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 FileUpload.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

    • fromAttachment

      @Nonnull static AttachmentUpdate fromAttachment(long id)
      Creates an AttachmentUpdate with the given attachment id.
      This is primarily used for message edit requests, to specify which attachments to retain in the message after the update.
      Parameters:
      id - The id of the attachment to retain
      Returns:
      AttachmentUpdate

    • fromAttachment

      @Nonnull static AttachmentUpdate fromAttachment(@Nonnull String id)
      Creates an AttachmentUpdate with the given attachment id.
      This is primarily used for message edit requests, to specify which attachments to retain in the message after the update.
      Parameters:
      id - The id of the attachment to retain
      Returns:
      AttachmentUpdate
      Throws:
      IllegalArgumentException - If the id is not a valid snowflake

    • fromAttachment

      @Nonnull static AttachmentUpdate fromAttachment(@Nonnull Message.Attachment attachment)
      Creates an AttachmentUpdate with the given attachment.
      This is primarily used for message edit requests, to specify which attachments to retain in the message after the update.
      Parameters:
      attachment - The attachment to retain
      Returns:
      AttachmentUpdate

    • addPart

      void addPart(@Nonnull okhttp3.MultipartBody.Builder builder, int index)
      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.

      Parameters:
      builder - The MultipartBody.Builder used for the request body
      index - The index of the attachment, ignored for AttachmentUpdate

    • toAttachmentData

      @Nonnull DataObject toAttachmentData(int index)
      Used internally to build attachment descriptions for requests.
      This contains the id/index of the attachment, and the name of the file.
      Parameters:
      index - The reference index (should be same as addPart(MultipartBody.Builder, int))
      Returns:
      DataObject for the attachment

    • createMultipartBody

      @Nonnull static okhttp3.MultipartBody.Builder createMultipartBody(@Nonnull Collection<? extends AttachedFile> files)
      Build a complete request using the provided files and payload data.
      Parameters:
      files - The files to upload/edit
      Returns:
      MultipartBody.Builder
      Throws:
      IllegalArgumentException - If the file list is null

    • createMultipartBody

      @Nonnull static okhttp3.MultipartBody.Builder createMultipartBody(@Nonnull Collection<? extends AttachedFile> files, @Nullable DataObject payloadJson)
      Build a complete request using the provided files and payload data.
      Parameters:
      files - The files to upload/edit
      payloadJson - The payload data to send, null to not add a payload_json part
      Returns:
      MultipartBody.Builder
      Throws:
      IllegalArgumentException - If the file list is null

    • createMultipartBody

      @Nonnull static okhttp3.MultipartBody.Builder createMultipartBody(@Nonnull Collection<? extends AttachedFile> files, @Nullable okhttp3.RequestBody payloadJson)
      Build a complete request using the provided files and payload data.
      Parameters:
      files - The files to upload/edit
      payloadJson - The payload data to send, null to not add a payload_json part
      Returns:
      MultipartBody.Builder
      Throws:
      IllegalArgumentException - If the file list is null

    • forceClose

      void forceClose() throws IOException
      Forces the underlying resource to be closed, even if the file is already handled by a request.
      Throws:
      IOException - If an IOException is thrown while closing the resource