0
# Sharding System
1

2
Multi-shard bot support for scaling beyond Discord's gateway limits with centralized management and cross-shard operations for large-scale Discord applications.
3

4
## Capabilities
5

6
### Shard Manager
7

8
Centralized management interface for multiple JDA shards with unified operations and monitoring.
9

10
```java { .api }
11
/**
12
 * The ShardManager is a higher level abstraction for managing multiple shards.
13
 * It provides a unified interface for operating across multiple JDA instances.
14
 */
15
interface ShardManager {
16
    /** Get all JDA shards */
17
    List<JDA> getShards();
18
    
19
    /** Get JDA shards with specific status */
20
    List<JDA> getShards(JDA.Status status);
21
    
22
    /** Get specific shard by ID */
23
    JDA getShardById(int shardId);
24
    
25
    /** Get shard cache view */
26
    ShardCacheView getShardCache();
27
    
28
    /** Get shard that contains specific guild */
29
    JDA getShardFor(long guildId);
30
    JDA getShardFor(String guildId);
31
    
32
    /** Start specific shard */
33
    void start(int shardId);
34
    
35
    /** Restart specific shard */
36
    void restart(int shardId);
37
    
38
    /** Shutdown specific shard */
39
    void shutdown(int shardId);
40
    
41
    /** Shutdown all shards */
42
    void shutdown();
43
    
44
    /** Get average gateway ping across all shards */
45
    double getAverageGatewayPing();
46
    
47
    /** Get average shard status */
48
    JDA.Status getStatus();
49
    
50
    /** Set status across all shards */
51
    void setStatus(OnlineStatus status);
52
    
53
    /** Set activity across all shards */
54
    void setActivity(Activity activity);
55
    
56
    /** Set idle status across all shards */
57
    void setIdle(boolean idle);
58
    
59
    /** Set presence across all shards */
60
    void setPresence(OnlineStatus status, Activity activity, boolean idle);
61
    
62
    /** Get unified guild cache across all shards */
63
    SnowflakeCacheView<Guild> getGuildCache();
64
    
65
    /** Get guild by ID from any shard */
66
    Guild getGuildById(long guildId);
67
    Guild getGuildById(String guildId);
68
    
69
    /** Get guilds by name from all shards */
70
    List<Guild> getGuildsByName(String name, boolean ignoreCase);
71
    
72
    /** Get mutual guilds for user across all shards */
73
    List<Guild> getMutualGuilds(User user);
74
    
75
    /** Get unified user cache across all shards */
76
    SnowflakeCacheView<User> getUserCache();
77
    
78
    /** Get user by ID from any shard */
79
    User getUserById(long userId);
80
    User getUserById(String userId);
81
    
82
    /** Get users by name from all shards */
83
    List<User> getUsersByName(String name, boolean ignoreCase);
84
    
85
    /** Get total guild count across all shards */
86
    long getGuildTotal();
87
    
88
    /** Get total user count across all shards */
89
    long getUserTotal();
90
    
91
    /** Add event listeners to all shards */
92
    void addEventListener(Object... listeners);
93
    
94
    /** Remove event listeners from all shards */
95
    void removeEventListener(Object... listeners);
96
    
97
    /** Get registered event listeners */
98
    List<Object> getRegisteredListeners();
99
    
100
    /** Retrieve user from any shard */
101
    RestAction<User> retrieveUserById(long userId);
102
    RestAction<User> retrieveUserById(String userId);
103
    
104
    /** Get statistics for all shards */
105
    ShardStatistics getShardStatistics();
106
}
107
```
108

109
**Usage Examples:**
110

