Package net.dv8tion.jda.webhook

Class WebhookCluster

java.lang.Object

net.dv8tion.jda.webhook.WebhookCluster

All Implemented Interfaces:

java.lang.AutoCloseable

public class WebhookCluster
extends java.lang.Object
implements java.lang.AutoCloseable

A central collection of WebhookClients which allows to broadcast (broadcast(WebhookMessage)) or multicast (multicast(Predicate, WebhookMessage)) to all registered clients (receivers).

Registering existing WebhookClients

To register an existing WebhookClient instance (that is not currently shutdown) you either use addWebhooks(WebhookClient...) or addWebhooks(Collection<WebhookClient>).
These methods allow to register multiple clients in one call and will fail if the client has been closed via WebhookClient.close().

Note that you should always remove a WebhookClient from this cluster when you close it directly!

Removing already registered WebhookClients

The cluster allows to remove existing clients in batch via removeWebhooks(WebhookClient...), removeWebhooks(Collection<WebhookClient>) and removeIf(Predicate<WebhookClient>). It does not matter if the specified clients are actually registered to this cluster when using these methods.

Note that removing a WebhookClient from the cluster does not close it!

Building WebhookClients from the Cluster

This class allows to set default values that will be provided to WebhookClientBuilder when building via buildWebhooks(Webhook...) and buildWebhooks(Collection<Webhook>).
The following settings can be used:

• setDefaultExecutorService(ScheduledExecutorService)
• setDefaultHttpClientBuilder(OkHttpClient.Builder)
• setDefaultHttpClient(OkHttpClient)
• setDefaultThreadFactory(ThreadFactory)
• setDefaultDaemon(boolean)

Note that when you provide your own ScheduledExecutorService you are able to shut it down outside of the clients which will cause them to fail.
Do not shutdown the pool before closing all clients!

Sending to multiple Webhooks at once

This cluster allows to both broadcast and multicast to registered clients.
When broadcasting a message is created before iterating each client to save performance which makes the broadcast method superior to direct for-loops.

Multicasting will send a message to all clients which meet a set filter. The filter is specified using a Predicate which is provided to multicast(Predicate, WebhookMessage).
The predicate decides whether the client should receive the message (returning true) or should be ignored (returning false).

Closing all connections

Each WebhookClient is a Closable resource which means it must be closed to free resources and enhance performance of the JVM.
The WebhookCluster allows to close all registered clients using close(). Calling close on the cluster means it will remove and close all currently registered webhooks.
The cluster may still be used after closing.

Constructor Summary

Constructors

Constructor	Description
WebhookCluster()	Creates a new WebhookCluster with default initial capacity and no registered WebhookClients
WebhookCluster(int initialCapacity)	Creates a new WebhookCluster with the specified initial capacity.
WebhookCluster(java.util.Collection<? extends WebhookClient> initialClients)	Creates a new WebhookCluster with the provided WebhookClients as initial client cache.

Method Summary

Modifier and Type	Method	Description
WebhookCluster	addWebhooks(java.util.Collection<WebhookClient> clients)	Adds the specified WebhookClients to this cluster's list of receivers.
WebhookCluster	addWebhooks(WebhookClient... clients)	Adds the specified WebhookClients to this cluster's list of receivers.
java.util.List<RequestFuture<?>>	broadcast(byte[] data, java.lang.String fileName)	Sends the provided byte[] data as an attachment to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(java.io.File file)	Sends the provided File to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(java.io.File file, java.lang.String fileName)	Sends the provided File to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(java.io.InputStream data, java.lang.String fileName)	Sends the provided InputStream as an attachment to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(java.lang.String content)	Sends the provided text message to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(java.util.Collection<MessageEmbed> embeds)	Sends the provided MessageEmbeds to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(Message message)	Sends the provided Message to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(MessageEmbed[] embeds)	Sends the provided MessageEmbeds to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(MessageEmbed first, MessageEmbed... embeds)	Sends the provided MessageEmbeds to all registered WebhookClients.
java.util.List<RequestFuture<?>>	broadcast(WebhookMessage message)	Sends the provided WebhookMessage to all registered WebhookClients.
WebhookCluster	buildWebhook(long id, java.lang.String token)	Creates new WebhookClients and adds them to this cluster.
WebhookCluster	buildWebhooks(java.util.Collection<Webhook> webhooks)	Creates new WebhookClients and adds them to this cluster.
WebhookCluster	buildWebhooks(Webhook... webhooks)	Creates new WebhookClients and adds them to this cluster.
void	close()	Closes all registered WebhookClients and removes the from this cluster!
java.util.List<WebhookClient>	closeIf(java.util.function.Predicate<WebhookClient> predicate)	Closes all WebhookClients that meet the specified filter.
java.util.List<WebhookClient>	getWebhooks()	The current list of receivers for this WebhookCluster instance.
java.util.List<RequestFuture<?>>	multicast(java.util.function.Predicate<WebhookClient> filter, WebhookMessage message)	Sends the provided WebhookMessage to all WebhookClients that meet the specified filter.
WebhookClientBuilder	newBuilder(long id, java.lang.String token)	Creates a new WebhookClientBuilder with the defined default settings of this cluster.
WebhookClientBuilder	newBuilder(Webhook webhook)	Creates a new WebhookClientBuilder with the defined default settings of this cluster.
java.util.List<WebhookClient>	removeIf(java.util.function.Predicate<WebhookClient> predicate)	Removes the specified WebhookClients from this cluster's list of receivers under the conditions of the provided filter.
WebhookCluster	removeWebhooks(java.util.Collection<WebhookClient> clients)	Removes the specified WebhookClients from this cluster's list of receivers.
WebhookCluster	removeWebhooks(WebhookClient... clients)	Removes the specified WebhookClients from this cluster's list of receivers.
WebhookCluster	setDefaultDaemon(boolean isDaemon)	Whether rate limit threads of created WebhookClients should be treated as Thread.isDaemon() or not.
WebhookCluster	setDefaultExecutorService(java.util.concurrent.ScheduledExecutorService executorService)	Sets the default ScheduledExecutorService that should be used when building WebhookClients via buildWebhooks(Webhook...) or buildWebhooks(Collection).
WebhookCluster	setDefaultHttpClient(okhttp3.OkHttpClient defaultHttpClient)	Sets the default OkHttpClient that should be used when building WebhookClients via buildWebhooks(Webhook...) or buildWebhooks(Collection).
WebhookCluster	setDefaultHttpClientBuilder(okhttp3.OkHttpClient.Builder builder)	Sets the default OkHttpClient.Builder that should be used when building WebhookClients via buildWebhooks(Webhook...) or buildWebhooks(Collection).
WebhookCluster	setDefaultThreadFactory(java.util.concurrent.ThreadFactory factory)	Factory that should be used by the default ScheduledExecutorService to create Threads for rate limitation handling of the created WebhookClient! This allows changing thread information such as name without having to create your own executor.

Methods inherited from class java.lang.Object

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

Constructor Detail

WebhookCluster

public WebhookCluster(@Nonnull
                      java.util.Collection<? extends WebhookClient> initialClients)

Creates a new WebhookCluster with the provided WebhookClients as initial client cache.

Parameters:

initialClients - Collection of WebhookClients that should be added

Throws:

java.lang.IllegalArgumentException - If any of the provided clients is null or closed

WebhookCluster

public WebhookCluster(int initialCapacity)

Creates a new WebhookCluster with the specified initial capacity.
For more information about this see ArrayList.

Parameters:

initialCapacity - The initial capacity for this cluster

Throws:

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

WebhookCluster

public WebhookCluster()

Creates a new WebhookCluster with default initial capacity and no registered WebhookClients

Method Detail

setDefaultHttpClientBuilder

public WebhookCluster setDefaultHttpClientBuilder(@Nullable
                                                  okhttp3.OkHttpClient.Builder builder)

Sets the default OkHttpClient.Builder that should be used when building WebhookClients via buildWebhooks(Webhook...) or buildWebhooks(Collection).

Parameters:

builder - The default builder, null to reset

Returns:

The current WebhookCluster for chaining convenience

setDefaultHttpClient

public WebhookCluster setDefaultHttpClient(@Nullable
                                           okhttp3.OkHttpClient defaultHttpClient)

Sets the default OkHttpClient that should be used when building WebhookClients via buildWebhooks(Webhook...) or buildWebhooks(Collection).

Parameters:

defaultHttpClient - The default client, null to reset

Returns:

The current WebhookCluster for chaining convenience

setDefaultExecutorService

public WebhookCluster setDefaultExecutorService(@Nullable
                                                java.util.concurrent.ScheduledExecutorService executorService)

Sets the default ScheduledExecutorService that should be used when building WebhookClients via buildWebhooks(Webhook...) or buildWebhooks(Collection).

Parameters:

executorService - The default executor service, null to reset

Returns:

The current WebhookCluster for chaining convenience

setDefaultThreadFactory

public WebhookCluster setDefaultThreadFactory(@Nullable
                                              java.util.concurrent.ThreadFactory factory)

Factory that should be used by the default ScheduledExecutorService to create Threads for rate limitation handling of the created WebhookClient!
This allows changing thread information such as name without having to create your own executor.

Parameters:

factory - The ThreadFactory that will be used when no ScheduledExecutorService has been set via setDefaultExecutorService(ScheduledExecutorService)

Returns:

The current WebhookCluster for chaining convenience

