net.dv8tion.jda.core.requests

Class RestAction<T>

java.lang.Object

net.dv8tion.jda.core.requests.RestAction<T>

Type Parameters:

T - The generic response type for this RestAction

Direct Known Subclasses:

ApplicationAction, ChannelAction, InviteAction, OrderAction, PermissionOverrideAction, RestAction.EmptyRestAction, RoleAction, WebhookAction

public abstract class RestAction<T>
extends java.lang.Object

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.

Since:

3.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RestAction.EmptyRestAction<T> Specialized form of RestAction that is used to provide information that has already been retrieved or generated so that another request does not need to be made to Discord.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.function.Consumer<java.lang.Throwable>	DEFAULT_FAILURE
static java.util.function.Consumer	DEFAULT_SUCCESS
static SimpleLog	LOG

Constructor Summary

Constructors

Constructor and Description
RestAction(JDA api, Route.CompiledRoute route, java.lang.Object data) Creates a new RestAction instance

Method Summary

Modifier and Type	Method and Description
T	block() Deprecated. use complete(boolean) instead!
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.
JDA	getJDA() The current JDA instance
void	queue() Submits a Request for execution.
void	queue(java.util.function.Consumer<T> success) Submits a Request for execution.
void	queue(java.util.function.Consumer<T> success, java.util.function.Consumer<java.lang.Throwable> failure) Submits a Request for execution.
java.util.concurrent.Future<T>	submit() Submits a Request for execution and provides an Future representing its completion task.
java.util.concurrent.Future<T>	submit(boolean shouldQueue) Submits a Request for execution and provides an Future representing its completion task.

Methods inherited from class java.lang.Object

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

Field Detail

LOG

public static final SimpleLog LOG

DEFAULT_SUCCESS

public static java.util.function.Consumer DEFAULT_SUCCESS

DEFAULT_FAILURE

public static java.util.function.Consumer<java.lang.Throwable> DEFAULT_FAILURE

Constructor Detail

RestAction

public RestAction(JDA api,
                  Route.CompiledRoute route,
                  java.lang.Object data)

Creates a new RestAction instance

Parameters:

api - The current JDA instance

route - The Route.CompiledRoute to be used for rate limit handling

data - The data that should be sent to the specified route. (can be null)

Method Detail

getJDA

public JDA getJDA()

The current JDA instance

Returns:

The corresponding JDA instance

queue

public void queue()

Submits a Request for execution.
Using the default callback functions: DEFAULT_SUCCESS and DEFAULT_FAILURE

This method is asynchronous

queue

public void queue(java.util.function.Consumer<T> success)

Submits a Request for execution.
Using the default failure callback function.

This method is asynchronous

Parameters:

success - The success callback that will be called at a convenient time for the API. (can be null)

queue

public void queue(java.util.function.Consumer<T> success,
                  java.util.function.Consumer<java.lang.Throwable> failure)

Submits a Request for execution.

This method is asynchronous

Parameters:

success - The success callback that will be called at a convenient time for the API. (can be null)

failure - The failure callback that will be called if the Request encounters an exception at its execution point.

submit

public java.util.concurrent.Future<T> submit()

Submits a Request for execution and provides an Future representing its completion task.
Cancelling the returned Future will result in the cancellation of the Request!

Returns:

Never-null Future task representing the completion promise

submit

public java.util.concurrent.Future<T> submit(boolean shouldQueue)

Submits a Request for execution and provides an Future 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 Future task representing the completion promise

complete

public T complete()

Blocks the current Thread and awaits the completion of an submit() request.
Used for synchronous logic.

This might throw RuntimeExceptions

Returns:

The never-null response value

complete

public 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 never-null response value

Throws:

RateLimitedException - If we were rate limited and the shouldQueue is false
Use complete() to avoid this Exception.

block

@Deprecated
public T block()
                     throws RateLimitedException

Deprecated. use complete(boolean) instead!

Returns:

The never-null response value

Throws:

RateLimitedException - If the request was ratelimited.