111
```java
112
import net.dv8tion.jda.api.sharding.ShardManager;
113
import net.dv8tion.jda.api.sharding.DefaultShardManagerBuilder;
114

115
// Create shard manager
116
ShardManager shardManager = DefaultShardManagerBuilder.createDefault("BOT_TOKEN")
117
    .setShardsTotal(4)
118
    .addEventListeners(new MyEventListener())
119
    .setStatus(OnlineStatus.ONLINE)
120
    .setActivity(Activity.playing("on multiple shards"))
121
    .build();
122

123
// Wait for all shards to be ready
124
List<JDA> shards = shardManager.getShards();
125
for (JDA shard : shards) {
126
    try {
127
        shard.awaitReady();
128
        System.out.println("Shard " + shard.getShardInfo().getShardId() + " is ready");
129
    } catch (InterruptedException e) {
130
        System.err.println("Interrupted while waiting for shard to be ready");
131
    }
132
}
133

134
// Get statistics
135
long totalGuilds = shardManager.getGuildTotal();
136
long totalUsers = shardManager.getUserTotal();
137
double avgPing = shardManager.getAverageGatewayPing();
138

139
System.out.println("Total guilds: " + totalGuilds);
140
System.out.println("Total users: " + totalUsers);
141
System.out.println("Average ping: " + avgPing + "ms");
142

143
// Find guild across all shards
144
Guild targetGuild = shardManager.getGuildById("123456789");
145
if (targetGuild != null) {
146
    JDA shard = shardManager.getShardFor(targetGuild.getIdLong());
147
    System.out.println("Guild found on shard " + shard.getShardInfo().getShardId());
148
}
149

150
// Set presence across all shards
151
shardManager.setPresence(OnlineStatus.DO_NOT_DISTURB, 
152
    Activity.watching(totalGuilds + " servers"), false);
153

154
// Restart specific shard
155
shardManager.restart(2);
156

157
// Shutdown all shards
158
shardManager.shutdown();
159
```
160

161
### Shard Manager Builder
162

163
Builder pattern for creating and configuring shard managers with comprehensive options.
164

