Package club.minnced.discord.webhook

Class WebhookClient

java.lang.Object

club.minnced.discord.webhook.WebhookClient

All Implemented Interfaces:

AutoCloseable

Direct Known Subclasses:

D4JWebhookClient, JavacordWebhookClient, JDAWebhookClient

public class WebhookClient
extends Object
implements AutoCloseable

Client used to execute webhooks. All send methods are async and return a CompletableFuture representing the execution. If provided with null an NullPointerException is thrown instead.

Field Summary

Fields

Modifier and Type	Field	Description
static String	USER_AGENT	User-Agent used for REST requests
static String	WEBHOOK_URL	Format for webhook execution endpoint

Method Summary

Modifier and Type	Method	Description
void	close()	Stops the thread pool used by this client.
@NotNull CompletableFuture<Void>	delete(long messageId)	Deletes the message with the provided ID.
@NotNull CompletableFuture<Void>	delete(@NotNull String messageId)	Deletes the message with the provided ID.
@NotNull CompletableFuture<ReadonlyMessage>	edit(long messageId, @NotNull WebhookEmbed first, @NotNull WebhookEmbed... embeds)	Edits the target message and updates it with the provided WebhookEmbed to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	edit(long messageId, @NotNull WebhookMessage message)	Edits the target message and updates it with the provided WebhookMessage to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	edit(long messageId, @NotNull String content)	Edits the target message and updates it with the provided content as normal message to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	edit(long messageId, @NotNull Collection<WebhookEmbed> embeds)	Edits the target message and updates it with the provided WebhookEmbed to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	edit(@NotNull String messageId, @NotNull WebhookEmbed first, @NotNull WebhookEmbed... embeds)	Edits the target message and updates it with the provided WebhookEmbed to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	edit(@NotNull String messageId, @NotNull WebhookMessage message)	Edits the target message and updates it with the provided WebhookMessage to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	edit(@NotNull String messageId, @NotNull String content)	Edits the target message and updates it with the provided content as normal message to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	edit(@NotNull String messageId, @NotNull Collection<WebhookEmbed> embeds)	Edits the target message and updates it with the provided WebhookEmbed to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	get(long messageId)	Get the message with the provided ID.
@NotNull CompletableFuture<ReadonlyMessage>	get(@NotNull String messageId)	Get the message with the provided ID.
long	getId()	The id for this webhook
long	getThreadId()	The target thread id this webhook client uses.
long	getTimeout()	The current timeout configured by setTimeout(long).
@NotNull String	getUrl()	The URL for this webhook formatted using WEBHOOK_URL unless specified by WebhookClientBuilder(String) explicitly
boolean	isShutdown()	Whether this client has been shutdown.
boolean	isWait()	Whether futures will receive ReadonlyMessage instances or null.
@NotNull WebhookClient	onThread(long threadId)	Returns a wrapper of this WebhookClient that targets the specified thread.
@NotNull CompletableFuture<ReadonlyMessage>	send(@org.jetbrains.annotations.NotNull byte[] data, @NotNull String fileName)	Sends the provided byte[] to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	send(@NotNull WebhookEmbed first, @NotNull WebhookEmbed... embeds)	Sends the provided WebhookEmbed to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	send(@NotNull WebhookMessage message)	Sends the provided WebhookMessage to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	send(@NotNull File file)	Sends the provided File to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	send(@NotNull File file, @NotNull String fileName)	Sends the provided File to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	send(@NotNull InputStream data, @NotNull String fileName)	Sends the provided InputStream to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	send(@NotNull String content)	Sends the provided content as normal message to the webhook.
@NotNull CompletableFuture<ReadonlyMessage>	send(@NotNull Collection<WebhookEmbed> embeds)	Sends the provided WebhookEmbed to the webhook.
static void	setDefaultErrorHandler(@NotNull WebhookErrorHandler handler)	Configures which default error handler to use instead of WebhookErrorHandler.DEFAULT.
@NotNull WebhookClient	setErrorHandler(@NotNull WebhookErrorHandler handler)	Configures the error handling behavior used for all asynchronous send/edit/delete calls.
@NotNull WebhookClient	setTimeout(long millis)	Configure a default timeout to use for requests.
static @NotNull WebhookClient	withId(long id, @NotNull String token)	Factory method to create a basic WebhookClient with the provided id and token.
static @NotNull WebhookClient	withUrl(@NotNull String url)	Factory method to create a basic WebhookClient with the provided id and token.

Methods inherited from class java.lang.Object

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

Field Detail

WEBHOOK_URL

public static final String WEBHOOK_URL

Format for webhook execution endpoint

See Also:

Constant Field Values

USER_AGENT

public static final String USER_AGENT

User-Agent used for REST requests

See Also:

Constant Field Values

Method Detail

setDefaultErrorHandler

public static void setDefaultErrorHandler(@NotNull
                                          @NotNull WebhookErrorHandler handler)

Configures which default error handler to use instead of WebhookErrorHandler.DEFAULT.

