Package net.dv8tion.jda.api.utils

Interface SessionController

All Known Implementing Classes:
ConcurrentSessionController, SessionControllerAdapter
public interface SessionController
Controls states and behaviour of one or multiple JDA instances.
One instance of this should be used when sharding a bot account in order to keep track of session information between shards.

The SessionControllerAdapter provides a default implementation that can be extended and overridden.

States & Behaviour
Identify Ratelimit Handling
This will enable handling of (re-)connecting gateway sessions.

Global REST Ratelimit
The global REST ratelimit is not bound to a single session and should be handled on all JDA instances. This controller will receive updates of this ratelimit through setGlobalRatelimit(long) and should report the last ratelimit information it received through getGlobalRatelimit().

Gateway Provider
This provider can be used to change the gateway retrieval (using cache, http, or static) and allows to set a custom gateway endpoint. Use carefully.

Examples
Using JDABuilder 


 JDABuilder builder = JDABuilder.createDefault(BOT_TOKEN);
 builder.setSessionController(new SessionControllerAdapter() {
     @Override
     public void appendSession(SessionConnectNode node) {
         System.out.println("[SessionController] Adding SessionConnectNode to Queue!");
         super.appendSession(node);
     }
 });
 builder.addEventListeners(myListener);
 for (int i = 0; i < 10; i++) {
     builder.useSharding(i, 10).build();
 }

Using ShardManager 


 DefaultShardManagerBuilder builder = DefaultShardManagerBuilder.createDefault(BOT_TOKEN);
 builder.setSessionController(new SessionControllerAdapter() {
     @Override
     public Pair<String, Integer> getGatewayBot(JDA api) {
         return Pair.of(getGateway(), 10);
     }
 });
 builder.addEventListeners(myListener);
 builder.build();

  • Field Details

  • Method Details

    • setConcurrency

      default void setConcurrency(int level)
      Apply the max_concurrency for this bot. This property is only useful for very large bots which get access to higher concurrency when starting their shards.

      Currently, there are 3 different levels of concurrency 1, 16, and 64. The concurrency means the bot can connect multiple shards at once without hitting the IDENTIFY rate-limit. This works by applying the concurrency level as a modulo operand to the shard id: shard_id % concurrency. We use one thread per bucket in this implementation.

      An implementation of this interface is not required to use this concurrency level. SessionControllerAdapter does not support this due to backwards compatibility.

      Parameters:
      level - The concurrency level
      Throws:
      AssertionError - If the provided level is not a valid array length size
      Since:
      4.2.0

    • appendSession

      void appendSession(@Nonnull SessionController.SessionConnectNode node)
      Called by a JDA session when a WebSocket should be started. (Connecting and Reconnecting)
      This should only add the node to a queue and execute the queue with respect to the IDENTIFY_DELAY.
      Parameters:
      node - The SessionConnectNode

    • removeSession

      void removeSession(@Nonnull SessionController.SessionConnectNode node)
      Called by a JDA session when a shutdown has been requested.
      When this happened the SessionConnectNode.run(boolean) will be a no-op and does not contribute to the IDENTIFY_DELAY.
      Parameters:
      node - The SessionConnectNode to remove from the queue.

    • getGlobalRatelimit

      @Deprecated @ForRemoval(deadline="5.0.0") @ReplaceWith("getRateLimitHandle().getClassic()") default long getGlobalRatelimit()
      Deprecated.
      Use getRateLimitHandle() instead
      Provides the cross-session global REST ratelimit it received through setGlobalRatelimit(long).
      Returns:
      The current global REST ratelimit or -1 if unset

    • setGlobalRatelimit

      @Deprecated @ForRemoval(deadline="5.0.0") @ReplaceWith("getRateLimitHandle().getClassic()") default void setGlobalRatelimit(long ratelimit)
      Deprecated.
      Use getRateLimitHandle() instead
      Called by the RateLimiter if the global rest ratelimit has changed.
      Parameters:
      ratelimit - The new global ratelimit

    • getRateLimitHandle

      @Nonnull default RestRateLimiter.GlobalRateLimit getRateLimitHandle()
      The store for global rate-limits of all types.
      This can be used to share the global rate-limit information between shards on the same IP.
      Returns:
      The global rate-limiter

    • getGateway

      @Nonnull default String getGateway()
      Discord's gateway URL, which is used to receive events.

      Called by JDA when starting a new gateway session (Connecting, Reconnecting).

      Returns:
      The gateway endpoint

    • getShardedGateway

      @Nonnull SessionController.ShardedGateway getShardedGateway(@Nonnull JDA api)
      Called by DefaultShardManager when a new shards is starting.
      Should provide a SessionController.ShardedGateway with (gateway, shardTotal).
      Parameters:
      api - The current JDA instance (used for RestActions and ShardInfo)
      Returns:
      The ShardedGateway instance consisting of the gateway endpoint to connect to and the shardTotal
      See Also: