docs.jda.wiki
Open in
urlscan Pro
2606:50c0:8002::153
Public Scan
URL:
https://docs.jda.wiki/net/dv8tion/jda/api/requests/RestAction.html
Submission: On October 09 via api from US — Scanned from DE
Submission: On October 09 via api from US — Scanned from DE
Form analysis 0 forms found in the DOM
Text Content
JavaScript is disabled on your browser.
Skip navigation links
* Overview
* Package
* Class
* Tree
* Deprecated
* Index
* Help
* Summary:
* Nested
* Field
* Constr
* Method
* Detail:
* Field
* Constr
* Method
* Summary:
* Nested |
* Field |
* Constr |
* Method
* Detail:
* Field |
* Constr |
* Method
SEARCH
Package net.dv8tion.jda.api.requests
INTERFACE RESTACTION<T>
Type Parameters: T - The generic response type for this RestAction All Known
Subinterfaces: AbstractThreadCreateAction<T,R>, AbstractWebhookMessageAction<T,
R>, AccountManager, AudioChannelManager<T,M>, AuditableRestAction<T>,
AuditLogPaginationAction, AutoCompleteCallbackAction, AutoModRuleManager,
BanPaginationAction, CacheRestAction<T>, CategoryManager, CategoryOrderAction,
ChannelAction<T>, ChannelManager<T,M>, ChannelOrderAction, CommandCreateAction,
CommandEditAction, CommandListUpdateAction, CustomEmojiManager,
EntitlementPaginationAction, FluentAuditableRestAction<T,R>, FluentRestAction<T,
R>, ForumChannelManager, ForumPostAction, GuildAction, GuildManager,
GuildStickerManager, GuildWelcomeScreenManager, IAgeRestrictedChannelManager<T,
M>, ICategorizableChannelManager<T,M>, InteractionCallbackAction<T>,
InviteAction, IPermissionContainerManager<T,M>, IPositionableChannelManager<T,M>
, IPostContainerManager<T,M>, ISlowmodeChannelManager<T,M>,
IThreadContainerManager<T,M>, Manager<M>, MediaChannelManager, MemberAction,
MessageCreateAction, MessageEditAction, MessageEditCallbackAction,
MessagePaginationAction, ModalCallbackAction, NewsChannelManager, OrderAction<T,
M>, PaginationAction<T,M>, PermissionOverrideAction, PermOverrideManager,
PollVotersPaginationAction, PremiumRequiredCallbackAction,
ReactionPaginationAction, ReplyCallbackAction, RoleAction, RoleManager,
RoleOrderAction, ScheduledEventAction, ScheduledEventManager,
ScheduledEventMembersPaginationAction, StageChannelManager, StageInstanceAction,
StageInstanceManager, StandardGuildChannelManager<T,M>,
StandardGuildMessageChannelManager<T,M>, TemplateManager,
TestEntitlementCreateAction, TextChannelManager, ThreadChannelAction,
ThreadChannelManager, ThreadChannelPaginationAction,
ThreadMemberPaginationAction, VoiceChannelManager, WebhookAction, WebhookManager
, WebhookMessageCreateAction<T>, WebhookMessageDeleteAction,
WebhookMessageEditAction<T>, WebhookMessageRetrieveAction All Known Implementing
Classes: MessageHistory.MessageRetrieveAction,
net.dv8tion.jda.internal.requests.RestActionImpl
--------------------------------------------------------------------------------
public interface RestAction<T>
A class representing a terminal between the user and the discord API.
This is used to offer users the ability to decide how JDA should limit a
Request.
Methods that return an instance of RestAction require an additional step to
complete the execution. Thus the user needs to append a follow-up method.
A default RestAction is issued with the following operations:
* queue(), queue(Consumer), queue(Consumer, Consumer)
The fastest and most simplistic way to execute a RestAction is to queue it.
This method has two optional callback functions, one with the generic type
and another with a failure exception.
* submit(), submit(boolean)
Provides a Future representing the pending request.
An optional parameter of type boolean can be passed to disable automated rate
limit handling. (not recommended)
* complete(), complete(boolean)
Blocking execution building up on submit().
This will simply block the thread and return the Request result, or throw an
exception.
An optional parameter of type boolean can be passed to disable automated rate
limit handling. (not recommended)
The most efficient way to use a RestAction is by using the asynchronous queue()
operations.
These allow users to provide success and failure callbacks which will be called
at a convenient time.
Planning Execution
To schedule a RestAction we provide both queue() and complete() versions that
will be executed by a ScheduledExecutorService after a specified delay:
* queueAfter(long, TimeUnit)
Schedules a call to queue() with default callback Consumers to be executed
after the specified delay.
The TimeUnit is used to convert the provided long into a delay time.
Example: queueAfter(1, TimeUnit.SECONDS);
will call queue() 1 second later.
* submitAfter(long, TimeUnit)
This returns a ScheduledFuture which can be joined into the current Thread
using Future.get()
The blocking call to submitAfter(delay, unit).get() will return the value
processed by a call to complete()
* completeAfter(long, TimeUnit)
This operation simply sleeps for the given delay and will call complete()
once finished sleeping.
All of those operations provide overloads for optional parameters such as a
custom ScheduledExecutorService instead of using the default global JDA
executor. Specifically queueAfter(long, TimeUnit) has overloads to provide a
success and/or failure callback due to the returned ScheduledFuture not being
able to provide the response values of the queue() callbacks.
Using RestActions
The most common way to use a RestAction is not using the returned value.
For instance sending messages usually means you will not require to view the
message once it was sent. Thus we can simply use the asynchronous queue()
operation which will be executed on a rate limit worker thread in the
background, without blocking your current thread:
MessageChannel channel = event.getChannel();
RestAction<Message> action = channel.sendMessage("Hello World");
action.queue(); // Execute the rest action asynchronously
Sometimes it is important to access the response value, possibly to modify it
later.
Now we have two options to actually access the response value, either using an
asynchronous callback Consumer or the (not recommended) complete() which will
block the current thread until the response has been processed and joins with
the current thread.
Example Queue: (recommended)
MessageChannel channel = event.getChannel();
final long time = System.currentTimeMillis();
RestAction<Message> action = channel.sendMessage("Calculating Response Time...");
Consumer<Message> callback = (message) -> {
Message m = message; // ^This is a lambda parameter!^
m.editMessage("Response Time: " + (System.currentTimeMillis() - time) + "ms").queue();
// End with queue() to not block the callback thread!
};
// You can also inline this with the queue parameter: action.queue(m -> m.editMessage(...).queue());
action.queue(callback);
Example Complete:
MessageChannel channel = event.getChannel();
final long time = System.currentTimeMillis();
RestAction<Message> action = channel.sendMessage("Calculating Response Time...");
Message message = action.complete();
message.editMessage("Response Time: " + (System.currentTimeMillis() - time) + "ms").queue();
// End with queue() to not block the callback thread!
Example Planning:
MessageChannel channel = event.getChannel();
RestAction<Message> action = channel.sendMessage("This message will destroy itself in 5 seconds!");
action.queue((message) -> message.delete().queueAfter(5, TimeUnit.SECONDS));
Developer Note: It is generally a good practice to use asynchronous logic
because blocking threads requires resources which can be avoided by using
callbacks over blocking operations:
queue(Consumer) > complete()
There is a dedicated wiki page for RestActions that can be useful for learning.
Since: 3.0 See Also:
* ErrorHandler
* ErrorResponseException
* METHOD SUMMARY
All MethodsStatic MethodsInstance MethodsAbstract MethodsDefault Methods
Modifier and Type
Method
Description
static <E, A, O> RestAction<O>
accumulate(Collection<? extends RestAction<? extends E>> actions, Collector<?
super E,A,? extends O> collector)
Creates a RestAction instance which accumulates all results of the provided
actions.
default RestAction<T>
addCheck(BooleanSupplier checks)
Shortcut for setCheck(() -> getCheck().getAsBoolean() &&
checks.getAsBoolean()).
static <E> RestAction<List<E>>
allOf(Collection<? extends RestAction<? extends E>> actions)
Creates a RestAction instance which accumulates all results of the provided
actions.
static <E> RestAction<List<E>>
allOf(RestAction<? extends E> first, RestAction<? extends E>... others)
Creates a RestAction instance which accumulates all results of the provided
actions.
default <U> RestAction<Void>
and(RestAction<U> other)
Combines this RestAction with the provided action.
default <U, O> RestAction<O>
and(RestAction<U> other, BiFunction<? super T,? super U,? extends
O> accumulator)
Combines this RestAction with the provided action.
default T
complete()
Blocks the current Thread and awaits the completion of an submit() request.
T
complete(boolean shouldQueue)
Blocks the current Thread and awaits the completion of an submit() request.
default T
completeAfter(long delay, TimeUnit unit)
Blocks the current Thread for the specified delay and calls complete() when
delay has been reached.
default RestAction<T>
deadline(long timestamp)
Similar to timeout(long, TimeUnit) but schedules a deadline at which the
request has to be completed.
default RestAction<T>
delay(long delay, TimeUnit unit)
Intermediate operator that returns a modified RestAction.
default RestAction<T>
delay(long delay, TimeUnit unit, ScheduledExecutorService scheduler)
Intermediate operator that returns a modified RestAction.
default RestAction<T>
delay(Duration duration)
Intermediate operator that returns a modified RestAction.
default RestAction<T>
delay(Duration duration, ScheduledExecutorService scheduler)
Intermediate operator that returns a modified RestAction.
default <O> RestAction<O>
flatMap(Function<? super T,? extends RestAction<O>> flatMap)
Intermediate operator that returns a modified RestAction.
default <O> RestAction<O>
flatMap(Predicate<? super T> condition, Function<? super T,? extends
RestAction<O>> flatMap)
Intermediate operator that returns a modified RestAction.
default BooleanSupplier
getCheck()
The current checks for this RestAction.
static Consumer<? super Throwable>
getDefaultFailure()
The default failure callback used when none is provided in queue(Consumer,
Consumer).
static Consumer<Object>
getDefaultSuccess()
The default success callback used when none is provided in queue(Consumer,
Consumer) or queue(Consumer).
static long
getDefaultTimeout()
The default timeout to apply to every RestAction in milliseconds.
JDA
getJDA()
The current JDA instance
static boolean
isPassContext()
Whether RestActions will use ContextException automatically to keep track of
the caller context.
default <O> RestAction<O>
map(Function<? super T,? extends O> map)
Intermediate operator that returns a modified RestAction.
default RestAction<Result<T>>
mapToResult()
Converts the success and failure callbacks into a Result.
default RestAction<T>
onErrorFlatMap(Function<? super Throwable,? extends RestAction<? extends T
>> map)
Supply a fallback value when the RestAction fails for a any reason.
default RestAction<T>
onErrorFlatMap(Predicate<? super Throwable> condition, Function<? super
Throwable,? extends RestAction<? extends T>> map)
Supply a fallback value when the RestAction fails for a specific reason.
default RestAction<T>
onErrorMap(Function<? super Throwable,? extends T> map)
Supply a fallback value when the RestAction fails for any reason.
default RestAction<T>
onErrorMap(Predicate<? super Throwable> condition, Function<? super Throwable
,? extends T> map)
Supply a fallback value when the RestAction fails for a specific reason.
default RestAction<T>
onSuccess(Consumer<? super T> consumer)
An intermediate operator that returns a modified RestAction.
default void
queue()
Submits a Request for execution.
default void
queue(Consumer<? super T> success)
Submits a Request for execution.
void
queue(Consumer<? super T> success, Consumer<? super Throwable> failure)
Submits a Request for execution.
default ScheduledFuture<?>
queueAfter(long delay, TimeUnit unit)
Schedules a call to queue() to be executed after the specified delay.
default ScheduledFuture<?>
queueAfter(long delay, TimeUnit unit, ScheduledExecutorService executor)
Schedules a call to queue() to be executed after the specified delay.
default ScheduledFuture<?>
queueAfter(long delay, TimeUnit unit, Consumer<? super T> success)
Schedules a call to queue(java.util.function.Consumer) to be executed after
the specified delay.
default ScheduledFuture<?>
queueAfter(long delay, TimeUnit unit, Consumer<? super T> success,
ScheduledExecutorService executor)
Schedules a call to queue(java.util.function.Consumer) to be executed after
the specified delay.
default ScheduledFuture<?>
queueAfter(long delay, TimeUnit unit, Consumer<? super T> success, Consumer<?
super Throwable> failure)
Schedules a call to queue(java.util.function.Consumer,
java.util.function.Consumer) to be executed after the specified delay.
default ScheduledFuture<?>
queueAfter(long delay, TimeUnit unit, Consumer<? super T> success, Consumer<?
super Throwable> failure, ScheduledExecutorService executor)
Schedules a call to queue(java.util.function.Consumer,
java.util.function.Consumer) to be executed after the specified delay.
RestAction<T>
setCheck(BooleanSupplier checks)
Sets the last-second checks before finally executing the http request in the
queue.
static void
setDefaultFailure(Consumer<? super Throwable> callback)
The default failure callback used when none is provided in queue(Consumer,
Consumer).
static void
setDefaultSuccess(Consumer<Object> callback)
The default success callback used when none is provided in queue(Consumer,
Consumer) or queue(Consumer).
static void
setDefaultTimeout(long timeout, TimeUnit unit)
Default timeout to apply to every RestAction.
static void
setPassContext(boolean enable)
If enabled this will pass a ContextException as root-cause to all failure
consumers.
default CompletableFuture<T>
submit()
Submits a Request for execution and provides a CompletableFuture representing
its completion task.
CompletableFuture<T>
submit(boolean shouldQueue)
Submits a Request for execution and provides a CompletableFuture representing
its completion task.
default DelayedCompletableFuture<T>
submitAfter(long delay, TimeUnit unit)
Schedules a call to queue() to be executed after the specified delay.
default DelayedCompletableFuture<T>
submitAfter(long delay, TimeUnit unit, ScheduledExecutorService executor)
Schedules a call to queue() to be executed after the specified delay.
default RestAction<T>
timeout(long timeout, TimeUnit unit)
Timeout for this RestAction instance.
default RestAction<List<T>>
zip(RestAction<? extends T> first, RestAction<? extends T>... other)
Accumulates this RestAction with the provided actions into a List.
* METHOD DETAILS
* SETPASSCONTEXT
static void setPassContext(boolean enable)
If enabled this will pass a ContextException as root-cause to all failure
consumers.
This might cause performance decrease due to the creation of exceptions
for every execution.
It is recommended to pass a context consumer as failure manually using
queue(success, ContextException.here(failure))
Parameters: enable - True, if context should be passed to all failure
consumers
* ISPASSCONTEXT
static boolean isPassContext()
Whether RestActions will use ContextException automatically to keep track
of the caller context.
If set to true this can cause performance drops due to the creation of
stack-traces on execution.
Returns: True, if RestActions will keep track of context automatically See
Also:
* setPassContext(boolean)
* SETDEFAULTFAILURE
static void setDefaultFailure(@Nullable Consumer<? super Throwable
> callback)
The default failure callback used when none is provided in queue(Consumer,
Consumer).
Parameters: callback - The fallback to use, or null to ignore failures
(not recommended)
* SETDEFAULTSUCCESS
static void setDefaultSuccess(@Nullable Consumer<Object> callback)
The default success callback used when none is provided in queue(Consumer,
Consumer) or queue(Consumer).
Parameters: callback - The fallback to use, or null to ignore success
* SETDEFAULTTIMEOUT
static void setDefaultTimeout(long timeout, @Nonnull TimeUnit unit)
Default timeout to apply to every RestAction.
This will use no timeout unless specified otherwise.
If the request doesn't get executed within the specified timeout it will
fail.
When a RestAction times out, it will fail with a TimeoutException.
Parameters: timeout - The default timeout to use unit - Unit for the
timeout value Throws: IllegalArgumentException - If the provided unit is
null
* GETDEFAULTTIMEOUT
static long getDefaultTimeout()
The default timeout to apply to every RestAction in milliseconds.
If no timeout has been configured, this will return 0.
When a RestAction times out, it will fail with a TimeoutException.
Returns: The default timeout in milliseconds, or 0
* GETDEFAULTFAILURE
@Nonnull static Consumer<? super Throwable> getDefaultFailure()
The default failure callback used when none is provided in queue(Consumer,
Consumer).
Returns: The fallback consumer
* GETDEFAULTSUCCESS
@Nonnull static Consumer<Object> getDefaultSuccess()
The default success callback used when none is provided in queue(Consumer,
Consumer) or queue(Consumer).
Returns: The fallback consumer
* ALLOF
@Nonnull @SafeVarargs @CheckReturnValue
static <E> RestAction<List<E>> allOf(@Nonnull RestAction<? extends
E> first, @Nonnull RestAction<? extends E>... others)
Creates a RestAction instance which accumulates all results of the
provided actions.
If one action fails, all others will be cancelled. To handle failures
individually instead of cancelling you can use mapToResult().
Type Parameters: E - The result type Parameters: first - The initial
RestAction starting point others - The remaining actions to accumulate
Returns: RestAction - Type: List of the results Throws:
IllegalArgumentException - If null is provided Since: 4.2.1 See Also:
* and(RestAction, BiFunction)
* zip(RestAction, RestAction[])
* ALLOF
@Nonnull @CheckReturnValue static <E> RestAction<List<E>> allOf(@Nonnull
Collection<? extends RestAction<? extends E>> actions)
Creates a RestAction instance which accumulates all results of the
provided actions.
If one action fails, all others will be cancelled. To handle failures
individually instead of cancelling you can use mapToResult().
Type Parameters: E - The result type Parameters: actions - Non-empty
collection of RestActions to accumulate Returns: RestAction - Type: List
of the results Throws: IllegalArgumentException - If null is provided or
the collection is empty Since: 4.2.1 See Also:
* and(RestAction, BiFunction)
* zip(RestAction, RestAction[])
* ACCUMULATE
@Nonnull @CheckReturnValue static <E, A, O> RestAction<O> accumulate(
@Nonnull Collection<? extends RestAction<? extends E>> actions, @Nonnull
Collector<? super E,A,? extends O> collector)
Creates a RestAction instance which accumulates all results of the
provided actions.
If one action fails, all others will be cancelled. To handle failures
individually instead of cancelling you can use mapToResult().
Type Parameters: E - The input type A - The accumulator type O - The
output type Parameters: actions - Non-empty collection of RestActions to
accumulate collector - The Collector to use Returns: RestAction - Type:
List of the results Throws: IllegalArgumentException - If null is provided
or the collection is empty Since: 4.2.1 See Also:
* and(RestAction, BiFunction)
* zip(RestAction, RestAction[])
* GETJDA
@Nonnull JDA getJDA()
The current JDA instance
Returns: The corresponding JDA instance
* SETCHECK
@Nonnull @CheckReturnValue RestAction<T> setCheck(@Nullable
BooleanSupplier checks)
Sets the last-second checks before finally executing the http request in
the queue.
If the provided supplier evaluates to false or throws an exception this
will not be finished. When an exception is thrown from the supplier it
will be provided to the failure callback.
Parameters: checks - The checks to run before executing the request, or
null to run no checks Returns: The current RestAction for chaining
convenience See Also:
* getCheck()
* addCheck(BooleanSupplier)
* GETCHECK
@Nullable default BooleanSupplier getCheck()
The current checks for this RestAction.
Returns: The current checks, or null if none were set Since: 4.2.1 See
Also:
* setCheck(BooleanSupplier)
* ADDCHECK
@Nonnull @CheckReturnValue default RestAction<T> addCheck(@Nonnull
BooleanSupplier checks)
Shortcut for setCheck(() -> getCheck().getAsBoolean() &&
checks.getAsBoolean()).
Parameters: checks - Other checks to run Returns: The current RestAction
for chaining convenience Throws: IllegalArgumentException - If the
provided checks are null Since: 4.2.1 See Also:
* setCheck(BooleanSupplier)
* TIMEOUT
@Nonnull @CheckReturnValue default RestAction<T> timeout(long timeout,
@Nonnull TimeUnit unit)
Timeout for this RestAction instance.
If the request doesn't get executed within the timeout it will fail.
When a RestAction times out, it will fail with a TimeoutException. This is
the same as deadline(System.currentTimeMillis() + unit.toMillis(timeout)).
Example
action.timeout(10, TimeUnit.SECONDS) // 10 seconds from now
.queueAfter(20, SECONDS); // request will not be executed within deadline and timeout immediately after 20 seconds
Parameters: timeout - The timeout to use unit - Unit for the timeout value
Returns: The same RestAction instance with the applied timeout Throws:
IllegalArgumentException - If the provided unit is null See Also:
* setDefaultTimeout(long, TimeUnit)
* DEADLINE
@Nonnull @CheckReturnValue default RestAction<T> deadline(long timestamp)
Similar to timeout(long, TimeUnit) but schedules a deadline at which the
request has to be completed.
If the deadline is reached, the request will fail with a TimeoutException.
This does not mean that the request will immediately timeout when the
deadline is reached. JDA will check the deadline right before executing
the request or within intervals in a worker thread. This only means the
request will timeout if the deadline has passed.
Example
action.deadline(System.currentTimeMillis() + 10000) // 10 seconds from now
.queueAfter(20, SECONDS); // request will not be executed within deadline and timeout immediately after 20 seconds
Parameters: timestamp - Millisecond timestamp at which the request will
timeout Returns: The same RestAction with the applied deadline See Also:
* timeout(long, TimeUnit)
* setDefaultTimeout(long, TimeUnit)
* QUEUE
default void queue()
Submits a Request for execution.
Using the default callback functions: setDefaultSuccess(Consumer) and
setDefaultFailure(Consumer)
To access the response you can use queue(java.util.function.Consumer) and
to handle failures use queue(java.util.function.Consumer,
java.util.function.Consumer).
This method is asynchronous
Example
public static void sendMessage(MessageChannel channel, String content)
{
// sendMessage returns "MessageAction" which is a specialization for "RestAction<Message>"
RestAction<Message> action = channel.sendMessage(content);
// call queue() to send the message off to discord.
action.queue();
}
Throws: RejectedExecutionException - If the requester has been shutdown by
JDA.shutdown() or JDA.shutdownNow() See Also:
* MessageChannel.sendMessage(CharSequence)
* queue(Consumer)
* queue(Consumer, Consumer)
* QUEUE
default void queue(@Nullable Consumer<? super T> success)
Submits a Request for execution.
Using the default failure callback function.
To handle failures use queue(java.util.function.Consumer,
java.util.function.Consumer).
This method is asynchronous
Example
public static void sendPrivateMessage(User user, String content)
{
// The "<PrivateChannel>" is the response type for the parameter in the success callback
RestAction<PrivateChannel> action = user.openPrivateChannel();
// "channel" is the identifier we use to access the channel of the response
// this is like the "user" we declared above, just a name for the function parameter
action.queue((channel) -> channel.sendMessage(content).queue());
}
Parameters: success - The success callback that will be called at a
convenient time for the API. (can be null) Throws:
RejectedExecutionException - If the requester has been shutdown by
JDA.shutdown() or JDA.shutdownNow() See Also:
* queue(Consumer, Consumer)
* QUEUE
void queue(@Nullable Consumer<? super T> success, @Nullable Consumer<?
super Throwable> failure)
Submits a Request for execution.
This method is asynchronous
Example
public static void sendPrivateMessage(JDA jda, String userId, String content)
{
// Retrieve the user by their id
RestAction<User> action = jda.retrieveUserById(userId);
action.queue(
// Handle success if the user exists
(user) -> user.openPrivateChannel().queue(
(channel) -> channel.sendMessage(content).queue()),
// Handle failure if the user does not exist (or another issue appeared)
(error) -> error.printStackTrace()
);
// Alternatively use submit() to remove nested callbacks
}
Parameters: success - The success callback that will be called at a
convenient time for the API. (can be null to use default) failure - The
failure callback that will be called if the Request encounters an
exception at its execution point. (can be null to use default) Throws:
RejectedExecutionException - If the requester has been shutdown by
JDA.shutdown() or JDA.shutdownNow() See Also:
* submit()
* ErrorHandler
* COMPLETE
@Blocking @UnknownNullability default T complete()
Blocks the current Thread and awaits the completion of an submit()
request.
Used for synchronous logic.
This might throw RuntimeExceptions
Returns: The response value Throws: RejectedExecutionException - If the
requester has been shutdown by JDA.shutdown() or JDA.shutdownNow()
IllegalStateException - If used within a queue(...) callback
* COMPLETE
@Blocking @UnknownNullability T complete(boolean shouldQueue) throws
RateLimitedException
Blocks the current Thread and awaits the completion of an submit()
request.
Used for synchronous logic.
Parameters: shouldQueue - Whether this should automatically handle rate
limitations (default true) Returns: The response value Throws:
RejectedExecutionException - If the requester has been shutdown by
JDA.shutdown() or JDA.shutdownNow() IllegalStateException - If used within
a queue(...) callback RateLimitedException - If we were rate limited and
the shouldQueue is false. Use complete() to avoid this Exception.
* SUBMIT
@Nonnull @CheckReturnValue default CompletableFuture<T> submit()
Submits a Request for execution and provides a CompletableFuture
representing its completion task.
Cancelling the returned Future will result in the cancellation of the
Request!
Example
public static void sendPrivateMessage(JDA jda, String userId, String content)
{
// Retrieve the user by their id
RestAction<User> action = jda.retrieveUserById(userId);
action.submit() // CompletableFuture<User>
// Handle success if the user exists
.thenCompose((user) -> user.openPrivateChannel().submit()) // CompletableFuture<PrivateChannel>
.thenCompose((channel) -> channel.sendMessage(content).submit()) // CompletableFuture<Void>
.whenComplete((v, error) -> {
// Handle failure if the user does not exist (or another issue appeared)
if (error != null) error.printStackTrace();
});
}
Returns: Never-null CompletableFuture representing the completion promise
Throws: RejectedExecutionException - If the requester has been shutdown by
JDA.shutdown() or JDA.shutdownNow()
* SUBMIT
@Nonnull @CheckReturnValue CompletableFuture<T> submit
(boolean shouldQueue)
Submits a Request for execution and provides a CompletableFuture
representing its completion task.
Cancelling the returned Future will result in the cancellation of the
Request!
Parameters: shouldQueue - Whether the Request should automatically handle
rate limitations. (default true) Returns: Never-null CompletableFuture
task representing the completion promise Throws:
RejectedExecutionException - If the requester has been shutdown by
JDA.shutdown() or JDA.shutdownNow()
* MAPTORESULT
@Nonnull @CheckReturnValue default RestAction<Result<T>> mapToResult()
Converts the success and failure callbacks into a Result.
This means the queue(Consumer, Consumer) failure consumer will never be
used. Instead, all results will be evaluated into a success consumer which
provides an instance of Result.
Result will either be successful or failed. This can be useful in
combination with allOf(Collection) to handle failed requests individually
for each action.
Note: You have to handle failures explicitly with this. You should use
Result.onFailure(Consumer), Result.getFailure(), or
Result.expect(Predicate)!
Returns: RestAction - Type: Result Since: 4.2.1
* MAP
@Nonnull @CheckReturnValue default <O> RestAction<O> map(@Nonnull Function
<? super T,? extends O> map)
Intermediate operator that returns a modified RestAction.
This does not modify this instance but returns a new RestAction which will
apply the map function on successful execution.
Example
public RestAction<String> retrieveMemberNickname(Guild guild, String userId) {
return guild.retrieveMemberById(userId)
.map(Member::getNickname);
}
Type Parameters: O - The target output type Parameters: map - The mapping
function to apply to the action result Returns: RestAction for the mapped
type Since: 4.1.1
* ONSUCCESS
@Nonnull @CheckReturnValue default RestAction<T> onSuccess(@Nonnull
Consumer<? super T> consumer)
An intermediate operator that returns a modified RestAction.
This does not modify this instance but returns a new RestAction, which
will consume the actions result using the given consumer on successful
execution. The resulting action continues with the previous result.
Example
public RestAction<String> retrieveMemberNickname(Guild guild, String userId) {
return guild.retrieveMemberById(userId)
.map(Member::getNickname)
.onSuccess(System.out::println);
}
Prefer using queue(Consumer) instead, if continuation of the action chain
is not desired.
Parameters: consumer - The consuming function to apply to the action
result, failures are propagated into the resulting action Returns:
RestAction that consumes the action result Throws:
IllegalArgumentException - If the consumer is null
* ONERRORMAP
@Nonnull @CheckReturnValue default RestAction<T> onErrorMap(@Nonnull
Function<? super Throwable,? extends T> map)
Supply a fallback value when the RestAction fails for any reason.
This does not modify this instance but returns a new RestAction which will
apply the map function on failed execution.
Example
public RestAction<String> sendMessage(User user, String content) {
return user.openPrivateChannel() // RestAction<PrivateChannel>
.flatMap((channel) -> channel.sendMessage(content)) // RestAction<Message>
.map(Message::getContentRaw) // RestAction<String>
.onErrorMap(Throwable::getMessage); // RestAction<String> (must be the same as above)
}
Parameters: map - The mapping function which provides the fallback value
to use Returns: RestAction with fallback handling Throws:
IllegalArgumentException - If the mapping function is null Since: 4.2.0
* ONERRORMAP
@Nonnull @CheckReturnValue default RestAction<T> onErrorMap(@Nullable
Predicate<? super Throwable> condition, @Nonnull Function<? super
Throwable,? extends T> map)
Supply a fallback value when the RestAction fails for a specific reason.
This does not modify this instance but returns a new RestAction which will
apply the map function on failed execution.
Example
public RestAction<String> sendMessage(User user, String content) {
return user.openPrivateChannel() // RestAction<PrivateChannel>
.flatMap((channel) -> channel.sendMessage(content)) // RestAction<Message>
.map(Message::getContentRaw) // RestAction<String>
.onErrorMap(CANNOT_SEND_TO_USER::test, Throwable::getMessage); // RestAction<String> (must be the same as above)
}
Parameters: condition - A condition that must return true to apply this
fallback map - The mapping function which provides the fallback value to
use Returns: RestAction with fallback handling Throws:
IllegalArgumentException - If the mapping function is null Since: 4.2.0
See Also:
* ErrorResponse.test(Throwable)
* ErrorResponse.test(ErrorResponse...)
* ONERRORFLATMAP
@Nonnull @CheckReturnValue default RestAction<T> onErrorFlatMap(@Nonnull
Function<? super Throwable,? extends RestAction<? extends T>> map)
Supply a fallback value when the RestAction fails for a any reason.
This does not modify this instance but returns a new RestAction which will
apply the map function on failed execution.
Example
public RestAction<Message> sendMessage(User user, TextChannel context, String content) {
return user.openPrivateChannel() // RestAction<PrivateChannel>
.flatMap((channel) -> channel.sendMessage(content)) // RestAction<Message>
.onErrorFlatMap(
(error) -> context.sendMessage("Failed to send direct message to " + user.getAsMention() + " Reason: " + error)
); // RestAction<Message> (must be the same as above)
}
Parameters: map - The mapping function which provides the fallback action
to use Returns: RestAction with fallback handling Throws:
IllegalArgumentException - If the mapping function is null Since: 4.2.0
* ONERRORFLATMAP
@Nonnull @CheckReturnValue default RestAction<T> onErrorFlatMap(@Nullable
Predicate<? super Throwable> condition, @Nonnull Function<? super
Throwable,? extends RestAction<? extends T>> map)
Supply a fallback value when the RestAction fails for a specific reason.
This does not modify this instance but returns a new RestAction which will
apply the map function on failed execution.
Example
public RestAction<Message> sendMessage(User user, TextChannel context, String content) {
return user.openPrivateChannel() // RestAction<PrivateChannel>
.flatMap((channel) -> channel.sendMessage(content)) // RestAction<Message>
.onErrorFlatMap(CANNOT_SEND_TO_USER::test,
(error) -> context.sendMessage("Cannot send direct message to " + user.getAsMention())
); // RestAction<Message> (must be the same as above)
}
Parameters: condition - A condition that must return true to apply this
fallback map - The mapping function which provides the fallback action to
use Returns: RestAction with fallback handling Throws:
IllegalArgumentException - If the mapping function is null Since: 4.2.0
See Also:
* ErrorResponse.test(Throwable)
* ErrorResponse.test(ErrorResponse...)
* FLATMAP
@Nonnull @CheckReturnValue default <O> RestAction<O> flatMap(@Nonnull
Function<? super T,? extends RestAction<O>> flatMap)
Intermediate operator that returns a modified RestAction.
This does not modify this instance but returns a new RestAction which will
apply the map function on successful execution. This will compute the
result of both RestActions.
The returned RestAction must not be null! To terminate the execution chain
on a specific condition you can use flatMap(Predicate, Function).
Example
public RestAction<Void> initializeGiveaway(Guild guild, String channelName) {
return guild.createTextChannel(channelName)
.addPermissionOverride(guild.getPublicRole(), null, EnumSet.of(Permission.MESSAGE_SEND)) // deny write for everyone
.addPermissionOverride(guild.getSelfMember(), EnumSet.of(Permission.MESSAGE_SEND), null) // allow for self user
.flatMap((channel) -> channel.sendMessage("React to enter giveaway!")) // send message
.flatMap((message) -> message.addReaction(REACTION)); // add reaction
}
Type Parameters: O - The target output type Parameters: flatMap - The
mapping function to apply to the action result, must return a RestAction
Returns: RestAction for the mapped type Since: 4.1.1
* FLATMAP
@Nonnull @CheckReturnValue default <O> RestAction<O> flatMap(@Nullable
Predicate<? super T> condition, @Nonnull Function<? super T,? extends
RestAction<O>> flatMap)
Intermediate operator that returns a modified RestAction.
This does not modify this instance but returns a new RestAction which will
apply the map function on successful execution. This will compute the
result of both RestActions.
The provided RestAction must not be null!
Example
private static final int MAX_COUNT = 1000;
public void updateCount(MessageChannel channel, String messageId, int count) {
channel.retrieveMessageById(messageId) // retrieve message for check
.map(Message::getContentRaw) // get content of the message
.map(Integer::parseInt) // convert it to an int
.flatMap(
(currentCount) -> currentCount + count <= MAX_COUNT, // Only edit if new count does not exceed maximum
(currentCount) -> channel.editMessageById(messageId, String.valueOf(currentCount + count)) // edit message
)
.map(Message::getContentRaw) // get content of the message
.map(Integer::parseInt) // convert it to an int
.queue((newCount) -> System.out.println("Updated count to " + newCount));
}
Type Parameters: O - The target output type Parameters: condition - A
condition predicate that decides whether to apply the flat map operator or
not flatMap - The mapping function to apply to the action result, must
return a RestAction Returns: RestAction for the mapped type Since: 4.1.1
See Also:
* flatMap(Function)
* map(Function)
* AND
@Nonnull @CheckReturnValue default <U, O> RestAction<O> and(@Nonnull
RestAction<U> other, @Nonnull BiFunction<? super T,? super U,? extends
O> accumulator)
Combines this RestAction with the provided action.
The result is computed by the provided BiFunction.
If one of the actions fails, the other will be cancelled. To handle
failures individually instead of cancelling you can use mapToResult().
Type Parameters: U - The type of the other action O - The result type
after applying the accumulator function Parameters: other - The action to
combine accumulator - BiFunction to compute the result Returns: Combined
RestAction Throws: IllegalArgumentException - If null is provided or you
tried to combine an action with itself Since: 4.2.1
* AND
@Nonnull @CheckReturnValue default <U> RestAction<Void> and(@Nonnull
RestAction<U> other)
Combines this RestAction with the provided action.
If one of the actions fails, the other will be cancelled. To handle
failures individually instead of cancelling you can use mapToResult().
Type Parameters: U - The type of the other action Parameters: other - The
action to combine Returns: Combined RestAction with empty result Throws:
IllegalArgumentException - If null is provided or you tried to combine an
action with itself Since: 4.2.1
* ZIP
@Nonnull @CheckReturnValue default RestAction<List<T>> zip(@Nonnull
RestAction<? extends T> first, @Nonnull RestAction<? extends T>... other)
Accumulates this RestAction with the provided actions into a List.
If one of the actions fails, the others will be cancelled. To handle
failures individually instead of cancelling you can use mapToResult().
Parameters: first - The first other action to accumulate into the list
other - The other actions to accumulate into the list Returns: Combined
RestAction with empty result Throws: IllegalArgumentException - If null is
provided or you tried to combine an action with itself Since: 4.2.1 See
Also:
* allOf(RestAction, RestAction[])
* and(RestAction, BiFunction)
* DELAY
@Nonnull @CheckReturnValue default RestAction<T> delay(@Nonnull Duration
duration)
Intermediate operator that returns a modified RestAction.
This does not modify this instance but returns a new RestAction which will
delay its result by the provided delay.
Example
public RestAction<Void> selfDestruct(MessageChannel channel, String content) {
return channel.sendMessage("The following message will destroy itself in 1 minute!")
.delay(Duration.ofSeconds(10)) // edit 10 seconds later
.flatMap((it) -> it.editMessage(content))
.delay(Duration.ofMinutes(1)) // delete 1 minute later
.flatMap(Message::delete);
}
Parameters: duration - The delay Returns: RestAction with delay Since:
4.1.1 See Also:
* queueAfter(long, TimeUnit)
* DELAY
@Nonnull @CheckReturnValue default RestAction<T> delay(@Nonnull Duration
duration, @Nullable ScheduledExecutorService scheduler)
Intermediate operator that returns a modified RestAction.
This does not modify this instance but returns a new RestAction which will
delay its result by the provided delay.
Example
public RestAction<Void> selfDestruct(MessageChannel channel, String content) {
return channel.sendMessage("The following message will destroy itself in 1 minute!")
.delay(Duration.ofSeconds(10), scheduler) // edit 10 seconds later
.flatMap((it) -> it.editMessage(content))
.delay(Duration.ofMinutes(1), scheduler) // delete 1 minute later
.flatMap(Message::delete);
}
Parameters: duration - The delay scheduler - The scheduler to use, null to
use JDA.getRateLimitPool() Returns: RestAction with delay Since: 4.1.1 See
Also:
* queueAfter(long, TimeUnit, ScheduledExecutorService)
* DELAY
@Nonnull @CheckReturnValue default RestAction<T> delay(long delay,
@Nonnull TimeUnit unit)
Intermediate operator that returns a modified RestAction.
This does not modify this instance but returns a new RestAction which will
delay its result by the provided delay.
Example
public RestAction<Void> selfDestruct(MessageChannel channel, String content) {
return channel.sendMessage("The following message will destroy itself in 1 minute!")
.delay(10, SECONDS) // edit 10 seconds later
.flatMap((it) -> it.editMessage(content))
.delay(1, MINUTES) // delete 1 minute later
.flatMap(Message::delete);
}
Parameters: delay - The delay value unit - The time unit for the delay
value Returns: RestAction with delay Since: 4.1.1 See Also:
* queueAfter(long, TimeUnit)
* DELAY
@Nonnull @CheckReturnValue default RestAction<T> delay(long delay,
@Nonnull TimeUnit unit, @Nullable ScheduledExecutorService scheduler)
Intermediate operator that returns a modified RestAction.
This does not modify this instance but returns a new RestAction which will
delay its result by the provided delay.
Example
public RestAction<Void> selfDestruct(MessageChannel channel, String content) {
return channel.sendMessage("The following message will destroy itself in 1 minute!")
.delay(10, SECONDS, scheduler) // edit 10 seconds later
.flatMap((it) -> it.editMessage(content))
.delay(1, MINUTES, scheduler) // delete 1 minute later
.flatMap(Message::delete);
}
Parameters: delay - The delay value unit - The time unit for the delay
value scheduler - The scheduler to use, null to use JDA.getRateLimitPool()
Returns: RestAction with delay Since: 4.1.1 See Also:
* queueAfter(long, TimeUnit, ScheduledExecutorService)
* SUBMITAFTER
@Nonnull @CheckReturnValue default DelayedCompletableFuture<T> submitAfter
(long delay, @Nonnull TimeUnit unit)
Schedules a call to queue() to be executed after the specified delay.
This is an asynchronous operation that will return a CompletableFuture
representing the task.
Similar to queueAfter(long, TimeUnit) but does not require callbacks to be
passed. Continuations of CompletableFuture can be used instead.
The global JDA RateLimit ScheduledExecutorService is used for this
operation.
You can provide your own Executor using submitAfter(long,
java.util.concurrent.TimeUnit,
java.util.concurrent.ScheduledExecutorService)!
Parameters: delay - The delay after which this computation should be
executed, negative to execute immediately unit - The TimeUnit to convert
the specified delay Returns: DelayedCompletableFuture representing the
delayed operation Throws: IllegalArgumentException - If the provided
TimeUnit is null
* SUBMITAFTER
@Nonnull @CheckReturnValue default DelayedCompletableFuture<T> submitAfter
(long delay, @Nonnull TimeUnit unit, @Nullable
ScheduledExecutorService executor)
Schedules a call to queue() to be executed after the specified delay.
This is an asynchronous operation that will return a CompletableFuture
representing the task.
Similar to queueAfter(long, TimeUnit) but does not require callbacks to be
passed. Continuations of CompletableFuture can be used instead.
The specified ScheduledExecutorService is used for this operation.
Parameters: delay - The delay after which this computation should be
executed, negative to execute immediately unit - The TimeUnit to convert
the specified delay executor - The ScheduledExecutorService that should be
used to schedule this operation, or null to use the default Returns:
DelayedCompletableFuture representing the delayed operation Throws:
IllegalArgumentException - If the provided TimeUnit is null
* COMPLETEAFTER
@Blocking @UnknownNullability default T completeAfter(long delay, @Nonnull
TimeUnit unit)
Blocks the current Thread for the specified delay and calls complete()
when delay has been reached.
If the specified delay is negative this action will execute immediately.
(see: TimeUnit.sleep(long))
Parameters: delay - The delay after which to execute a call to complete()
unit - The TimeUnit which should be used (this will use unit.sleep(delay))
Returns: The response value Throws: IllegalArgumentException - If the
specified TimeUnit is null RuntimeException - If the sleep operation is
interrupted
* QUEUEAFTER
@Nonnull default ScheduledFuture<?> queueAfter(long delay, @Nonnull
TimeUnit unit)
Schedules a call to queue() to be executed after the specified delay.
This is an asynchronous operation that will return a ScheduledFuture
representing the task.
This operation gives no access to the response value.
Use queueAfter(long, java.util.concurrent.TimeUnit,
java.util.function.Consumer) to access the success consumer for
queue(java.util.function.Consumer)!
The global JDA ScheduledExecutorService is used for this operation.
You can provide your own Executor with queueAfter(long,
java.util.concurrent.TimeUnit,
java.util.concurrent.ScheduledExecutorService)
Parameters: delay - The delay after which this computation should be
executed, negative to execute immediately unit - The TimeUnit to convert
the specified delay Returns: ScheduledFuture representing the delayed
operation Throws: IllegalArgumentException - If the provided TimeUnit is
null
* QUEUEAFTER
@Nonnull default ScheduledFuture<?> queueAfter(long delay, @Nonnull
TimeUnit unit, @Nullable Consumer<? super T> success)
Schedules a call to queue(java.util.function.Consumer) to be executed
after the specified delay.
This is an asynchronous operation that will return a ScheduledFuture
representing the task.
This operation gives no access to the failure callback.
Use queueAfter(long, java.util.concurrent.TimeUnit,
java.util.function.Consumer, java.util.function.Consumer) to access the
failure consumer for queue(java.util.function.Consumer,
java.util.function.Consumer)!
The global JDA ScheduledExecutorService is used for this operation.
You can provide your own Executor with queueAfter(long,
java.util.concurrent.TimeUnit, java.util.function.Consumer,
java.util.concurrent.ScheduledExecutorService)
Parameters: delay - The delay after which this computation should be
executed, negative to execute immediately unit - The TimeUnit to convert
the specified delay success - The success Consumer that should be called
once the queue(java.util.function.Consumer) operation completes
successfully. Returns: ScheduledFuture representing the delayed operation
Throws: IllegalArgumentException - If the provided TimeUnit is null
* QUEUEAFTER
@Nonnull default ScheduledFuture<?> queueAfter(long delay, @Nonnull
TimeUnit unit, @Nullable Consumer<? super T> success, @Nullable Consumer<?
super Throwable> failure)
Schedules a call to queue(java.util.function.Consumer,
java.util.function.Consumer) to be executed after the specified delay.
This is an asynchronous operation that will return a ScheduledFuture
representing the task.
The global JDA ScheduledExecutorService is used for this operation.
You provide your own Executor with queueAfter(long,
java.util.concurrent.TimeUnit, java.util.function.Consumer,
java.util.function.Consumer,
java.util.concurrent.ScheduledExecutorService)
Parameters: delay - The delay after which this computation should be
executed, negative to execute immediately unit - The TimeUnit to convert
the specified delay success - The success Consumer that should be called
once the queue(java.util.function.Consumer, java.util.function.Consumer)
operation completes successfully. failure - The failure Consumer that
should be called in case of an error of the
queue(java.util.function.Consumer, java.util.function.Consumer) operation.
Returns: ScheduledFuture representing the delayed operation Throws:
IllegalArgumentException - If the provided TimeUnit is null See Also:
* ErrorHandler
* QUEUEAFTER
@Nonnull default ScheduledFuture<?> queueAfter(long delay, @Nonnull
TimeUnit unit, @Nullable ScheduledExecutorService executor)
Schedules a call to queue() to be executed after the specified delay.
This is an asynchronous operation that will return a ScheduledFuture
representing the task.
This operation gives no access to the response value.
Use queueAfter(long, java.util.concurrent.TimeUnit,
java.util.function.Consumer) to access the success consumer for
queue(java.util.function.Consumer)!
The specified ScheduledExecutorService is used for this operation.
Parameters: delay - The delay after which this computation should be
executed, negative to execute immediately unit - The TimeUnit to convert
the specified delay executor - The Non-null ScheduledExecutorService that
should be used to schedule this operation Returns: ScheduledFuture
representing the delayed operation Throws: IllegalArgumentException - If
the provided TimeUnit or ScheduledExecutorService is null
* QUEUEAFTER
@Nonnull default ScheduledFuture<?> queueAfter(long delay, @Nonnull
TimeUnit unit, @Nullable Consumer<? super T> success, @Nullable
ScheduledExecutorService executor)
Schedules a call to queue(java.util.function.Consumer) to be executed
after the specified delay.
This is an asynchronous operation that will return a ScheduledFuture
representing the task.
This operation gives no access to the failure callback.
Use queueAfter(long, java.util.concurrent.TimeUnit,
java.util.function.Consumer, java.util.function.Consumer) to access the
failure consumer for queue(java.util.function.Consumer,
java.util.function.Consumer)!
The specified ScheduledExecutorService is used for this operation.
Parameters: delay - The delay after which this computation should be
executed, negative to execute immediately unit - The TimeUnit to convert
the specified delay success - The success Consumer that should be called
once the queue(java.util.function.Consumer) operation completes
successfully. executor - The Non-null ScheduledExecutorService that should
be used to schedule this operation Returns: ScheduledFuture representing
the delayed operation Throws: IllegalArgumentException - If the provided
TimeUnit or ScheduledExecutorService is null
* QUEUEAFTER
@Nonnull default ScheduledFuture<?> queueAfter(long delay, @Nonnull
TimeUnit unit, @Nullable Consumer<? super T> success, @Nullable Consumer<?
super Throwable> failure, @Nullable ScheduledExecutorService executor)
Schedules a call to queue(java.util.function.Consumer,
java.util.function.Consumer) to be executed after the specified delay.
This is an asynchronous operation that will return a ScheduledFuture
representing the task.
The specified ScheduledExecutorService is used for this operation.
Parameters: delay - The delay after which this computation should be
executed, negative to execute immediately unit - The TimeUnit to convert
the specified delay success - The success Consumer that should be called
once the queue(java.util.function.Consumer, java.util.function.Consumer)
operation completes successfully. failure - The failure Consumer that
should be called in case of an error of the
queue(java.util.function.Consumer, java.util.function.Consumer) operation.
executor - The Non-null ScheduledExecutorService that should be used to
schedule this operation Returns: ScheduledFuture representing the delayed
operation Throws: IllegalArgumentException - If the provided TimeUnit or
ScheduledExecutorService is null See Also:
* ErrorHandler