O
- the configuration flavor supplied to the GatewayClient
instances to be built.public class GatewayBootstrap<O extends GatewayOptions> extends Object
GatewayDiscordClient
. A shard
group represents a set of shards for a given bot that will share some key resources like entity caching and event
dispatching. Defaults to creating an automatic sharding group using all shards up to the recommended amount. Refer
to each setter for more details about the default values for each configuration. Some of the commonly used ones are:
setSharding(ShardingStrategy)
method.setInitialStatus(Function)
setStoreService(StoreService)
One of the following methods must be subscribed to in order to begin establishing Discord Gateway connections:
login()
to obtain a Mono
for a GatewayDiscordClient
that can be externally
managed.login(Function)
to customize the GatewayClient
instances to build.withGateway(Function)
to work with the GatewayDiscordClient
in a scoped way, providing
a mapping function that will close and release all resources on disconnection.setAwaitConnections(boolean)
.Modifier and Type | Method and Description |
---|---|
static GatewayBootstrap<GatewayOptions> |
create(DiscordClient client)
Create a default
GatewayBootstrap based off the given DiscordClient that provides an instance
of CoreResources used to provide defaults while building a GatewayDiscordClient . |
static VoiceConnectionFactory |
defaultVoiceConnectionFactory()
Create a
VoiceConnectionFactory with reconnecting capabilities. |
Mono<GatewayDiscordClient> |
login()
Connect to the Discord Gateway upon subscription to build a
GatewayClient from the set of options
configured by this builder. |
Mono<GatewayDiscordClient> |
login(Function<O,GatewayClient> clientFactory)
Connect to the Discord Gateway upon subscription using a custom
factory to build a
GatewayClient from the set of options configured by this builder. |
static Function<GatewayDiscordClient,Mono<Void>> |
noopDestroyHandler()
Destroy handler that doesn't perform any cleanup task.
|
GatewayBootstrap<O> |
setAwaitConnections(boolean awaitConnections)
Set if the connect
Mono should defer completion until all joining shards have connected. |
GatewayBootstrap<O> |
setDestroyHandler(Function<GatewayDiscordClient,Mono<Void>> destroyHandler)
Set a custom
handler that generate a destroy sequence to be run once all joining shards have
disconnected, after all internal resources have been released. |
GatewayBootstrap<O> |
setDisabledIntents(IntentSet intents)
Set the intents which should not be subscribed from the gateway for this shard.
|
GatewayBootstrap<O> |
setDispatchEventMapper(DispatchEventMapper dispatchEventMapper)
Customize the
DispatchEventMapper used to convert Gateway Dispatch into Event instances. |
GatewayBootstrap<O> |
setEnabledIntents(IntentSet intents)
Set the intents to subscribe from the gateway for this shard.
|
GatewayBootstrap<O> |
setEntityRetrievalStrategy(EntityRetrievalStrategy entityRetrievalStrategy)
Customize the
EntityRetrievalStrategy to use by default in order to retrieve Discord entities. |
GatewayBootstrap<O> |
setEventDispatcher(EventDispatcher eventDispatcher)
Set a custom
EventDispatcher to receive Events from all joining shards and publish them to
all subscribers. |
<O2 extends GatewayOptions> |
setExtraOptions(Function<? super O,O2> optionsModifier)
Add a configuration for
GatewayClient implementation-specific cases, changing the type of the current
GatewayOptions object passed to the GatewayClient factory in connect methods. |
GatewayBootstrap<O> |
setGatewayObserver(GatewayObserver gatewayObserver)
Set a custom
GatewayObserver to be notified of Gateway lifecycle events across all joining shards. |
GatewayBootstrap<O> |
setGatewayReactorResources(Function<ReactorResources,GatewayReactorResources> gatewayReactorResources)
Customize the
ReactorResources used exclusively for Gateway-related operations, such as maintaining
the websocket connections and scheduling Gateway tasks. |
GatewayBootstrap<O> |
setGuildSubscriptions(boolean guildSubscriptions)
Set if this shard group will subscribe to presence and typing events.
|
GatewayBootstrap<O> |
setInitialPresence(Function<ShardInfo,discord4j.discordjson.json.gateway.StatusUpdate> initialPresence)
Deprecated.
|
GatewayBootstrap<O> |
setInitialStatus(Function<ShardInfo,discord4j.discordjson.json.gateway.StatusUpdate> initialStatus)
Set a
Function to determine the StatusUpdate that each joining shard should use when identifying
to the Gateway. |
GatewayBootstrap<O> |
setInvalidationStrategy(InvalidationStrategy invalidationStrategy)
Set the
InvalidationStrategy this shard group should use on shard session termination. |
GatewayBootstrap<O> |
setMaxMissedHeartbeatAck(int maxMissedHeartbeatAck)
Set the maximum number of missed heartbeat acknowledge payloads each connection to Gateway will allow before
triggering an automatic reconnect.
|
GatewayBootstrap<O> |
setMemberRequestFilter(MemberRequestFilter memberRequestFilter)
Set a
MemberRequestFilter to determine how this shard group should request guild members. |
GatewayBootstrap<O> |
setPayloadReader(PayloadReader payloadReader)
Customize how inbound Gateway payloads are decoded from
ByteBuf . |
GatewayBootstrap<O> |
setPayloadWriter(PayloadWriter payloadWriter)
Customize how outbound Gateway payloads are encoded into
ByteBuf . |
GatewayBootstrap<O> |
setReconnectOptions(ReconnectOptions reconnectOptions)
Set a custom
ReconnectOptions to configure how Gateway connections will attempt to reconnect every
time a websocket session is closed unexpectedly. |
GatewayBootstrap<O> |
setResumeOptions(Function<ShardInfo,SessionInfo> resumeOptions)
Set a
Function to determine the details to resume a session that each joining shard should use when
identifying for the first time to the Gateway. |
GatewayBootstrap<O> |
setShardCoordinator(ShardCoordinator shardCoordinator)
Set a custom
ShardCoordinator to manage multiple GatewayDiscordClient instances, even across
boundaries. |
GatewayBootstrap<O> |
setSharding(ShardingStrategy shardingStrategy)
Set the sharding method to use while building a
GatewayDiscordClient . |
GatewayBootstrap<O> |
setStoreService(StoreService storeService)
Set a custom
StoreService , an abstract factory to create Store instances, to cache Gateway
updates. |
GatewayBootstrap<O> |
setVoiceConnectionFactory(VoiceConnectionFactory voiceConnectionFactory)
Customize the
VoiceConnectionFactory used to establish and maintain VoiceConnection instances to
perform voice-related operations. |
GatewayBootstrap<O> |
setVoiceReactorResources(Function<ReactorResources,VoiceReactorResources> voiceReactorResources)
Customize the
ReactorResources used exclusively for voice-related operations, such as maintaining
the Voice Gateway websocket connections, Voice UDP socket connections and scheduling Gateway tasks. |
GatewayBootstrap<O> |
setVoiceReconnectOptions(ReconnectOptions voiceReconnectOptions)
Set a custom
ReconnectOptions to configure how Voice Gateway connections will attempt to reconnect every
time a websocket session is closed unexpectedly. |
static Function<GatewayDiscordClient,Mono<Void>> |
shutdownDestroyHandler()
Destroy handler that calls
EventDispatcher.shutdown() followed by StoreService.dispose()
asynchronously. |
GatewayBootstrap<O> |
withEventDispatcher(Function<EventDispatcher,Publisher<?>> dispatcherFunction)
Set an initial subscriber to the bootstrapped
EventDispatcher to gain access to early startup events. |
Mono<Void> |
withGateway(Function<GatewayDiscordClient,Publisher<?>> whileConnectedFunction)
Connect to the Discord Gateway upon subscription to acquire a
GatewayDiscordClient instance and use it
in a declarative way, releasing the object once the derived usage Function completes, and the underlying
shard group disconnects, according to GatewayDiscordClient.onDisconnect() . |
public static GatewayBootstrap<GatewayOptions> create(DiscordClient client)
GatewayBootstrap
based off the given DiscordClient
that provides an instance
of CoreResources
used to provide defaults while building a GatewayDiscordClient
.client
- the DiscordClient
used to set up configurationGatewayDiscordClient
public <O2 extends GatewayOptions> GatewayBootstrap<O2> setExtraOptions(Function<? super O,O2> optionsModifier)
GatewayClient
implementation-specific cases, changing the type of the current
GatewayOptions
object passed to the GatewayClient
factory in connect methods.O2
- new type for the optionsoptionsModifier
- Function
to transform the GatewayOptions
type to provide custom
GatewayClient
implementations a proper configuration object.GatewayBootstrap
that will now work with the new options type.public GatewayBootstrap<O> setSharding(ShardingStrategy shardingStrategy)
GatewayDiscordClient
. Defaults to creating all shards
given by the recommended amount from Discord. Built-in factories like ShardingStrategy.fixed(int)
to use
a predefined number of shards, or customize the strategy using ShardingStrategy.builder()
.
For example, it is possible to define the shardCount
parameter independently from the number of shards
to create and connect to Gateway by using:
.setSharding(ShardingStrategy.builder() .indices(0, 2, 4) .count(6) .build())Would only connect shards 0, 2 and 4 while still indicating that your bot guilds are split across 6 shards.
shardingStrategy
- a strategy to use while sharding the connections to Discord Gatewaypublic GatewayBootstrap<O> setAwaitConnections(boolean awaitConnections)
Mono
should defer completion until all joining shards have connected. Defaults to
true
if running a single shard, otherwise false
.awaitConnections
- true
if connect should wait until all joining shards have connected before
completing, or false
to complete immediatelypublic GatewayBootstrap<O> setShardCoordinator(ShardCoordinator shardCoordinator)
ShardCoordinator
to manage multiple GatewayDiscordClient
instances, even across
boundaries. Defaults to using LocalShardCoordinator
.shardCoordinator
- an externally managed ShardCoordinator
to coordinate multiple
GatewayDiscordClient
instances.public GatewayBootstrap<O> setEventDispatcher(@Nullable EventDispatcher eventDispatcher)
EventDispatcher
to receive Events
from all joining shards and publish them to
all subscribers. Defaults to using EventDispatcher.buffering()
which buffers all events until the
first subscriber subscribes to the dispatcher.eventDispatcher
- an externally managed EventDispatcher
to publish eventspublic GatewayBootstrap<O> setStoreService(@Nullable StoreService storeService)
StoreService
, an abstract factory to create Store
instances, to cache Gateway
updates. Defaults to using JdkStoreService
unless another factory of higher priority is discovered.storeService
- an externally managed StoreService
to receive Gateway updatespublic GatewayBootstrap<O> setInvalidationStrategy(InvalidationStrategy invalidationStrategy)
InvalidationStrategy
this shard group should use on shard session termination. Discord Gateway
sends real-time updates that are cached by Discord4J. When a Gateway session is terminated, any update beyond
that point is lost and therefore the cache, represented by the Store
abstraction, is outdated. Reacting
to this event is called "invalidation" and can be configured through this method.
Defaults to using InvalidationStrategy.disable()
unless you are under a single shard setup, where
InvalidationStrategy.identity()
is used. Common possible options are:
InvalidationStrategy.withJdkRegistry()
InvalidationStrategy.withCustomRegistry(KeyStoreRegistry)
InvalidationStrategy.disable()
InvalidationStrategy.identity()
invalidationStrategy
- an InvalidationStrategy
to apply to this shard grouppublic GatewayBootstrap<O> setMemberRequestFilter(MemberRequestFilter memberRequestFilter)
MemberRequestFilter
to determine how this shard group should request guild members. The provided
filter is applied on each GUILD_CREATE payload and if returns true
, members will be requested for the
given guild. Defaults to loading members from all large guilds immediately after a GUILD_CREATE.memberRequestFilter
- the filter indicating how to load guild memberspublic GatewayBootstrap<O> setDestroyHandler(Function<GatewayDiscordClient,Mono<Void>> destroyHandler)
handler
that generate a destroy sequence to be run once all joining shards have
disconnected, after all internal resources have been released. The destroy procedure is applied asynchronously
and errors are logged and swallowed. Defaults to shutdownDestroyHandler()
that will
release the set EventDispatcher
and StoreService
.@Deprecated public GatewayBootstrap<O> setInitialPresence(Function<ShardInfo,discord4j.discordjson.json.gateway.StatusUpdate> initialPresence)
setInitialStatus(Function)
public GatewayBootstrap<O> setInitialStatus(Function<ShardInfo,discord4j.discordjson.json.gateway.StatusUpdate> initialStatus)
public GatewayBootstrap<O> setResumeOptions(Function<ShardInfo,SessionInfo> resumeOptions)
Function
to determine the details to resume a session that each joining shard should use when
identifying for the first time to the Gateway. Defaults to returning null
to begin a fresh session on
startup.resumeOptions
- a Function
that supplies SessionInfo
instances from a given
ShardInfo
public GatewayBootstrap<O> setEnabledIntents(IntentSet intents)
intents
- set of intents to subscribepublic GatewayBootstrap<O> setDisabledIntents(IntentSet intents)
IntentSet.all()
- the provided intents
Intents will not be used, when this method is not called.intents
- set of intents which should not be subscribedpublic GatewayBootstrap<O> setGuildSubscriptions(boolean guildSubscriptions)
true
.guildSubscriptions
- whether to enable or disable guild subscriptionspublic GatewayBootstrap<O> setPayloadReader(@Nullable PayloadReader payloadReader)
ByteBuf
.payloadReader
- a Gateway payload decoderpublic GatewayBootstrap<O> setPayloadWriter(@Nullable PayloadWriter payloadWriter)
ByteBuf
.payloadWriter
- a Gateway payload encoderpublic GatewayBootstrap<O> setReconnectOptions(ReconnectOptions reconnectOptions)
ReconnectOptions
to configure how Gateway connections will attempt to reconnect every
time a websocket session is closed unexpectedly.reconnectOptions
- a ReconnectOptions
policy to use in Gateway connectionspublic GatewayBootstrap<O> setVoiceReconnectOptions(ReconnectOptions voiceReconnectOptions)
ReconnectOptions
to configure how Voice Gateway connections will attempt to reconnect every
time a websocket session is closed unexpectedly.voiceReconnectOptions
- a ReconnectOptions
policy to use in Voice Gateway connectionspublic GatewayBootstrap<O> setGatewayObserver(GatewayObserver gatewayObserver)
GatewayObserver
to be notified of Gateway lifecycle events across all joining shards.gatewayObserver
- a GatewayObserver
to install on all joining shardspublic GatewayBootstrap<O> setGatewayReactorResources(Function<ReactorResources,GatewayReactorResources> gatewayReactorResources)
ReactorResources
used exclusively for Gateway-related operations, such as maintaining
the websocket connections and scheduling Gateway tasks. Defaults to using the parent ReactorResources
inherited from DiscordClient
.gatewayReactorResources
- a ReactorResources
object for Gateway operationspublic GatewayBootstrap<O> setVoiceReactorResources(Function<ReactorResources,VoiceReactorResources> voiceReactorResources)
ReactorResources
used exclusively for voice-related operations, such as maintaining
the Voice Gateway websocket connections, Voice UDP socket connections and scheduling Gateway tasks. Defaults
to using the parent ReactorResources
inherited from DiscordClient
.voiceReactorResources
- a ReactorResources
object for voice operationspublic GatewayBootstrap<O> setVoiceConnectionFactory(VoiceConnectionFactory voiceConnectionFactory)
VoiceConnectionFactory
used to establish and maintain VoiceConnection
instances to
perform voice-related operations. Defaults to defaultVoiceConnectionFactory()
.voiceConnectionFactory
- a factory that can create VoiceConnection
instances.public GatewayBootstrap<O> setEntityRetrievalStrategy(@Nullable EntityRetrievalStrategy entityRetrievalStrategy)
EntityRetrievalStrategy
to use by default in order to retrieve Discord entities.entityRetrievalStrategy
- a strategy to use to retrieve entitiespublic GatewayBootstrap<O> setDispatchEventMapper(DispatchEventMapper dispatchEventMapper)
DispatchEventMapper
used to convert Gateway Dispatch into Event
instances.
Defaults to using DispatchEventMapper.emitEvents()
that will process payloads and save its updates to
the appropriate Store
, then generate the right Event
instance.dispatchEventMapper
- a factory to derive Events
from Gatewaypublic GatewayBootstrap<O> setMaxMissedHeartbeatAck(int maxMissedHeartbeatAck)
maxMissedHeartbeatAck
- a non-negative number representing the maximum number of allowed@Experimental public GatewayBootstrap<O> withEventDispatcher(Function<EventDispatcher,Publisher<?>> dispatcherFunction)
EventDispatcher
to gain access to early startup events. The
subscriber is derived from the given Function
which returns a Publisher
that is subscribed early
in the Gateway connection process.dispatcherFunction
- an EventDispatcher
mapper that derives an asynchronous listenerpublic Mono<Void> withGateway(Function<GatewayDiscordClient,Publisher<?>> whileConnectedFunction)
GatewayDiscordClient
instance and use it
in a declarative way, releasing the object once the derived usage Function
completes, and the underlying
shard group disconnects, according to GatewayDiscordClient.onDisconnect()
.
The timing of acquiring a GatewayDiscordClient
depends on the setAwaitConnections(boolean)
setting: if true
, when all joining shards have connected; if false
, as soon as it is possible to
establish a connection to the Gateway.
Calling this method is useful when you operate on the GatewayDiscordClient
object using reactive API you
can compose within the scope of the given Function
.
whileConnectedFunction
- the Function
to apply the connected
GatewayDiscordClient
and trigger a processing pipeline from it.Mono
completing after all resources have releasedpublic Mono<GatewayDiscordClient> login()
GatewayClient
from the set of options
configured by this builder. The resulting GatewayDiscordClient
can be externally managed, leaving you
in charge of properly releasing its resources by calling GatewayDiscordClient.logout()
.
The timing of acquiring a GatewayDiscordClient
depends on the setAwaitConnections(boolean)
setting: if true
, when all joining shards have connected; if false
, as soon as it is possible
to establish a connection to the Gateway.
All joining shards will attempt to serially connect to Discord Gateway, coordinated by the current
ShardCoordinator
. If one of the shards fail to connect due to a retryable problem like invalid session
it will retry before continuing to the next one.
Mono
that upon subscription and depending on the configuration of
setAwaitConnections(boolean)
, emits a GatewayDiscordClient
. If an error occurs during the setup
sequence, it will be emitted through the Mono
.public Mono<GatewayDiscordClient> login(Function<O,GatewayClient> clientFactory)
factory
to build a
GatewayClient
from the set of options configured by this builder. See login()
for more details
about how the returned Mono
operates.Mono
that upon subscription and depending on the configuration of
setAwaitConnections(boolean)
, emits a GatewayDiscordClient
. If an error occurs during the setup
sequence, it will be emitted through the Mono
.public static Function<GatewayDiscordClient,Mono<Void>> noopDestroyHandler()
public static Function<GatewayDiscordClient,Mono<Void>> shutdownDestroyHandler()
EventDispatcher.shutdown()
followed by StoreService.dispose()
asynchronously.public static VoiceConnectionFactory defaultVoiceConnectionFactory()
VoiceConnectionFactory
with reconnecting capabilities.VoiceConnectionFactory