7) Using RestAction

What is a RestAction?

In JDA 3.0 we introduced the new RestAction class which basically is a terminal between the JDA user and the Discord REST API.
The RestAction is a step between specifying what the user wants to do and executing it, it allows the user to specify how JDA should deal with their Request.

However this only works if you actually tell the RestAction to do something. That is why we recommend checking out whether or not something in JDA returns a RestAction. If that is the case you have to execute it using one of the RestAction execution operations:

• queue(), queue(Consumer), queue(Consumer, Consumer)
  These operations are asynchronous and will not execute within the same Thread.
  This means that you cannot use procedural logic when you use queue(), unless you use the callback Consumers.
• complete()
  This operation will block the current Thread until the request has been finished and will return the response type.

Note: We recommend using queue() when possible as blocking the current Thread can cause downtime and will use more resources.

JavaDocs: http://home.dv8tion.net:8080/job/JDA/javadoc/net/dv8tion/jda/core/requests/RestAction.html

Using queue()

The most common way to execute a RestAction is by simply calling .queue() after the operation: Example:

public void sendMessage(MessageChannel channel, String message) 
{
    channel.sendMessage(message).queue();
}

This will always simply execute the RestAction<Message> which was returned by MessageChannel.sendMessage(String).
Note that this might happen after calling sendMessage(MessageChannel, String) because queue() is asynchronous!

You: Why can't I access the Message that was sent with queue()?
Minn: Use the success callback!

Is one of the common conversations we had when people started using JDA 3.0.

You: What does that mean?

A success callback is what we call the primary Consumer that can be passed to a queue() statement:

public void sendAndLog(MessageChannel channel, String message) 
{
    channel.sendMessage(message).queue(new Consumer<Message>()
    {
        @Override
        public void accept(Message t)
        {
            System.out.printf("Sent Message %s\n", t);
        }
    });
}

Here we used an inline implementation of Consumer<Message> that handles the response of a REST Request.
The method Consumer.accept(Message) is automatically called once the response has been received by the JDA Requester.

Minn: But that looks really ugly...
You: Yeah but it works!!

Since JDA requires you to use Java 1.8 we can use one of the new features: Lambda Expressions

public void sendAndLog(MessageChannel channel, String message)
{
    // Here we use a lambda expressions which names the callback parameter -response- and uses that as a reference
    // in the callback body -System.out.printf("Sent Message %s", response)-
    Consumer<Message> callback = (response) -> System.out.printf("Sent Message %s", response);
    channel.sendMessage(message).queue(callback); // ^ calls that
}

You: Wow that looks so much better!
Minn: Yes, please learn more about lambda expressions: lambda quickstart

Using complete()

The complete() operation is simply for your convenience. It will block the Thread that you call it on which means it will not be able to continue with other tasks in the meantime.
If you don't use the return value and don't need the request to be completed before continuing with other operations it is recommended to use queue() instead!

Examples

public Message sendAndLog(MessageChannel channel, String message)
{
    Message response = channel.sendMessage(message).complete();
    System.out.printf("Sent Message %s", response);
    return response;
}

public Message getMessage(MessageChannel channel, String messageId)
{
    // messageMap is a HashMap<String, Message> instance that caches messages
    return messageMap.computIfAbsent(messageId, (key) -> channel.getMessageById(messageId).complete())
}

Using completeAfter and queueAfter

Coming Soon.