club.minnced.discord.webhook

Class WebhookClient

java.lang.Object

club.minnced.discord.webhook.WebhookClient

All Implemented Interfaces:

java.lang.AutoCloseable

Direct Known Subclasses:

D4JWebhookClient, JavacordWebhookClient, JDAWebhookClient

public class WebhookClient
extends java.lang.Object
implements java.lang.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	WebhookClient.Bucket

Field Summary

Fields

Modifier and Type	Field and Description
protected AllowedMentions	allowedMentions
protected WebhookClient.Bucket	bucket
protected okhttp3.OkHttpClient	client
protected long	defaultTimeout
protected long	id
protected boolean	isQueued
protected boolean	isShutdown
protected WebhookClient	parent
protected boolean	parseMessage
protected java.util.concurrent.ScheduledExecutorService	pool
protected java.util.concurrent.BlockingQueue<club.minnced.discord.webhook.WebhookClient.Request>	queue
protected long	threadId
protected java.lang.String	url
static java.lang.String	USER_AGENT User-Agent used for REST requests
static java.lang.String	WEBHOOK_URL Format for webhook execution endpoint

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	WebhookClient(long id, java.lang.String token, boolean parseMessage, okhttp3.OkHttpClient client, java.util.concurrent.ScheduledExecutorService pool, AllowedMentions mentions, long threadId)
protected	WebhookClient(WebhookClient parent, long threadId)

Method Summary