165
```java { .api }
166
/**
167
 * Builder for creating ShardManager instances with various configuration options.
168
 */
169
class DefaultShardManagerBuilder {
170
    /** Create with default settings */
171
    static DefaultShardManagerBuilder createDefault(String token);
172
    
173
    /** Create with minimal cache settings */
174
    static DefaultShardManagerBuilder createLight(String token);
175
    
176
    /** Create with custom intent settings */
177
    static DefaultShardManagerBuilder create(String token, GatewayIntent intent, GatewayIntent... intents);
178
    static DefaultShardManagerBuilder create(String token, Collection<GatewayIntent> intents);
179
    
180
    /** Set bot token */
181
    DefaultShardManagerBuilder setToken(String token);
182
    
183
    /** Set total number of shards */
184
    DefaultShardManagerBuilder setShardsTotal(int shardsTotal);
185
    
186
    /** Set specific shard range to manage */
187
    DefaultShardManagerBuilder setShards(int minShardId, int maxShardId);
188
    DefaultShardManagerBuilder setShards(int... shardIds);
189
    
190
    /** Enable specific gateway intents */
191
    DefaultShardManagerBuilder enableIntents(GatewayIntent... intents);
192
    DefaultShardManagerBuilder enableIntents(Collection<GatewayIntent> intents);
193
    
194
    /** Disable specific gateway intents */
195
    DefaultShardManagerBuilder disableIntents(GatewayIntent... intents);
196
    DefaultShardManagerBuilder disableIntents(Collection<GatewayIntent> intents);
197
    
198
    /** Set enabled intents */
199
    DefaultShardManagerBuilder setEnabledIntents(Collection<GatewayIntent> intents);
200
    
201
    /** Enable cache flags */
202
    DefaultShardManagerBuilder enableCache(CacheFlag... flags);
203
    DefaultShardManagerBuilder enableCache(Collection<CacheFlag> flags);
204
    
205
    /** Disable cache flags */
206
    DefaultShardManagerBuilder disableCache(CacheFlag... flags);
207
    DefaultShardManagerBuilder disableCache(Collection<CacheFlag> flags);
208
    
209
    /** Set member cache policy */
210
    DefaultShardManagerBuilder setMemberCachePolicy(MemberCachePolicy policy);
211
    
212
    /** Set chunking filter */
213
    DefaultShardManagerBuilder setChunkingFilter(ChunkingFilter filter);
214
    
215
    /** Set event manager */
216
    DefaultShardManagerBuilder setEventManagerProvider(IntFunction<IEventManager> eventManagerProvider);
217
    
218
    /** Add event listeners to all shards */
219
    DefaultShardManagerBuilder addEventListeners(Object... listeners);
220
    DefaultShardManagerBuilder addEventListenerProviders(IntFunction<Object>... providers);
221
    
222
    /** Remove event listeners */
223
    DefaultShardManagerBuilder removeEventListeners(Object... listeners);
224
    DefaultShardManagerBuilder removeEventListenerProviders(IntFunction<Object>... providers);
225
    
226
    /** Set initial status */
227
    DefaultShardManagerBuilder setStatus(OnlineStatus status);
228
    
229
    /** Set initial activity */
230
    DefaultShardManagerBuilder setActivity(Activity activity);
231
    
232
    /** Set idle status */
233
    DefaultShardManagerBuilder setIdle(boolean idle);
234
    
235
    /** Set HTTP client builder */
236
    DefaultShardManagerBuilder setHttpClientBuilder(OkHttpClient.Builder builder);
237
    
238
    /** Set HTTP client */
239
    DefaultShardManagerBuilder setHttpClient(OkHttpClient client);
240
    
241
    /** Set WebSocket factory */
242
    DefaultShardManagerBuilder setWebsocketFactory(WebSocketFactory factory);
243
    
244
    /** Set rate limit scheduler */
245
    DefaultShardManagerBuilder setRateLimitScheduler(ScheduledExecutorService scheduler, boolean shutdown);
246
    
247
    /** Set callback pool */
248
    DefaultShardManagerBuilder setCallbackPool(ExecutorService executor, boolean shutdown);
249
    
250
    /** Set event pool */
251
    DefaultShardManagerBuilder setEventPool(ExecutorService executor, boolean shutdown);
252
    
253
    /** Set audio pool */
254
    DefaultShardManagerBuilder setAudioPool(ScheduledExecutorService executor, boolean shutdown);
255
    
256
    /** Set session controller */
257
    DefaultShardManagerBuilder setSessionController(SessionController controller);
258
    
259
    /** Set voice dispatch interceptor */
260
    DefaultShardManagerBuilder setVoiceDispatchInterceptor(VoiceDispatchInterceptor interceptor);
261
    
262
    /** Set shard listeners */
263
    DefaultShardManagerBuilder setShardListenerProvider(IntFunction<ShardListener> provider);
264
    
265
    /** Set thread factory */
266
    DefaultShardManagerBuilder setThreadFactory(ThreadFactory threadFactory);
267
    
268
    /** Set compression type */
269
    DefaultShardManagerBuilder setCompression(Compression compression);
270
    
271
    /** Set gateway encoding */
272
    DefaultShardManagerBuilder setEncoding(GatewayEncoding encoding);
273
    
274
    /** Set large threshold */
275
    DefaultShardManagerBuilder setLargeThreshold(int threshold);
276
    
277
    /** Set maximum reconnect delay */
278
    DefaultShardManagerBuilder setMaxReconnectDelay(int maxReconnectDelay);
279
    
280
    /** Set maximum buffer size */
281
    DefaultShardManagerBuilder setMaxBufferSize(int bufferSize);
282
    
283
    /** Enable/disable config flags */
284
    DefaultShardManagerBuilder setFlag(ConfigFlag flag, boolean enable);
285
    
286
    /** Set context map */
287
    DefaultShardManagerBuilder setContextMap(ConcurrentMap<String, String> map);
288
    
289
    /** Build the shard manager */
290
    ShardManager build() throws LoginException;
291
}
292
```
293

294
**Usage Examples:**
295

