Package net.dv8tion.jda.api.requests

Interface RestAction<T>

Type Parameters:
T - The generic response type for this RestAction
All Known Subinterfaces:
AccountManager, AudioChannelManager<T,M>, AuditableRestAction<T>, AuditLogPaginationAction, AutoCompleteCallbackAction, BaseGuildMessageChannelManager<T,M>, CategoryManager, CategoryOrderAction, ChannelAction<T>, ChannelManager<T,M>, ChannelOrderAction, CommandCreateAction, CommandEditAction, CommandListUpdateAction, EmoteManager, GuildAction, GuildManager, ICategorizableChannelManager<T,M>, InteractionCallbackAction<T>, InviteAction, IPermissionContainerManager<T,M>, IPositionableChannelManager<T,M>, Manager<M>, MemberAction, MessageAction, MessageEditCallbackAction, MessagePaginationAction, NewsChannelManager, OrderAction<T,M>, PaginationAction<T,M>, PermissionOverrideAction, PermOverrideManager, ReactionPaginationAction, ReplyCallbackAction, RoleAction, RoleManager, RoleOrderAction, StageChannelManager, StageInstanceAction, StageInstanceManager, StoreChannelManager, TemplateManager, TextChannelManager, ThreadChannelAction, ThreadChannelManager, ThreadChannelPaginationAction, VoiceChannelManager, WebhookAction, WebhookManager, WebhookMessageAction<T>, WebhookMessageUpdateAction<T>
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:

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: