JDA (Java Discord API)

Add the JDA dependency to your build.gradle file. Ensure you use the latest version from Maven Central. You can optionally exclude opus-java and tink to reduce the JAR size if you do not require audio encoding or encryption.

repositories {
    mavenCentral()
}

dependencies {
    implementation("net.dv8tion:JDA:$version") { // replace $version with the latest version
      // Optionally disable audio natives to reduce jar size by excluding `opus-java` and `tink`
      // Gradle DSL:
      // exclude module: 'opus-java' // required for encoding audio into opus, not needed if audio is already provided in opus encoding
      // exclude module: 'tink' // required for encrypting and decrypting audio
      // Kotlin DSL:
      // exclude(module="opus-java") // required for encoding audio into opus, not needed if audio is already provided in opus encoding
      // exclude(module="tink") // required for encrypting and decrypting audio
    }
}

Add the JDA dependency to your pom.xml. You can optionally exclude opus-java and tink to reduce the JAR size if you do not require audio encoding or encryption.

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>$version</version> <!-- replace $version with the latest version -->
    <!-- Optionally disable audio natives to reduce jar size by excluding `opus-java` and `tink` -->
    <exclusions>
        <!-- required for encoding audio into opus, not needed if audio is already provided in opus encoding
        <exclusion>
            <groupId>club.minnced</groupId>
            <artifactId>opus-java</artifactId>
        </exclusion> -->
        <!-- required for encrypting and decrypting audio
        <exclusion>
            <groupId>com.google.crypto.tink</groupId>
            <artifactId>tink</artifactId>
        </exclusion> -->
    </exclusions>
</dependency>

To implement the Mixin pattern, follow this structure:

1. Public Interface: Define the API exposed to the user (e.g., getName(), updateName()).
2. Internal Mixin: An interface that extends the public interface. It uses generics (e.g., SomeEntityMixin<T extends SomeEntityMixin<T>>) to allow fluent state accessors. It provides default implementations for the public interface methods by utilizing State Accessors and Mixin Hooks.
3. Concrete Implementation: The actual class that implements the Mixin. It holds the private state and provides the actual logic for the State Accessors and Mixin Hooks.

Example Implementation

// Publicly exposed entity api interface
public interface SomeEntity {
    String getName();
    
    default String getNameTwice() {
      return getName() + "-" + getName();
    }

    RestAction<Void> updateName(String name);
}

// Internal mixin for that entity for code reuse and state exposing
public interface SomeEntityMixin<T extends SomeEntityMixin<T>> extends SomeEntity {
    //---- Default implementations of interface ----
    @Override
    default RestAction<Void> updateName(String name) {
        checkCanModifyEntity();
        
        Route.CompiledRoute route = Route.custom(Method.POST, "/someEntity/name/");
        return new RestActionImpl<>(route);
    }
    
    //---- State Accessors ----
    T setName(String name);
    
    //---- Mixin Hooks -----
    void checkCanModifyEntity();
}

// Internal concrete implementation of the entity
public class SomeEntityImpl implements SomeEntityMixin<SomeEntityImpl> {
    private String name;
    
    public SomeEntityImpl() {}
    
    @Override
    public String getName() {
        return name;
    }
    
    @Override
    public SomeEntityImpl setName(String name) {
        this.name = name;
    }
    
    @Override
    public void checkCanModifyEntity() {
        // Do some check here, throw if check is bad!
    }
}

//Publicly exposed entity api interface
public interface SomeEntity {
    String getName();
    
    default String getNameTwice() {
      return getName() + "-" + getName();
    }

    RestAction<Void> updateName(String name);
}

//Internal mixin for that entity for code reuse and state exposing
public interface SomeEntityMixin<T extends SomeEntityMixin<T>> extends SomeEntity {
    //---- Default implementations of interface ----
    @Override
    default RestAction<Void> updateName(String name) {
        checkCanModifyEntity();
        
        Route.CompiledRoute route = Route.custom(Method.POST, "/someEntity/name/");
        return new RestActionImpl<>(route);
    }
    