296
```java
297
// Basic shard manager setup
298
ShardManager basicShardManager = DefaultShardManagerBuilder.createDefault("BOT_TOKEN")
299
    .setShardsTotal(2)
300
    .build();
301

302
// Advanced shard manager configuration
303
ShardManager advancedShardManager = DefaultShardManagerBuilder.createDefault("BOT_TOKEN")
304
    .setShardsTotal(8)
305
    .setShards(0, 3) // Only manage shards 0-3
306
    .enableIntents(GatewayIntent.GUILD_MEMBERS, GatewayIntent.GUILD_PRESENCES)
307
    .setMemberCachePolicy(MemberCachePolicy.VOICE.or(MemberCachePolicy.OWNER))
308
    .setChunkingFilter(ChunkingFilter.NONE)
309
    .disableCache(CacheFlag.ACTIVITY, CacheFlag.CLIENT_STATUS)
310
    .addEventListeners(new MyShardedEventListener())
311
    .setStatus(OnlineStatus.ONLINE)
312
    .setActivity(Activity.playing("across " + 8 + " shards"))
313
    .setLargeThreshold(250)
314
    .build();
315

316
// Custom shard configuration per shard
317
ShardManager customShardManager = DefaultShardManagerBuilder.createDefault("BOT_TOKEN")
318
    .setShardsTotal(4)
319
    .addEventListenerProviders(shardId -> {
320
        // Different listeners per shard
321
        if (shardId == 0) {
322
            return new PrimaryShardListener();
323
        } else {
324
            return new SecondaryShardListener();
325
        }
326
    })
327
    .setEventManagerProvider(shardId -> {
328
        // Custom event manager per shard
329
        return new CustomEventManager("Shard-" + shardId);
330
    })
331
    .build();
332

333
// Light shard manager for memory efficiency
334
ShardManager lightShardManager = DefaultShardManagerBuilder.createLight("BOT_TOKEN", 
335
        EnumSet.of(GatewayIntent.GUILD_MESSAGES, GatewayIntent.MESSAGE_CONTENT))
336
    .setShardsTotal(4)
337
    .setMemberCachePolicy(MemberCachePolicy.NONE)
338
    .disableCache(CacheFlag.VOICE_STATE, CacheFlag.EMOJI, CacheFlag.STICKER)
339
    .build();
340
```
341

342
### Shard Statistics and Monitoring
343

344
Comprehensive monitoring and statistics for shard performance and health.
345

346
```java { .api }
347
/**
348
 * Interface for monitoring individual shard events and lifecycle.
349
 */
350
interface ShardListener {
351
    /** Called when shard comes online */
352
    void onShardReady(int shardId);
353
    
354
    /** Called when shard disconnects */
355
    void onShardDisconnect(int shardId, CloseCode closeCode, OffsetDateTime disconnectTime, boolean resumable);
356
    
357
    /** Called when shard resumes connection */
358
    void onShardResume(int shardId);
359
    
360
    /** Called when shard reconnects */
361
    void onShardReconnect(int shardId);
362
    
363
    /** Called when shard shuts down */
364
    void onShardShutdown(int shardId, OffsetDateTime shutdownTime);
365
}
366

367
/**
368
 * Cache view for accessing shards.
369
 */
370
interface ShardCacheView extends CacheView<JDA> {
371
    /** Get shard by ID */
372
    JDA getElementById(int shardId);
373
    
374
    /** Get all shards with specific status */
375
    List<JDA> getElementsByStatus(JDA.Status status);
376
    
377
    /** Get shard statistics */
378
    default ShardStatistics getStatistics() {
379
        return new ShardStatistics(asList());
380
    }
381
}
382

383
/**
384
 * Statistics and metrics for shard performance.
385
 */
386
class ShardStatistics {
387
    /** Get total number of shards */
388
    int getTotalShards();
389
    
390
    /** Get number of shards with specific status */
391
    int getShardCount(JDA.Status status);
392
    
393
    /** Get number of connected shards */
394
    int getConnectedShards();
395
    
396
    /** Get average gateway ping across all shards */
397
    double getAverageGatewayPing();
398
    
399
    /** Get minimum gateway ping */
400
    long getMinGatewayPing();
401
    
402
    /** Get maximum gateway ping */
403
    long getMaxGatewayPing();
404
    
405
    /** Get total guild count across all shards */
406
    long getTotalGuilds();
407
    
408
    /** Get total user count across all shards */
409
    long getTotalUsers();
410
    
411
    /** Get total cached entities count */
412
    long getTotalCachedEntities();
413
    
414
    /** Get memory usage per shard */
415
    Map<Integer, Long> getMemoryUsagePerShard();
416
    
417
    /** Get uptime per shard */
418
    Map<Integer, Duration> getUptimePerShard();
419
    
420
    /** Get guild distribution per shard */
421
    Map<Integer, Integer> getGuildDistribution();
422
    
423
    /** Get shard load balancing metrics */
424
    ShardLoadMetrics getLoadMetrics();
425
}
426
```
427

428
**Usage Examples:**
429

430
```java
431
// Custom shard listener for monitoring
432
public class ShardMonitor implements ShardListener {
433
    private final TextChannel logChannel;
434
    private final Map<Integer, OffsetDateTime> shardStartTimes = new HashMap<>();
435
    
436
    public ShardMonitor(TextChannel logChannel) {
437
        this.logChannel = logChannel;
438
    }
439
    
440
    @Override
441
    public void onShardReady(int shardId) {
442
        shardStartTimes.put(shardId, OffsetDateTime.now());
443
        logChannel.sendMessage("✅ Shard " + shardId + " is ready").queue();
444
        
445
        // Log shard info
446
        JDA shard = shardManager.getShardById(shardId);
447
        if (shard != null) {
448
            String info = String.format("Shard %d: %d guilds, %d users, %dms ping",
449
                shardId,
450
                shard.getGuildCache().size(),
451
                shard.getUserCache().size(),
452
                shard.getGatewayPing());
453
            logChannel.sendMessage(info).queue();
454
        }
455
    }
456
    
457
    @Override
458
    public void onShardDisconnect(int shardId, CloseCode closeCode, OffsetDateTime disconnectTime, boolean resumable) {
459
        String status = resumable ? "⚠️ Disconnected (resumable)" : "❌ Disconnected (non-resumable)";
460
        String message = String.format("%s Shard %d: %s (%d)", 
461
            status, shardId, closeCode.getMeaning(), closeCode.getCode());
462
        logChannel.sendMessage(message).queue();
463
    }
464
    
465
    @Override
466
    public void onShardResume(int shardId) {
467
        logChannel.sendMessage("🔄 Shard " + shardId + " resumed").queue();
468
    }
469
    
470
    @Override
471
    public void onShardReconnect(int shardId) {
472
        logChannel.sendMessage("🔄 Shard " + shardId + " reconnected").queue();
473
    }
474
    
475
    @Override
476
    public void onShardShutdown(int shardId, OffsetDateTime shutdownTime) {
477
        Duration uptime = Duration.between(shardStartTimes.get(shardId), shutdownTime);
478
        String message = String.format("🛑 Shard %d shutdown after %d minutes uptime",
479
            shardId, uptime.toMinutes());
480
        logChannel.sendMessage(message).queue();
481
        shardStartTimes.remove(shardId);
482
    }
483
}
484

485
// Set up monitoring
486
ShardMonitor monitor = new ShardMonitor(logChannel);
487
ShardManager shardManager = DefaultShardManagerBuilder.createDefault("BOT_TOKEN")
488
    .setShardsTotal(4)
489
    .setShardListenerProvider(shardId -> monitor)
490
    .build();
491

492
// Regular statistics reporting
493
ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
494
scheduler.scheduleAtFixedRate(() -> {
495
    ShardStatistics stats = shardManager.getShardStatistics();
496
    
497
    EmbedBuilder embed = new EmbedBuilder()
498
        .setTitle("Shard Statistics")
499
        .addField("Total Shards", String.valueOf(stats.getTotalShards()), true)
500
        .addField("Connected", String.valueOf(stats.getConnectedShards()), true)
501
        .addField("Average Ping", String.format("%.1fms", stats.getAverageGatewayPing()), true)
502
        .addField("Total Guilds", String.valueOf(stats.getTotalGuilds()), true)
503
        .addField("Total Users", String.valueOf(stats.getTotalUsers()), true)
504
        .addField("Memory Usage", formatMemoryUsage(stats.getMemoryUsagePerShard()), false)
505
        .setTimestamp(Instant.now())
506
        .setColor(Color.BLUE);
507
    
508
    logChannel.sendMessageEmbeds(embed.build()).queue();
509
}, 0, 1, TimeUnit.HOURS);
510

511
// Helper method for memory formatting
512
private String formatMemoryUsage(Map<Integer, Long> memoryUsage) {
513
    return memoryUsage.entrySet().stream()
514
        .map(entry -> String.format("Shard %d: %dMB", entry.getKey(), entry.getValue() / 1024 / 1024))
515
        .collect(Collectors.joining("\n"));
516
}
517
```
518