You can use this to avoid having to set the error handler on each new webhook client instance.

Parameters:

handler - The error handler to use

Throws:

NullPointerException - If null is provided

withId

@NotNull
public static @NotNull WebhookClient withId(long id,
                                            @NotNull
                                            @NotNull String token)

Factory method to create a basic WebhookClient with the provided id and token.

You can use onThread(long) to target specific threads on the channel.

Parameters:

id - The webhook id

token - The webhook token

Returns:

The WebhookClient for the provided id and token

Throws:

NullPointerException - If provided with null

withUrl

@NotNull
public static @NotNull WebhookClient withUrl(@NotNull
                                             @NotNull String url)

Factory method to create a basic WebhookClient with the provided id and token.

You can use onThread(long) to target specific threads on the channel.

Parameters:

url - The url for the webhook

Returns:

The WebhookClient for the provided url

Throws:

NullPointerException - If provided with null

NumberFormatException - If no valid id is part o the url

onThread

@NotNull
public @NotNull WebhookClient onThread(long threadId)

Returns a wrapper of this WebhookClient that targets the specified thread.
The thread should be on the same channel as the webhook.

The returned webhook client inherits all the settings (including the thread pool) from this client instance. If either of the clients is shutdown/closed, the other instance will no longer send any messages.

Parameters:

threadId - The target thread id, or 0 to send directly to the parent channel

Returns:

A new webhook client instance which targets the specified thread

getId

public long getId()

The id for this webhook

Returns:

The id

getThreadId

public long getThreadId()

The target thread id this webhook client uses.

Returns:

The thread id or 0 if the messages are not sent to threads

getUrl

@NotNull
public @NotNull String getUrl()

The URL for this webhook formatted using WEBHOOK_URL unless specified by WebhookClientBuilder(String) explicitly

Returns:

The URL for this webhook

isWait

public boolean isWait()

Whether futures will receive ReadonlyMessage instances or null.

Returns:

True, if messages will be received - false otherwise

isShutdown

public boolean isShutdown()

Whether this client has been shutdown.

Returns:

True, if client is closed

setTimeout

@NotNull
public @NotNull WebhookClient setTimeout(@Nonnegative
                                         long millis)

Configure a default timeout to use for requests.
The CompletableFuture returned by the various send methods will be completed exceptionally with a TimeoutException when the timeout expires. By default, no timeout is used.

Note that this timeout is independent of the timeouts configured in OkHttpClient and will only prevent queued requests from being executed.

Parameters:

millis - The timeout in milliseconds, or 0 for no timeout

Returns:

The current WebhookClient instance

Throws:

IllegalArgumentException - If the provided timeout is negative

setErrorHandler

@NotNull
public @NotNull WebhookClient setErrorHandler(@NotNull
                                              @NotNull WebhookErrorHandler handler)

Configures the error handling behavior used for all asynchronous send/edit/delete calls.

Parameters:

handler - The error handler

Returns:

The current WebhookClient instance

Throws:

NullPointerException - If provided with null

getTimeout

public long getTimeout()

The current timeout configured by setTimeout(long).
If no timeout was configured, this returns 0.

Returns:

The timeout in milliseconds or 0 for no timeout

send

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> send(@NotNull
                                                        @NotNull WebhookMessage message)

Sends the provided WebhookMessage to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

This will override the default AllowedMentions of this client!

Parameters:

message - The message to send

Returns:

CompletableFuture

See Also:

isWait()

send

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> send(@NotNull
                                                        @NotNull File file)

Sends the provided File to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

file - The file to send

Returns:

CompletableFuture

See Also:

isWait(), send(club.minnced.discord.webhook.send.WebhookMessage)

send

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> send(@NotNull
                                                        @NotNull File file,
                                                        @NotNull
                                                        @NotNull String fileName)

Sends the provided File to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

file - The file to send

fileName - The alternative name to use for this file

Returns:

CompletableFuture

See Also:

isWait(), send(club.minnced.discord.webhook.send.WebhookMessage)

send

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> send(@NotNull
                                                        @org.jetbrains.annotations.NotNull byte[] data,
                                                        @NotNull
                                                        @NotNull String fileName)

Sends the provided byte[] to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

data - The data to send as a file

fileName - The file name to use

Returns:

CompletableFuture

See Also:

isWait(), send(club.minnced.discord.webhook.send.WebhookMessage)

send

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> send(@NotNull
                                                        @NotNull InputStream data,
                                                        @NotNull
                                                        @NotNull String fileName)

Sends the provided InputStream to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

data - The data to send as a file

fileName - The file name to use

Returns:

CompletableFuture

See Also:

isWait(), send(club.minnced.discord.webhook.send.WebhookMessage)

send

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> send(@NotNull
                                                        @NotNull WebhookEmbed first,
                                                        @NotNull
                                                        @NotNull WebhookEmbed... embeds)

Sends the provided WebhookEmbed to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

first - The first embed to send

embeds - Optional additional embeds to send, up to 10

Returns:

CompletableFuture

See Also:

isWait(), send(club.minnced.discord.webhook.send.WebhookMessage)

send

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> send(@NotNull
                                                        @NotNull Collection<WebhookEmbed> embeds)

Sends the provided WebhookEmbed to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

embeds - The embeds to send

Returns:

CompletableFuture

See Also:

isWait(), send(club.minnced.discord.webhook.send.WebhookMessage)

send

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> send(@NotNull
                                                        @NotNull String content)

Sends the provided content as normal message to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

content - The content to send

Returns:

CompletableFuture

See Also:

isWait(), send(club.minnced.discord.webhook.send.WebhookMessage)

edit

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> edit(long messageId,
                                                        @NotNull
                                                        @NotNull WebhookMessage message)

Edits the target message and updates it with the provided WebhookMessage to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

This will override the default AllowedMentions of this client!

Parameters:

messageId - The target message id

message - The message to send

Returns:

CompletableFuture

See Also:

isWait()

edit

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> edit(long messageId,
                                                        @NotNull
                                                        @NotNull WebhookEmbed first,
                                                        @NotNull
                                                        @NotNull WebhookEmbed... embeds)

Edits the target message and updates it with the provided WebhookEmbed to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

messageId - The target message id

first - The first embed to send

embeds - Optional additional embeds to send, up to 10

Returns:

CompletableFuture

See Also:

isWait(), edit(long, club.minnced.discord.webhook.send.WebhookMessage)

edit

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> edit(long messageId,
                                                        @NotNull
                                                        @NotNull Collection<WebhookEmbed> embeds)

Edits the target message and updates it with the provided WebhookEmbed to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

messageId - The target message id

embeds - The embeds to send

Returns:

CompletableFuture

See Also:

isWait(), edit(long, club.minnced.discord.webhook.send.WebhookMessage)

edit

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> edit(long messageId,
                                                        @NotNull
                                                        @NotNull String content)

Edits the target message and updates it with the provided content as normal message to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

messageId - The target message id

content - The content to send

Returns:

CompletableFuture

See Also:

isWait(), edit(long, club.minnced.discord.webhook.send.WebhookMessage)

edit

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> edit(@NotNull
                                                        @NotNull String messageId,
                                                        @NotNull
                                                        @NotNull WebhookMessage message)

Edits the target message and updates it with the provided WebhookMessage to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

This will override the default AllowedMentions of this client!

Parameters:

messageId - The target message id

message - The message to send

Returns:

CompletableFuture

See Also:

isWait()

edit

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> edit(@NotNull
                                                        @NotNull String messageId,
                                                        @NotNull
                                                        @NotNull WebhookEmbed first,
                                                        @NotNull
                                                        @NotNull WebhookEmbed... embeds)

Edits the target message and updates it with the provided WebhookEmbed to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

messageId - The target message id

first - The first embed to send

embeds - Optional additional embeds to send, up to 10

Returns:

CompletableFuture

See Also:

isWait(), edit(long, club.minnced.discord.webhook.send.WebhookMessage)

edit

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> edit(@NotNull
                                                        @NotNull String messageId,
                                                        @NotNull
                                                        @NotNull Collection<WebhookEmbed> embeds)

Edits the target message and updates it with the provided WebhookEmbed to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

messageId - The target message id

embeds - The embeds to send

Returns:

CompletableFuture

See Also:

isWait(), edit(long, club.minnced.discord.webhook.send.WebhookMessage)

edit

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> edit(@NotNull
                                                        @NotNull String messageId,
                                                        @NotNull
                                                        @NotNull String content)

Edits the target message and updates it with the provided content as normal message to the webhook.
The returned future receives null if WebhookClientBuilder.setWait(boolean) was set to false.

Parameters:

messageId - The target message id

content - The content to send

Returns:

CompletableFuture

See Also:

isWait(), edit(long, club.minnced.discord.webhook.send.WebhookMessage)

delete

@NotNull
public @NotNull CompletableFuture<Void> delete(long messageId)

Deletes the message with the provided ID.

Parameters:

messageId - The target message id

Returns:

CompletableFuture

delete

@NotNull
public @NotNull CompletableFuture<Void> delete(@NotNull
                                               @NotNull String messageId)

Deletes the message with the provided ID.

Parameters:

messageId - The target message id

Returns:

CompletableFuture

Throws:

NullPointerException - If null is provided

get

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> get(long messageId)

Get the message with the provided ID.
Only messages sent by this webhook can be retrieved.

Parameters:

messageId - The target message id

Returns:

CompletableFuture

get

@NotNull
public @NotNull CompletableFuture<ReadonlyMessage> get(@NotNull
                                                       @NotNull String messageId)

Get the message with the provided ID.
Only messages sent by this webhook can be retrieved.

Parameters:

messageId - The target message id

Returns:

CompletableFuture

Throws:

NullPointerException - If null is provided

close

public void close()

Stops the thread pool used by this client.
Any further requests to this client or clients with the same thread pool will be rejected.

Specified by:

close in interface AutoCloseable