Modifier and Type	Method and Description
protected void	backoffQueue()
protected void	checkShutdown()
void	close() Stops the thread pool used by this client.
@NotNull java.util.concurrent.CompletableFuture<java.lang.Void>	delete(long messageId) Deletes the message with the provided ID.
@NotNull java.util.concurrent.CompletableFuture<java.lang.Void>	delete(@NotNull java.lang.String messageId) Deletes the message with the provided ID.
protected void	drainQueue()
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	edit(long messageId, @NotNull java.util.Collection<WebhookEmbed> embeds) Edits the target message and updates it with the provided WebhookEmbed to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	edit(long messageId, @NotNull java.lang.String content) Edits the target message and updates it with the provided content as normal message to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	edit(long messageId, @NotNull WebhookEmbed first, WebhookEmbed... embeds) Edits the target message and updates it with the provided WebhookEmbed to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	edit(long messageId, @NotNull WebhookMessage message) Edits the target message and updates it with the provided WebhookMessage to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	edit(@NotNull java.lang.String messageId, @NotNull java.util.Collection<WebhookEmbed> embeds) Edits the target message and updates it with the provided WebhookEmbed to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	edit(@NotNull java.lang.String messageId, @NotNull java.lang.String content) Edits the target message and updates it with the provided content as normal message to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	edit(@NotNull java.lang.String messageId, @NotNull WebhookEmbed first, WebhookEmbed... embeds) Edits the target message and updates it with the provided WebhookEmbed to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	edit(@NotNull java.lang.String messageId, @NotNull WebhookMessage message) Edits the target message and updates it with the provided WebhookMessage to the webhook.
protected @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	execute(okhttp3.RequestBody body)
protected @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	execute(okhttp3.RequestBody body, @Nullable java.lang.String messageId, @NotNull club.minnced.discord.webhook.WebhookClient.RequestType type)
protected static @NotNull HttpException	failure(okhttp3.Response response)
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	get(long messageId) Get the message with the provided ID.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	get(@NotNull java.lang.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 java.lang.String	getUrl() The URL for this webhook formatted using WEBHOOK_URL unless specified by WebhookClientBuilder.WebhookClientBuilder(String) explicitly
boolean	isShutdown() Whether this client has been shutdown.
boolean	isWait() Whether futures will receive ReadonlyMessage instances or null.
protected static @NotNull okhttp3.RequestBody	newBody(java.lang.String object)
protected okhttp3.Request	newRequest(club.minnced.discord.webhook.WebhookClient.Request request)
@NotNull WebhookClient	onThread(long threadId) Returns a wrapper of this WebhookClient that targets the specified thread.
protected @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	queueRequest(java.lang.String url, java.lang.String method, okhttp3.RequestBody body)
protected @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	schedule(@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage> callback, @NotNull club.minnced.discord.webhook.WebhookClient.Request req)
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	send(@NotNull byte[] data, @NotNull java.lang.String fileName) Sends the provided byte[] to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	send(@NotNull java.util.Collection<WebhookEmbed> embeds) Sends the provided WebhookEmbed to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	send(@NotNull java.io.File file) Sends the provided File to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	send(@NotNull java.io.File file, @NotNull java.lang.String fileName) Sends the provided File to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	send(@NotNull java.io.InputStream data, @NotNull java.lang.String fileName) Sends the provided InputStream to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	send(@NotNull java.lang.String content) Sends the provided content as normal message to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	send(@NotNull WebhookEmbed first, WebhookEmbed... embeds) Sends the provided WebhookEmbed to the webhook.
@NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage>	send(@NotNull WebhookMessage message) Sends the provided WebhookMessage to the webhook.
@NotNull WebhookClient	setTimeout(long millis) Configure a default timeout to use for requests.
static @NotNull WebhookClient	withId(long id, @NotNull java.lang.String token) Factory method to create a basic WebhookClient with the provided id and token.
static @NotNull WebhookClient	withUrl(@NotNull java.lang.String url) Factory method to create a basic WebhookClient with the provided id and token.

Methods inherited from class java.lang.Object

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

Field Detail

WEBHOOK_URL

public static final java.lang.String WEBHOOK_URL

Format for webhook execution endpoint

See Also:

Constant Field Values

USER_AGENT

public static final java.lang.String USER_AGENT

User-Agent used for REST requests

See Also:

Constant Field Values

parent

protected final WebhookClient parent

url

protected final java.lang.String url

id

protected final long id

threadId

protected final long threadId

client

protected final okhttp3.OkHttpClient client

pool

protected final java.util.concurrent.ScheduledExecutorService pool

bucket

protected final WebhookClient.Bucket bucket

queue

protected final java.util.concurrent.BlockingQueue<club.minnced.discord.webhook.WebhookClient.Request> queue

parseMessage

protected final boolean parseMessage

allowedMentions

protected final AllowedMentions allowedMentions

defaultTimeout

protected long defaultTimeout

isQueued

protected volatile boolean isQueued

isShutdown

protected boolean isShutdown

Constructor Detail

WebhookClient

protected WebhookClient(long id,
                        java.lang.String token,
                        boolean parseMessage,
                        okhttp3.OkHttpClient client,
                        java.util.concurrent.ScheduledExecutorService pool,
                        AllowedMentions mentions,
                        long threadId)

WebhookClient

protected WebhookClient(WebhookClient parent,
                        long threadId)

Method Detail

withId

@NotNull
public static @NotNull WebhookClient withId(long id,
                                                      @NotNull
                                                      @NotNull java.lang.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:

java.lang.NullPointerException - If provided with null

withUrl

@NotNull
public static @NotNull WebhookClient withUrl(@NotNull
                                                       @NotNull java.lang.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:

java.lang.NullPointerException - If provided with null

java.lang.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 java.lang.String getUrl()

The URL for this webhook formatted using WEBHOOK_URL unless specified by WebhookClientBuilder.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:

java.lang.IllegalArgumentException - If the provided timeout is negative

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 java.util.concurrent.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> send(@NotNull
                                                                                       @NotNull java.io.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> send(@NotNull
                                                                                       @NotNull java.io.File file,
                                                                                       @NotNull
                                                                                       @NotNull java.lang.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> send(@NotNull
                                                                                       @NotNull byte[] data,
                                                                                       @NotNull
                                                                                       @NotNull java.lang.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> send(@NotNull
                                                                                       @NotNull java.io.InputStream data,
                                                                                       @NotNull
                                                                                       @NotNull java.lang.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> send(@NotNull
                                                                                       @NotNull WebhookEmbed first,
                                                                                       @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 java.util.concurrent.CompletableFuture<ReadonlyMessage> send(@NotNull
                                                                                       @NotNull java.util.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> send(@NotNull
                                                                                       @NotNull java.lang.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 java.util.concurrent.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> edit(long messageId,
                                                                                       @NotNull
                                                                                       @NotNull WebhookEmbed first,
                                                                                       @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 java.util.concurrent.CompletableFuture<ReadonlyMessage> edit(long messageId,
                                                                                       @NotNull
                                                                                       @NotNull java.util.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> edit(long messageId,
                                                                                       @NotNull
                                                                                       @NotNull java.lang.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> edit(@NotNull
                                                                                       @NotNull java.lang.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> edit(@NotNull
                                                                                       @NotNull java.lang.String messageId,
                                                                                       @NotNull
                                                                                       @NotNull WebhookEmbed first,
                                                                                       @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 java.util.concurrent.CompletableFuture<ReadonlyMessage> edit(@NotNull
                                                                                       @NotNull java.lang.String messageId,
                                                                                       @NotNull
                                                                                       @NotNull java.util.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> edit(@NotNull
                                                                                       @NotNull java.lang.String messageId,
                                                                                       @NotNull
                                                                                       @NotNull java.lang.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 java.util.concurrent.CompletableFuture<java.lang.Void> delete(long messageId)

Deletes the message with the provided ID.

Parameters:

messageId - The target message id

Returns:

CompletableFuture

delete

@NotNull
public @NotNull java.util.concurrent.CompletableFuture<java.lang.Void> delete(@NotNull
                                                                                        @NotNull java.lang.String messageId)

Deletes the message with the provided ID.

Parameters:

messageId - The target message id

Returns:

CompletableFuture

Throws:

java.lang.NullPointerException - If null is provided

get

@NotNull
public @NotNull java.util.concurrent.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 java.util.concurrent.CompletableFuture<ReadonlyMessage> get(@NotNull
                                                                                      @NotNull java.lang.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:

java.lang.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 java.lang.AutoCloseable

checkShutdown

protected void checkShutdown()

newBody

@NotNull
protected static @NotNull okhttp3.RequestBody newBody(java.lang.String object)

execute

@NotNull
protected @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage> execute(okhttp3.RequestBody body,
                                                                                             @Nullable
                                                                                             @Nullable java.lang.String messageId,
                                                                                             @NotNull
                                                                                             @NotNull club.minnced.discord.webhook.WebhookClient.RequestType type)

execute

@NotNull
protected @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage> execute(okhttp3.RequestBody body)

failure

@NotNull
protected static @NotNull HttpException failure(okhttp3.Response response)
                                                   throws java.io.IOException

Throws:

java.io.IOException

queueRequest

@NotNull
protected @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage> queueRequest(java.lang.String url,
                                                                                                  java.lang.String method,
                                                                                                  okhttp3.RequestBody body)

schedule

@NotNull
protected @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage> schedule(@NotNull
                                                                                              @NotNull java.util.concurrent.CompletableFuture<ReadonlyMessage> callback,
                                                                                              @NotNull
                                                                                              @NotNull club.minnced.discord.webhook.WebhookClient.Request req)

newRequest

@NotNull
protected okhttp3.Request newRequest(club.minnced.discord.webhook.WebhookClient.Request request)

backoffQueue

protected void backoffQueue()

drainQueue

protected void drainQueue()