519
### Cross-Shard Operations
520

521
Utility methods and patterns for operations that span multiple shards.
522

523
```java { .api }
524
/**
525
 * Utility class for cross-shard operations.
526
 */
527
class ShardUtils {
528
    /** Execute operation on all shards */
529
    static <T> List<CompletableFuture<T>> executeOnAllShards(
530
        ShardManager shardManager, 
531
        Function<JDA, CompletableFuture<T>> operation);
532
    
533
    /** Execute operation on specific shards */
534
    static <T> List<CompletableFuture<T>> executeOnShards(
535
        ShardManager shardManager,
536
        Collection<Integer> shardIds,
537
        Function<JDA, CompletableFuture<T>> operation);
538
    
539
    /** Find optimal shard for operation */
540
    static JDA findOptimalShard(ShardManager shardManager, Predicate<JDA> criteria);
541
    
542
    /** Get total count across all shards */
543
    static long getTotalCount(ShardManager shardManager, Function<JDA, Long> counter);
544
    
545
    /** Distribute load across shards */
546
    static <T> Map<Integer, List<T>> distributeLoad(
547
        ShardManager shardManager,
548
        List<T> items,
549
        Function<T, Long> hashFunction);
550
}
551
```
552

553
**Usage Examples:**
554

555
```java
556
// Cross-shard guild search
557
public CompletableFuture<List<Guild>> findGuildsByName(String name) {
558
    List<CompletableFuture<List<Guild>>> futures = ShardUtils.executeOnAllShards(
559
        shardManager,
560
        shard -> CompletableFuture.supplyAsync(() -> 
561
            shard.getGuildsByName(name, true))
562
    );
563
    
564
    return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
565
        .thenApply(v -> futures.stream()
566
            .flatMap(future -> future.join().stream())
567
            .collect(Collectors.toList()));
568
}
569

570
// Cross-shard message broadcasting
571
public void broadcastMessage(String message) {
572
    shardManager.getShards().parallelStream().forEach(shard -> {
573
        shard.getGuilds().stream()
574
            .map(Guild::getDefaultChannel)
575
            .filter(Objects::nonNull)
576
            .forEach(channel -> {
577
                channel.sendMessage(message).queue(
578
                    success -> {},
579
                    error -> System.err.println("Failed to send to " + channel.getGuild().getName())
580
                );
581
            });
582
    });
583
}
584

585
// Load balancing for processing
586
public void processGuildsBalanced(List<String> guildIds) {
587
    Map<Integer, List<String>> distribution = ShardUtils.distributeLoad(
588
        shardManager,
589
        guildIds,
590
        guildId -> Long.parseLong(guildId)
591
    );
592
    
593
    distribution.forEach((shardId, guildList) -> {
594
        JDA shard = shardManager.getShardById(shardId);
595
        CompletableFuture.runAsync(() -> {
596
            guildList.forEach(guildId -> {
597
                Guild guild = shard.getGuildById(guildId);
598
                if (guild != null) {
599
                    processGuild(guild);
600
                }
601
            });
602
        });
603
    });
604
}
605

606
// Cross-shard statistics collection
607
public ShardHealthReport generateHealthReport() {
608
    Map<Integer, CompletableFuture<ShardHealth>> healthFutures = 
609
        shardManager.getShards().stream()
610
            .collect(Collectors.toMap(
611
                shard -> shard.getShardInfo().getShardId(),
612
                this::collectShardHealth
613
            ));
614
    
615
    // Wait for all health checks to complete
616
    CompletableFuture.allOf(healthFutures.values().toArray(new CompletableFuture[0])).join();
617
    
618
    Map<Integer, ShardHealth> healthMap = healthFutures.entrySet().stream()
619
        .collect(Collectors.toMap(
620
            Map.Entry::getKey,
621
            entry -> entry.getValue().join()
622
        ));
623
    
624
    return new ShardHealthReport(healthMap);
625
}
626

627
private CompletableFuture<ShardHealth> collectShardHealth(JDA shard) {
628
    return CompletableFuture.supplyAsync(() -> {
629
        return ShardHealth.builder()
630
            .shardId(shard.getShardInfo().getShardId())
631
            .status(shard.getStatus())
632
            .ping(shard.getGatewayPing())
633
            .guildCount(shard.getGuildCache().size())
634
            .userCount(shard.getUserCache().size())
635
            .uptime(Duration.between(shard.getTimeCreated(), Instant.now()))
636
            .build();
637
    });
638
}
639
```
640

