Package org.javacord.api

Class DiscordApiBuilder

    • Constructor Detail

      • DiscordApiBuilder

        public DiscordApiBuilder​()

    • Method Detail

      • loginShards

        public Collection<CompletableFuture<DiscordApi>> loginShards​(IntPredicate shardsCondition)
        Login shards adhering to the given predicate to the account with the given token. It is invalid to call setCurrentShard(int) with anything but 0 before calling this method.
        Parameters:
        shardsCondition - The predicate for identifying shards to connect, starting with 0!
        Returns:
        A collection of CompletableFutures which contain the DiscordApis for the shards.

      • loginShards

        public Collection<CompletableFuture<DiscordApi>> loginShards​(int... shards)
        Login given shards to the account with the given token. It is invalid to call setCurrentShard(int) with anything but 0 before calling this method.
        Parameters:
        shards - The shards to connect, starting with 0!
        Returns:
        A collection of CompletableFutures which contain the DiscordApis for the shards.

      • setGlobalRatelimiter

        public DiscordApiBuilder setGlobalRatelimiter​(Ratelimiter ratelimiter)
        Sets a ratelimiter that can be used to control global ratelimits.

        By default, no ratelimiter is set, but for large bots or special use-cases, it can be useful to provide a ratelimiter with a hardcoded ratelimit to prevent hitting the global ratelimit.

        An easy implementation is available with the LocalRatelimiter.

        Parameters:
        ratelimiter - The ratelimiter used to control global ratelimits.
        Returns:
        The current instance in order to chain call methods.

      • setGatewayIdentifyRatelimiter

        public DiscordApiBuilder setGatewayIdentifyRatelimiter​(Ratelimiter ratelimiter)
        Sets a ratelimiter that can be used to control the 5 seconds gateway identify ratelimit.

        By default, Javacord automatically provides a default LocalRatelimiter which is set to allow one gateway identify request per 5500ms and is shared with every bot with the same token in the same Java program.

        **DO NOT** set a custom gateway identify ratelimiter unless you have to synchronize the ratelimit across multiple Java programs (running on different JVMs, VMs, phyiscal servers etc.) that run Javacord on the same bot token. The default ratelimiter will handle the ratelimit for you as long as your whole bot runs in the same Java program.

        Parameters:
        ratelimiter - The ratelimiter used to control the 5 seconds gateway identify ratelimit.
        Returns:
        The current instance in order to chain call methods.

      • setTrustAllCertificates

        public DiscordApiBuilder setTrustAllCertificates​(boolean trustAllCertificates)
        Sets whether all SSL certificates should be trusted when connecting to the Discord API and web socket. This might for example be necessary when connecting through a decrypting proxy. Be aware that this also increases the risk of man-in-the-middle attacks, which basically is, what a decrypting proxy does. Due to this risk, a warning is logged when connecting with this property set to true. If you do not care about this risk, you can suppress this warning using your logging configuration.
        Parameters:
        trustAllCertificates - Whether to trust all SSL certificates.
        Returns:
        The current instance in order to chain call methods.

      • setToken

        public DiscordApiBuilder setToken​(String token)
        Sets the token which is required for the login process. A tutorial on how to get the token can be found in the Javacord wiki.
        Parameters:
        token - The token to set.
        Returns:
        The current instance in order to chain call methods.

      • setAccountType

        public DiscordApiBuilder setAccountType​(AccountType type)
        Sets the account type. By default the builder assumes that you want to login to a bot account. Please notice, that public client bots are not allowed by Discord!
        Parameters:
        type - The account type.
        Returns:
        The current instance in order to chain call methods.

      • setTotalShards

        public DiscordApiBuilder setTotalShards​(int totalShards)
        Sets total shards for server sharding. Sharding allows you to split your bot into several independent instances. A shard only handles a subset of a bot's servers.
        Parameters:
        totalShards - The total amount of shards. Sharding will be disabled if set to 1.
        Returns:
        The current instance in order to chain call methods.
        See Also:
        API docs

      • getTotalShards

        public int getTotalShards​()
        Gets the total amount of shards. Sharding is disabled if set to 1.
        Returns:
        The total amount of shards.
        See Also:
        setTotalShards(int)

      • setCurrentShard

        public DiscordApiBuilder setCurrentShard​(int currentShard)
        Sets shard for server sharding. Sharding allows you to split your bot into several independent instances. A shard only handles a subset of a bot's servers.
        Parameters:
        currentShard - The shard of this connection starting with 0!
        Returns:
        The current instance in order to chain call methods.
        See Also:
        API docs

      • getCurrentShard

        public int getCurrentShard​()
        Gets the current shard.
        Returns:
        The current shard.
        See Also:
        setCurrentShard(int)

      • setWaitForServersOnStartup

        public DiscordApiBuilder setWaitForServersOnStartup​(boolean waitForServersOnStartup)
        Sets if Javacord should wait for all servers to become available on startup. If this is disabled the DiscordApi.getServers() method will return an empty collection directly after logging in and fire ServerBecomesAvailableEvent events once they become available. You can check the ids of unavailable servers using the DiscordApi.getUnavailableServers() method.
        Parameters:
        waitForServersOnStartup - Whether Javacord should wait for all servers to become available on startup or not.
        Returns:
        The current instance in order to chain call methods.

      • isWaitingForServersOnStartup

        public boolean isWaitingForServersOnStartup​()
        Checks if Javacord should wait for all servers to become available on startup.
        Returns:
        If Javacord should wait.
        See Also:
        setWaitForServersOnStartup(boolean)

      • setWaitForUsersOnStartup

        public DiscordApiBuilder setWaitForUsersOnStartup​(boolean waitForUsersOnStartup)
        Sets if Javacord should wait for all users to be cached. If this is set to true, Javacord will consider Servers with uncached users as unavailable.

        Requires the Intent.GUILD_MEMBERS intent to be set.

        Parameters:
        waitForUsersOnStartup - Whether Javacord should wait for all users to be cached or not.
        Returns:
        The current instance in order to chain call methods.

      • isWaitingForUsersOnStartup

        public boolean isWaitingForUsersOnStartup​()
        Checks if Javacord should wait for all users to be cached.
        Returns:
        If Javacord should wait.
        See Also:
        setWaitForUsersOnStartup(boolean)

      • setShutdownHookRegistrationEnabled

        public DiscordApiBuilder setShutdownHookRegistrationEnabled​(boolean registerShutdownHook)
        Sets if Javacord should register a shutdown hook that disconnects the DiscordApi instance.

        By default, Javacord registers a shutdown hook using Runtime.addShutdownHook(Thread) that calls the DiscordApi.disconnect() method. Setting this flag to false will disable this behavior.

        Parameters:
        registerShutdownHook - Whether the shutdown hook should be registered or not.
        Returns:
        The current instance in order to chain call methods.

      • isShutdownHookRegistrationEnabled

        public boolean isShutdownHookRegistrationEnabled​()
        Checks if newly created DiscordApi instances should register a shutdown hook to disconnect the instance.
        Returns:
        Whether the shutdown hook will be registered or not.
        See Also:
        setShutdownHookRegistrationEnabled(boolean)

      • setIntents

        public DiscordApiBuilder setIntents​(Intent... intents)
        Sets intent for the events which should be received.
        Parameters:
        intents - One or more intents from Intent.
        Returns:
        The current instance in order to chain call methods.

      • setAllIntents

        public DiscordApiBuilder setAllIntents​()
        Sets all intents.
        Returns:
        The current instance in order to chain call methods.

      • setAllNonPrivilegedIntents

        public DiscordApiBuilder setAllNonPrivilegedIntents​()
        Sets all non privileged intents.

        This is the default behavior if no intents are set in the builder.

        Returns:
        The current instance in order to chain call methods.

      • setAllIntentsExcept

        public DiscordApiBuilder setAllIntentsExcept​(Intent... intentsToOmit)
        Sets all intents except the given intents.
        Parameters:
        intentsToOmit - One or more Intents which should be omitted.
        Returns:
        The current instance in order to chain call methods.

      • setAllNonPrivilegedIntentsExcept

        public DiscordApiBuilder setAllNonPrivilegedIntentsExcept​(Intent... intentsToOmit)
        Sets all non privileged intents except the given intents.
        Parameters:
        intentsToOmit - One or more Intents which should be omitted.
        Returns:
        The current instance in order to chain call methods.

      • setAllIntentsWhere

        public DiscordApiBuilder setAllIntentsWhere​(Predicate<Intent> condition)
        Sets the intents where the given predicate matches.
        Parameters:
        condition - Whether the intent should be added or not.
        Returns:
        The current instance in order to chain call methods.

      • setRecommendedTotalShards

        public CompletableFuture<DiscordApiBuilder> setRecommendedTotalShards​()
        Retrieves the recommended shards count from the Discord API and sets it in this builder. Sharding allows you to split your bot into several independent instances. A shard only handles a subset of a bot's servers.
        Returns:
        A future with the current api builder.
        See Also:
        API docs

      • addListener

        public <T extends GloballyAttachableListener> DiscordApiBuilder addListener​(Class<T> listenerClass,
                                                                            Supplier<T> listenerSupplier)
        Description copied from interface: ChainableGloballyAttachableListenerManager
        Adds a GloballyAttachableListener to all created DiscordApi instances. The supplier is called for every created DiscordApi instance, so either the same or different instances can be registered. One example would be a method reference to a default constructor like MyListener::new. Adding a listener multiple times will only add it once. The order of invocation is according to first addition.
        Specified by:
        addListener in interface ChainableGloballyAttachableListenerManager
        Type Parameters:
        T - The type of the listener.
        Parameters:
        listenerClass - The listener class.
        listenerSupplier - The supplier of listeners to add.
        Returns:
        The current instance in order to chain call methods.

      • addListener

        public DiscordApiBuilder addListener​(Supplier<GloballyAttachableListener> listenerSupplier)
        Description copied from interface: ChainableGloballyAttachableListenerManager
        Adds a listener that implements one or more GloballyAttachableListeners to all created DiscordApi instances. The supplier is called for every created DiscordApi instance, so either the same or different instances can be registered. One example would be a method reference to a default constructor like MyListener::new. Adding a listener multiple times will only add it once. The order of invocation is according to first addition.
        Specified by:
        addListener in interface ChainableGloballyAttachableListenerManager
        Parameters:
        listenerSupplier - The supplier of listeners to add.
        Returns:
        The current instance in order to chain call methods.

      • addListener

        public <T extends GloballyAttachableListener> DiscordApiBuilder addListener​(Class<T> listenerClass,
                                                                            Function<DiscordApi,T> listenerFunction)
        Description copied from interface: ChainableGloballyAttachableListenerManager
        Adds a GloballyAttachableListener to all created DiscordApi instances. The function is called for every created DiscordApi instance, so either the same or different instances can be registered. One example would be a method reference to a constructor with a DiscordApi parameter like MyListener::new. Adding a listener multiple times will only add it once. The order of invocation is according to first addition.
        Specified by:
        addListener in interface ChainableGloballyAttachableListenerManager
        Type Parameters:
        T - The type of the listener.
        Parameters:
        listenerClass - The listener class.
        listenerFunction - The function to provide listeners to add.
        Returns:
        The current instance in order to chain call methods.

      • addListener

        public DiscordApiBuilder addListener​(Function<DiscordApi,GloballyAttachableListener> listenerFunction)
        Description copied from interface: ChainableGloballyAttachableListenerManager
        Adds a listener that implements one or more GloballyAttachableListeners to all created DiscordApi instances. The function is called for every created DiscordApi instance, so either the same or different instances can be registered. One example would be a method reference to a constructor with a DiscordApi parameter like MyListener::new. Adding a listener multiple times will only add it once. The order of invocation is according to first addition.
        Specified by:
        addListener in interface ChainableGloballyAttachableListenerManager
        Parameters:
        listenerFunction - The function to provide listeners to add.
        Returns:
        The current instance in order to chain call methods.

      • removeListener

        public <T extends GloballyAttachableListener> DiscordApiBuilder removeListener​(Class<T> listenerClass,
                                                                               T listener)
        Description copied from interface: ChainableGloballyAttachableListenerManager
        Removes a GloballyAttachableListener from the list of listeners to be added to DiscordApi instances. If the listener was already added to a DiscordApi instance, it will not get removed by calling this method. This method should normally only be used before calling one of the login methods.
        Specified by:
        removeListener in interface ChainableGloballyAttachableListenerManager
        Type Parameters:
        T - The type of the listener.
        Parameters:
        listenerClass - The listener class.
        listener - The listener to remove.
        Returns:
        The current instance in order to chain call methods.

      • removeListenerSupplier

        public <T extends GloballyAttachableListener> DiscordApiBuilder removeListenerSupplier​(Class<T> listenerClass,
                                                                                       Supplier<T> listenerSupplier)
        Description copied from interface: ChainableGloballyAttachableListenerManager
        Removes a supplier of GloballyAttachableListeners from the list of listeners to be added to DiscordApi instances. If the listener was already added to a DiscordApi instance, it will not get removed by calling this method. This method should normally only be used before calling one of the login methods.
        Specified by:
        removeListenerSupplier in interface ChainableGloballyAttachableListenerManager
        Type Parameters:
        T - The type of the listener.
        Parameters:
        listenerClass - The listener class.
        listenerSupplier - The supplier of listeners to remove.
        Returns:
        The current instance in order to chain call methods.

      • removeListenerFunction

        public <T extends GloballyAttachableListener> DiscordApiBuilder removeListenerFunction​(Class<T> listenerClass,
                                                                                       Function<DiscordApi,T> listenerFunction)
        Description copied from interface: ChainableGloballyAttachableListenerManager
        Removes a function that provides GloballyAttachableListeners from the list of listeners to be added to DiscordApi instances. If the listener was already added to a DiscordApi instance, it will not get removed by calling this method. This method should normally only be used before calling one of the login methods.
        Specified by:
        removeListenerFunction in interface ChainableGloballyAttachableListenerManager
        Type Parameters:
        T - The type of the listener.
        Parameters:
        listenerClass - The listener class.
        listenerFunction - The function to provide listeners to remove.
        Returns:
        The current instance in order to chain call methods.