The ShardManager interface manages multiple JDA shards, providing a unified API to interact with all shards simultaneously.
What is Sharding?
Sharding splits your bot across multiple gateway connections, which is required for bots in 2,500+ guilds. Each shard handles a subset of guilds.
Getting Started
Create a ShardManager using DefaultShardManagerBuilder:
ShardManager shardManager = DefaultShardManagerBuilder
.createDefault("YOUR_BOT_TOKEN")
.build();
getShardsTotal
Gets the total number of managed shards.
Total number of shards (running + queued)
getShardsRunning
Gets the number of currently running shards.
default int getShardsRunning()
getShardsQueued
Gets the number of shards queued for connection.
Number of shards waiting to connect
Shard Access
getShardById
Retrieves a specific shard by ID.
JDA getShardById(int id)
JDA getShardById(String id)
The JDA instance for that shard, or null if not found
JDA shard = shardManager.getShardById(0);
if (shard != null) {
System.out.println("Shard 0 status: " + shard.getStatus());
}
getShardCache
Gets a cache view of all shards.
ShardCacheView getShardCache()
Cache view of all JDA shards
getShards
Gets a list of all shard instances.
default List<JDA> getShards()
Immutable list of all JDA instances
for (JDA shard : shardManager.getShards()) {
System.out.println("Shard " + shard.getShardInfo().getShardId() +
": " + shard.getGuilds().size() + " guilds");
}
Shard Status
getStatus
Gets the status of a specific shard.
default JDA.Status getStatus(int shardId)
The shard’s status, or null if shard doesn’t exist
getStatuses
Gets the status of all shards.
default Map<JDA, Status> getStatuses()
Map of each shard to its current status
shardManager.getStatuses().forEach((shard, status) -> {
int shardId = shard.getShardInfo().getShardId();
System.out.println("Shard " + shardId + ": " + status);
});
Event Listeners
addEventListener
Adds event listeners to all shards.
default void addEventListener(Object... listeners)
The event listeners to add
shardManager.addEventListener(new MyEventListener());
removeEventListener
Removes event listeners from all shards.
default void removeEventListener(Object... listeners)
The event listeners to remove
addEventListeners
Adds shard-specific event listeners using a provider.
default void addEventListeners(IntFunction<Object> eventListenerProvider)
eventListenerProvider
IntFunction<Object>
required
Function that takes shard ID and returns a listener
// Create different listener instance per shard
shardManager.addEventListeners(shardId ->
new ShardSpecificListener(shardId)
);
Entity Access
ShardManager provides unified access to entities across all shards:
getGuildById
Finds a guild across all shards.
default Guild getGuildById(long id)
default Guild getGuildById(String id)
The guild, or null if not found
getGuildCache
Gets a unified cache of all guilds.
default SnowflakeCacheView<Guild> getGuildCache()
returns
SnowflakeCacheView<Guild>
Unified cache view of all guilds across shards
getUserById
Finds a user across all shards.
default User getUserById(long id)
default User getUserById(String id)
The user, or null if not found
retrieveUserById
Retrieves a user by ID, fetching from Discord if needed.
default RestAction<User> retrieveUserById(long id)
default RestAction<User> retrieveUserById(String id)
RestAction that completes with the user
shardManager.retrieveUserById("123456789")
.queue(user -> {
System.out.println("Found user: " + user.getAsTag());
});
Shard Management
restart
Restarts all shards or a specific shard.
void restart()
void restart(int id)
The shard ID to restart (optional)
// Restart all shards
shardManager.restart();
// Restart specific shard
shardManager.restart(0);
start
Starts a new shard with the given ID.
The ID of the shard to start
shutdown
Shuts down all shards or a specific shard.
void shutdown()
void shutdown(int shardId)
The shard ID to shutdown (optional)
// Shutdown all shards
shardManager.shutdown();
// Shutdown specific shard
shardManager.shutdown(2);
After calling shutdown(), the ShardManager cannot be reused. Operations like restart() and start() will throw RejectedExecutionException.
Presence Management
setActivity
Sets the activity for all shards.
default void setActivity(Activity activity)
The activity to set, or null to clear
shardManager.setActivity(Activity.playing("with shards"));
setActivityProvider
Sets shard-specific activities.
default void setActivityProvider(IntFunction<? extends Activity> activityProvider)
Function that takes shard ID and returns an activity
shardManager.setActivityProvider(shardId ->
Activity.playing("Shard " + shardId)
);
setStatus
Sets the online status for all shards.
default void setStatus(OnlineStatus status)
setPresence
Sets both status and activity.
default void setPresence(OnlineStatus status, Activity activity)
Statistics
Gets the average gateway ping across all shards.
default double getAverageGatewayPing()
Average ping in milliseconds, or -1 if no shards are connected
double avgPing = shardManager.getAverageGatewayPing();
System.out.println("Average shard ping: " + avgPing + "ms");
getGatewayIntents
Gets the gateway intents configured for shards.
default EnumSet<GatewayIntent> getGatewayIntents()
Set of active gateway intents
Complete Example
public class ShardedBot {
public static void main(String[] args) {
ShardManager shardManager = DefaultShardManagerBuilder
.createDefault("YOUR_BOT_TOKEN")
.setActivity(Activity.watching("all shards"))
.addEventListeners(new GlobalEventListener())
.addEventListeners(shardId -> new ShardListener(shardId))
.build();
// Monitor shard status
shardManager.getStatuses().forEach((shard, status) -> {
int id = shard.getShardInfo().getShardId();
System.out.println("Shard " + id + ": " + status);
});
// Get statistics
System.out.println("Total shards: " + shardManager.getShardsTotal());
System.out.println("Running shards: " + shardManager.getShardsRunning());
System.out.println("Average ping: " + shardManager.getAverageGatewayPing() + "ms");
// Access entities across all shards
long guildCount = shardManager.getGuildCache().size();
System.out.println("Total guilds: " + guildCount);
}
}