    //---- State Accessors ----
    T setName(String name);
    
    //---- Mixin Hooks -----
    void checkCanModifyEntity();
}

//Internal concrete implementation of the entity
public class SomeEntityImpl implements SomeEntityMixin<SomeEntityImpl> {
    private String name;
    
    public SomeEntityImpl() {}
    
    @Override
    public String getName() {
        return name;
    }
    
    @Override
    public SomeEntityImpl setName(String name) {
        this.name = name;
    }
    
    @Override
    public void checkCanModifyEntity() {
        //Do some check here, throw if check is bad!
    }
}

Slash commands use interactions and do not require specific gateway intents. You can register commands globally using jda.updateCommands(). To handle commands, extend ListenerAdapter and override onSlashCommandInteraction. Use .queue() to execute RestActions.

public static void main(String[] args) {
  JDA jda = JDABuilder.createLight(token, Collections.emptyList())
      .addEventListeners(new SlashCommandListener())
      .build();

  // Register your commands to make them visible globally on Discord:

  CommandListUpdateAction commands = jda.updateCommands();

  // Add all your commands on this action instance
  commands.addCommands(
    Commands.slash("say", "Makes the bot say what you tell it to")
      .addOption(STRING, "content", "What the bot should say", true), // Accepting a user input
    Commands.slash("leave", "Makes the bot leave the server")
      .setContexts(InteractionContextType.GUILD) // this doesn't make sense in DMs
      .setDefaultPermissions(DefaultMemberPermissions.DISABLED) // only admins should be able to use this command.
  );

  // Then finally send your commands to discord using the API
  commands.queue();
}

public class SlashCommandListener extends ListenerAdapter {
  @Override
  public void onSlashCommandInteraction(SlashCommandInteractionEvent event) {
    switch (event.getName()) {
      case "say" -> {
        String content = event.getOption("content", OptionMapping::getAsString);
        event.reply(content).queue();
      }
      case "leave" -> {
        event.reply("I'm leaving the server now!")
          .setEphemeral(true) // this message is only visible to the command user
          .flatMap(m -> event.getGuild().leave()) // append a follow-up action using flatMap
          .queue(); // enqueue both actions to run in sequence (send message -> leave guild)
      }
    }
  }
}

When defining an internal Mixin, use the following components to provide default logic for the public interface:

• State Accessors: Methods defined in the Mixin that provide access to the underlying state in the concrete implementation. They are used by default methods to perform logic or to expose internal setters/getters (like setName or getConnectedMembersMap) to the library without exposing them to the end-user.
• Mixin Hooks: Methods that must be implemented by the concrete class to provide necessary information or validation for the Mixin's default logic, but which do not necessarily map directly to a single piece of state (e.g., checkCanModifyEntity()).
• Default Implementations of Interface: The default methods in the Mixin that use State Accessors and Mixin Hooks to implement the public API. Note that basic getters that map directly to a field (e.g., int getBitrate()) cannot be implemented in the Mixin and must be implemented in the concrete class.

The RestAction interface is a lazy request builder used for all API endpoints. You chain builder methods to configure the request, but the request is not sent until you call a terminal method like .queue().

Common Operators

To avoid callback hell, RestAction supports several functional operators:

• map: Convert the result of the RestAction to a different value.
• flatMap: Chain another RestAction based on the result.
• delay: Delay the execution of the next step.

Combinators

• and: Runs another RestAction in parallel, requiring it to complete successfully.
• allOf: Accumulates a collection of many actions into one.
• zip: Similar to and, but combines results into a list.

Configurators

• timeout(long, TimeUnit) / deadline(long): Sets how long the action can stay in the queue before being cancelled.
• setCheck(BooleanSupplier): Runs a check immediately before the request is sent.
• reason(String): Sets the audit log reason for the action.

channel.sendMessage("Hello Friend!")
  .addFiles(FileUpload.fromData(greetImage))
  .queue(); // Sends the request asynchronously