641
## Types
642

643
```java { .api }
644
// Shard information
645
class ShardInfo {
646
    /** Get shard ID (0-based) */
647
    int getShardId();
648
    
649
    /** Get total shard count */
650
    int getShardTotal();
651
    
652
    /** Get string representation (id/total) */
653
    String getShardString();
654
}
655

656
// Session controller for coordinating shard logins
657
interface SessionController {
658
    /** Get gateway information */
659
    CompletableFuture<SessionController.Gateway> getGateway();
660
    
661
    /** Request session identifier */
662
    SessionController.SessionConnectNode appendSession(SessionController.SessionConnectNode node);
663
    
664
    /** Remove session from queue */
665
    void removeSession(SessionController.SessionConnectNode node);
666
    
667
    /** Get remaining session starts */
668
    int getRemainingStarts();
669
    
670
    /** Get session start limit reset time */
671
    long getSessionStartLimitResetTime();
672
}
673

674
// Chunking filter for member loading
675
enum ChunkingFilter {
676
    ALL, NONE;
677
    
678
    /** Create filter that includes specific guilds */
679
    static ChunkingFilter include(long... guildIds);
680
    
681
    /** Create filter that excludes specific guilds */
682
    static ChunkingFilter exclude(long... guildIds);
683
    
684
    /** Filter guilds */
685
    boolean filter(long guildId);
686
}
687

688
// Member cache policy
689
enum MemberCachePolicy {
690
    ALL, OWNER, VOICE, ONLINE, PENDING, NONE;
691
    
692
    /** Combine policies with OR logic */
693
    MemberCachePolicy or(MemberCachePolicy policy);
694
    
695
    /** Combine policies with AND logic */
696
    MemberCachePolicy and(MemberCachePolicy policy);
697
    
698
    /** Create policy for specific users */
699
    static MemberCachePolicy of(Collection<User> users);
700
    
701
    /** Check if member should be cached */
702
    boolean cacheMember(Member member);
703
}
704

705
// Compression types
706
enum Compression {
707
    NONE, ZLIB
708
}
709

710
// Gateway encoding
711
enum GatewayEncoding {
712
    JSON, ETF
713
}
714

715
// Config flags for JDA behavior
716
enum ConfigFlag {
717
    SHUTDOWN_HOOK, BULK_DELETE_SPLITTING, AUTO_RECONNECT, 
718
    BUFFER_POOL, LAZY_LOADING, MEMBER_CACHE_CHUNKING,
719
    USE_SHUTDOWN_NOW;
720
    
721
    /** Get default config flags */
722
    static EnumSet<ConfigFlag> getDefault();
723
}
724
```