setDefaultDaemon

public WebhookCluster setDefaultDaemon(boolean isDaemon)

Whether rate limit threads of created WebhookClients should be treated as Thread.isDaemon() or not.
Default: false

This will not be used when the default thread pool has been set via setDefaultExecutorService(ScheduledExecutorService)!

Parameters:

isDaemon - True, if the threads should be daemon

Returns:

The current WebhookCluster for chaining convenience

buildWebhooks

public WebhookCluster buildWebhooks(Webhook... webhooks)

Creates new WebhookClients and adds them to this cluster.
The WebhookClientBuilders will be supplied with the default settings of this cluster.

Parameters:

webhooks - Webhooks to target (duplicates will not be filtered)

Returns:

The current WebhookCluster for chaining convenience

Throws:

java.lang.IllegalArgumentException - If the provided array or any of the contained webhooks is null

See Also:

buildWebhooks(Webhook...), newBuilder(Webhook)

buildWebhooks

public WebhookCluster buildWebhooks(java.util.Collection<Webhook> webhooks)

Creates new WebhookClients and adds them to this cluster.
The WebhookClientBuilders will be supplied with the default settings of this cluster.

Parameters:

webhooks - Webhooks to target (duplicates will not be filtered)

Returns:

The current WebhookCluster for chaining convenience

Throws:

java.lang.IllegalArgumentException - If the provided collection or any of the contained webhooks is null

See Also:

buildWebhooks(Webhook...), newBuilder(Webhook)

buildWebhook

public WebhookCluster buildWebhook(long id,
                                   java.lang.String token)

Creates new WebhookClients and adds them to this cluster.
The WebhookClientBuilders will be supplied with the default settings of this cluster.

Parameters:

id - The id for the webhook

token - The token for the webhook

Returns:

The current WebhookCluster for chaining convenience

Throws:

java.lang.IllegalArgumentException - If the provided webhooks token is null or contains whitespace

See Also:

newBuilder(long, String)

newBuilder

public WebhookClientBuilder newBuilder(long id,
                                       java.lang.String token)

Creates a new WebhookClientBuilder with the defined default settings of this cluster.

Parameters:

id - The webhook id

token - The webhook token

Returns:

The WebhookClientBuilder with default settings

Throws:

java.lang.IllegalArgumentException - If the token is null, empty or contains blanks

See Also:

new WebhookClientBuilder(long, String)

newBuilder

public WebhookClientBuilder newBuilder(Webhook webhook)

Creates a new WebhookClientBuilder with the defined default settings of this cluster.

Parameters:

webhook - The target webhook

Returns:

The WebhookClientBuilder with default settings

Throws:

java.lang.IllegalArgumentException - If the webhook is null

See Also:

new WebhookClientBuilder(Webhook)

addWebhooks

public WebhookCluster addWebhooks(WebhookClient... clients)

Adds the specified WebhookClients to this cluster's list of receivers.
Duplicate clients are supported and will not be filtered automatically.

Parameters:

clients - WebhookClients to add

Returns:

The current WebhookCluster for chaining convenience

Throws:

java.lang.IllegalArgumentException - If the provided array or any of the contained clients is null or closed

addWebhooks

public WebhookCluster addWebhooks(java.util.Collection<WebhookClient> clients)

Adds the specified WebhookClients to this cluster's list of receivers.
Duplicate clients are supported and will not be filtered automatically.

Parameters:

clients - WebhookClients to add

Returns:

The current WebhookCluster for chaining convenience

Throws:

java.lang.IllegalArgumentException - If the provided collection or any of the contained clients is null or closed

removeWebhooks

public WebhookCluster removeWebhooks(WebhookClient... clients)

Removes the specified WebhookClients from this cluster's list of receivers.
It does not matter whether any of the provided clients is actually in the list of receivers.

Note that the removed clients are not closed by this operation!

Parameters:

clients - WebhookClients to remove

Returns:

The current WebhookCluster for chaining convenience

Throws:

java.lang.IllegalArgumentException - If the provided array is null

removeWebhooks

public WebhookCluster removeWebhooks(java.util.Collection<WebhookClient> clients)

Removes the specified WebhookClients from this cluster's list of receivers.
It does not matter whether any of the provided clients is actually in the list of receivers.

Note that the removed clients are not closed by this operation!

Parameters:

clients - WebhookClients to remove

Returns:

The current WebhookCluster for chaining convenience

Throws:

java.lang.IllegalArgumentException - If the provided collection is null

removeIf

public java.util.List<WebhookClient> removeIf(java.util.function.Predicate<WebhookClient> predicate)

Removes the specified WebhookClients from this cluster's list of receivers under the conditions of the provided filter.
The filter should return true to remove provided clients and false to retain them.

Note that the removed clients are not closed by this operation!

