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.

Field Summary

Fields inherited from interface net.dv8tion.jda.api.utils.AttachedFile

MAX_DESCRIPTION_LENGTH

Method Summary

Modifier and Type	Method	Description
void	addPart(okhttp3.MultipartBody.Builder builder, int index)	Used internally to build the multipart request.
FileUpload	asSpoiler()	Changes the name of this file, to be prefixed as SPOILER_.
void	close()
void	forceClose()	Forces the underlying resource to be closed, even if the file is already handled by a request.
static FileUpload	fromData(byte[] data, String name)	Create a new FileUpload for a byte array.
static FileUpload	fromData(File file)	Create a new FileUpload for a local file.
static FileUpload	fromData(File file, String name)	Create a new FileUpload for a local file.
static FileUpload	fromData(InputStream data, String name)	Create a new FileUpload for an input stream.
static FileUpload	fromData(Path path, String name, OpenOption... options)	Create a new FileUpload for a local file.
static FileUpload	fromData(Path path, OpenOption... options)	Create a new FileUpload for a local file.
InputStream	getData()	The InputStream representing the data to upload as a file.
String	getName()	The filename for the file.
okhttp3.RequestBody	getRequestBody(okhttp3.MediaType type)	Creates a re-usable instance of RequestBody with the specified content-type.
FileUpload	setDescription(String description)	Set the file description used as ALT text for screenreaders.
FileUpload	setName(String name)	Changes the name of this file.
DataObject	toAttachmentData(int index)	Used internally to build attachment descriptions for requests.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Details

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:

• FileInputStream

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:

• FileInputStream

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:

• FileInputStream
• fromData(File, String)

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

getName

@Nonnull
public String getName()

The filename for the file.

Returns:

The filename

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