Parameters:

predicate - The filter

Returns:

List of removed clients

Throws:

java.lang.IllegalArgumentException - If the provided filter is null

closeIf

public java.util.List<WebhookClient> closeIf(java.util.function.Predicate<WebhookClient> predicate)

Closes all WebhookClients that meet the specified filter.
The filter may return true for all clients that should be removed and closed.

Parameters:

predicate - The filter to decide which clients to remove

Returns:

List of removed and closed clients

Throws:

java.lang.IllegalArgumentException - If the provided filter is null

getWebhooks

public java.util.List<WebhookClient> getWebhooks()

The current list of receivers for this WebhookCluster instance.
The provided list is an immutable copy of the actual stored list of WebhookClients.

Returns:

Immutable list of registered receivers

multicast

public java.util.List<RequestFuture<?>> multicast(java.util.function.Predicate<WebhookClient> filter,
                                                  WebhookMessage message)

Sends the provided WebhookMessage to all WebhookClients that meet the specified filter.
The filter should return true for all clients that should receive the message.

Hint: Use WebhookMessageBuilder to create a WebhookMessage instance!

Parameters:

filter - The filter that decides what clients receive the message

message - The message that should be sent to the filtered clients

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If any of the provided arguments is null

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(WebhookMessage message)

Sends the provided WebhookMessage to all registered WebhookClients.

Hint: Use WebhookMessageBuilder to create a WebhookMessage instance!

Parameters:

message - The message that should be sent to the clients

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If any of the provided arguments is null

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(Message message)

Sends the provided Message to all registered WebhookClients.

Hint: Use MessageBuilder to create a Message instance!

Parameters:

message - The message that should be sent to the clients

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If the provided message is null

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(MessageEmbed[] embeds)

Sends the provided MessageEmbeds to all registered WebhookClients.

You can send up to 10 embeds per message! If more are sent they will not be displayed.

Hint: Use EmbedBuilder to create a MessageEmbeds instance!

Parameters:

embeds - The embeds that should be sent to the clients

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If any of the provided arguments is null

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(MessageEmbed first,
                                                  MessageEmbed... embeds)

Sends the provided MessageEmbeds to all registered WebhookClients.

You can send up to 10 embeds per message! If more are sent they will not be displayed.

Hint: Use EmbedBuilder to create a MessageEmbeds instance!

Parameters:

first - The first embed to send to the clients

embeds - The other embeds that should be sent to the clients

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If any of the provided arguments is null

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(java.util.Collection<MessageEmbed> embeds)

Sends the provided MessageEmbeds to all registered WebhookClients.

You can send up to 10 embeds per message! If more are sent they will not be displayed.

Hint: Use EmbedBuilder to create a MessageEmbeds instance!

Parameters:

embeds - The embeds that should be sent to the clients

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If any of the provided arguments is null

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(java.lang.String content)

Sends the provided text message to all registered WebhookClients.

Parameters:

content - The text that should be sent to the clients

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If the provided content is null or blank

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(java.io.File file)

Sends the provided File to all registered WebhookClients.
Use WebhookMessage.files(String, Object, Object...) to send up to 10 files!

The provided data should not exceed 8MB in size!

Parameters:

file - The file that should be sent to the clients

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If the provided file is null, does not exist or ist not readable

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(java.io.File file,
                                                  java.lang.String fileName)

Sends the provided File to all registered WebhookClients.
Use WebhookMessage.files(String, Object, Object...) to send up to 10 files!

The provided data should not exceed 8MB in size!

Parameters:

file - The file that should be sent to the clients

fileName - The name that should be given to the file

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If the provided file is null, does not exist or ist not readable

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(java.io.InputStream data,
                                                  java.lang.String fileName)

Sends the provided InputStream as an attachment to all registered WebhookClients.
Use WebhookMessage.files(String, Object, Object...) to send up to 10 files!

The provided data should not exceed 8MB in size!

Parameters:

data - The data that should be sent to the clients

fileName - The name that should be given to the attachment

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If the provided data is null

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

broadcast

public java.util.List<RequestFuture<?>> broadcast(byte[] data,
                                                  java.lang.String fileName)

Sends the provided byte[] data as an attachment to all registered WebhookClients.
Use WebhookMessage.files(String, Object, Object...) to send up to 10 files!

The provided data should not exceed 8MB in size!

Parameters:

data - The data that should be sent to the clients

fileName - The name that should be given to the attachment

Returns:

A list of Future instances representing all message tasks.

Throws:

java.lang.IllegalArgumentException - If the provided data is null

java.util.concurrent.RejectedExecutionException - If any of the receivers has been shutdown

close

public void close()

Closes all registered WebhookClients and removes the from this cluster!

Specified by:

close in interface java.lang.AutoCloseable