Package com.mewna.catnip

Interface Catnip

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
CatnipImpl
public interface Catnip extends AutoCloseable
The base catnip interface. Almost everything catnip-related will be accessed through this interface -- REST access, shard management, some utilities, and more. The main exception to this rule is entities that have convenience methods exposed on their interfaces.

Note that this interface extends AutoCloseable; this is meant for cases where some relatively-fast blocking operations are desirable, and a long-term catnip instance is not needed. An example of this is doing some quick REST calls when blocking a thread is not an issue. Another possible use-case is (ab)using the built-in TaskScheduler for one reason or another, although creating an entire catnip instance solely for that would be quite silly.

Since:
9/3/18.
Author:
amy

  • Method Details

    • catnip

      static Catnip catnip(@Nonnull String token)
      Create a new catnip instance with the given token.

      This method may block while validating the provided token.

      Parameters:
      token - The token to be used for all API operations.
      Returns:
      A new catnip instance.

    • catnipAsync

      static io.reactivex.rxjava3.core.Single<Catnip> catnipAsync(@Nonnull String token)
      Create a new catnip instance with the given token.

      This method may block while validating the provided token.

      Parameters:
      token - The token to be used for all API operations.
      Returns:
      A new catnip instance.

    • catnip

      static Catnip catnip(@Nonnull CatnipOptions options)
      Create a new catnip instance with the given options.

      This method may block while validating the provided token.

      Parameters:
      options - The options to be applied to the catnip instance.
      Returns:
      A new catnip instance.

    • catnipAsync

      static io.reactivex.rxjava3.core.Single<Catnip> catnipAsync(@Nonnull CatnipOptions options)
      Create a new catnip instance with the given options.

      This method may block while validating the provided token.

      Parameters:
      options - The options to be applied to the catnip instance.
      Returns:
      A new catnip instance.

    • parseIdFromToken

      static long parseIdFromToken(String token)
      Parses a token and returns the client id encoded therein. Throws a IllegalArgumentException if the provided token is not well-formed.

      See the following image for an explanation of the Discord token format:
      Token format

      Parameters:
      token - The token to parse.
      Returns:
      The client id encoded in the token.
      Throws:
      IllegalArgumentException - If the provided token is not well-formed.

    • options

      @Nonnull @CheckReturnValue CatnipOptionsView options()
      Returns:
      An immutable view of the current instance's options.

    • gatewayInfo

      @Nullable @CheckReturnValue GatewayInfo gatewayInfo()
      Returns:
      The cached gateway info. May be null if it hasn't been fetched yet.

    • fetchGatewayInfo

      @Nonnull @CheckReturnValue io.reactivex.rxjava3.core.Single<GatewayInfo> fetchGatewayInfo()
      Fetches the gateway info and updates the cache. Calls made to gatewayInfo() after this stage completes successfully are guaranteed to return a non null value.

      Updates the cached gateway info.

      Returns:
      The gateway info fetched from discord.

    • connect

      @Nonnull Catnip connect()
      Start all shards asynchronously. To customize the shard spawning / management strategy, see CatnipOptions.
      Returns:
      Itself.

    • rxScheduler

      @Nonnull @CheckReturnValue default io.reactivex.rxjava3.core.Scheduler rxScheduler()

    • dispatchManager

      @Nonnull @CheckReturnValue default DispatchManager dispatchManager()
      Handles dispatching and listening to events.
      Returns:
      The current dispatch manager instance.

    • shardManager

      @Nonnull default ShardManager shardManager()
      Returns:
      The shard manager being used by this catnip instance.

    • sessionManager

      @Nonnull default SessionManager sessionManager()
      Returns:
      The session manager being used by this catnip instance.

    • eventBuffer

      @Nonnull default EventBuffer eventBuffer()
      Returns:
      The event buffer being used by this catnip instance.

    • rest

      @Nonnull @CheckReturnValue Rest rest()
      Returns:
      The REST API instance for this catnip instance.

    • logAdapter

      @Nonnull default LogAdapter logAdapter()
      The logging adapter. This is used throughout the lib to log things, and may additionally be used by user code if you don't want to set up your own logging things. The logging adapter is exposed like this because it is possible to specify a custom logging adapter in CatnipOptions; generally you should just stick with the provided default SLF4J logging adapter.
      Returns:
      The logging adapter being used by this catnip instance.

    • cache

      @Nonnull default EntityCache cache()
      Returns:
      The entity cache being used by this catnip instance.

    • cacheWorker

      @Nonnull default EntityCacheWorker cacheWorker()
      The cache worker being used by this catnip instance. You should use this if you need to do special caching for some reason.
      Returns:
      The cache worker being used by this catnip instance.

    • taskScheduler

      default TaskScheduler taskScheduler()
      The task scheduler allows for scheduling one-off and recurring tasks that are executed at some point in the future. By default, the task scheduler is effectively just a simple wrapper over Observable.timer(long, TimeUnit) and Observable.interval(long, TimeUnit).
      Returns:
      The task scheduler used by this catnip instance.

    • unavailableGuilds

      @Nonnull Set<String> unavailableGuilds()
      Returns:
      A set of all ids of unavailable guilds.

    • isUnavailable

      boolean isUnavailable(@Nonnull String guildId)
      Parameters:
      guildId - The guild to check.
      Returns:
      Whether or not the guild is unavailable.

    • extensionManager

      @Nonnull ExtensionManager extensionManager()
      Returns:
      The extension manager being used by this catnip instance.

    • loadExtension

      @Nonnull Catnip loadExtension(@Nonnull Extension extension)
      Load an extension for this catnip instance. See Extension for more information.
      Parameters:
      extension - The extension to load.
      Returns:
      Itself.

    • extension

      @Nullable default <T extends Extension> T extension(@Nonnull Class<T> extensionClass)
      Return a single extension by class. If multiple extensions are loaded from the same class, there is no guarantee which extension instance will be returned, in which case you should be using ExtensionManager.matchingExtensions(Class).
      Type Parameters:
      T - Type of the extension.
      Parameters:
      extensionClass - The extension class to find instances of
      Returns:
      A possibly-null instance of the passed extension class.

    • injectOptions

      @Nonnull Catnip injectOptions(@Nonnull Extension extension, @Nonnull UnaryOperator<CatnipOptions> optionsPatcher)
      Inject options into this catnip instance from the given extension. This allows extensions to do things like automatically register a new cache worker without having to tell the end-user to specify options. By default, options that get injected will be logged.
      Parameters:
      extension - The extension injecting the options.
      optionsPatcher - Function responsible for updating the settings.
      Returns:
      Itself.
      Throws:
      IllegalArgumentException - When the given extension isn't loaded.

    • selfUser

      @Nonnull @CheckReturnValue io.reactivex.rxjava3.core.Maybe<User> selfUser()
      Returns:
      The currently-logged-in user. May be null if no shards have logged in.

    • clientId

      String clientId()
      The ID of this client
      Returns:
      The ID of this client.

    • clientIdAsLong

      long clientIdAsLong()
      The ID of this client, as a long.
      Returns:
      The ID of the client, as a long.

    • entitySerializer

      default EntitySerializer<?> entitySerializer()
      Returns:
      The entity serializer that catnip uses for converting entities into an external-friendly format.

    • openVoiceConnection

      default void openVoiceConnection(@Nonnull String guildId, @Nonnull String channelId)
      Opens a voice connection to the provided guild and channel. The connection is opened asynchronously, with VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE events being fired when the connection is opened.
      Parameters:
      guildId - Guild to connect.
      channelId - Channel to connect.

    • openVoiceConnection

      void openVoiceConnection(@Nonnull String guildId, @Nonnull String channelId, boolean selfMute, boolean selfDeaf)
      Opens a voice connection to the provided guild and channel. The connection is opened asynchronously, with VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE events being fired when the connection is opened.
      Parameters:
      guildId - Guild to connect.
      channelId - Channel to connect.
      selfMute - Whether or not to connect as muted.
      selfDeaf - Whether or not to connect as deafened.

    • openVoiceConnection

      default void openVoiceConnection(long guildId, long channelId)
      Opens a voice connection to the provided guild and channel. The connection is opened asynchronously, with VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE events being fired when the connection is opened.
      Parameters:
      guildId - Guild to connect.
      channelId - Channel to connect.

    • openVoiceConnection

      default void openVoiceConnection(long guildId, long channelId, boolean selfMute, boolean selfDeaf)
      Opens a voice connection to the provided guild and channel. The connection is opened asynchronously, with VOICE_STATE_UPDATE and VOICE_SERVER_UPDATE events being fired when the connection is opened.
      Parameters:
      guildId - Guild to connect.
      channelId - Channel to connect.
      selfMute - Whether or not to connect as muted.
      selfDeaf - Whether or not to connect as deafened.

    • closeVoiceConnection

      void closeVoiceConnection(@Nonnull String guildId)
      Closes the voice connection on the specified guild.
      Parameters:
      guildId - Guild to disconnect.

    • closeVoiceConnection

      void closeVoiceConnection(long guildId)
      Closes the voice connection on the specified guild.
      Parameters:
      guildId - Guild to disconnect.

    • chunkMembers

      default void chunkMembers(long guildId)
      Request all guild members for the given guild.
      Parameters:
      guildId - Guild to request for.

    • chunkMembers

      default void chunkMembers(@Nonnull String guildId)
      Request all guild members for the given guild.
      Parameters:
      guildId - Guild to request for.

    • chunkMembers

      default void chunkMembers(long guildId, @Nonnull String query)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      query - Member names must start with this.

    • chunkMembers

      default void chunkMembers(@Nonnull String guildId, @Nonnull String query)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      query - Member names must start with this.

    • chunkMembers

      default void chunkMembers(long guildId, @Nonnegative int limit)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      limit - Maximum number of members to return. 0 for no limit.

    • chunkMembers

      default void chunkMembers(@Nonnull String guildId, @Nonnegative int limit)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      limit - Maximum number of members to return. 0 for no limit.

    • chunkMembers

      default void chunkMembers(long guildId, @Nonnull String query, @Nonnegative int limit)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      query - Members returned must have a username starting with this.
      limit - Maximum number of members to return. 0 for no limit.

    • chunkMembers

      default void chunkMembers(@Nonnull String guildId, @Nonnull String nonce, boolean _useless)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      nonce - Nonce to use for knowing which chunks came from which request.
      _useless - Differentiates this method from chunkMembers(String, String). Otherwise useless.

    • chunkMembers

      default void chunkMembers(@Nonnull String guildId, @Nonnull String query, @Nonnull String nonce)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      query - Members returned must have a username starting with this.
      nonce - Nonce to use for knowing which chunks came from which request.

    • chunkMembers

      default void chunkMembers(@Nonnull String guildId, @Nonnegative int limit, @Nonnull String nonce)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      limit - Maximum number of members to return. 0 for no limit.
      nonce - Nonce to use for knowing which chunks came from which request.

    • chunkMembers

      void chunkMembers(@Nonnull String guildId, @Nonnull String query, @Nonnegative int limit, @Nullable String nonce)
      Request guild members for the given guild.
      Parameters:
      guildId - Guild to request for.
      query - Members returned must have a username starting with this.
      limit - Maximum number of members to return. 0 for no limit.
      nonce - Nonce to use for knowing which chunks came from which request.

    • presence

      Presence presence(@Nonnegative int shardId)
      Get the presence for the specified shard.
      Parameters:
      shardId - The shard id to get presence for.
      Returns:
      The shard's presence.

    • presence

      void presence(@Nonnull Presence presence)
      Update the presence for all shards.
      Parameters:
      presence - The new presence to set.

    • presence

      void presence(@Nonnull Presence presence, @Nonnegative int shardId)
      Update the presence for a specific shard.
      Parameters:
      presence - The new presence to set.
      shardId - The shard to set presence for.

    • presence

      void presence(@Nullable Presence.OnlineStatus status, @Nullable String game, @Nullable Presence.ActivityType type, @Nullable String url)
      Update the presence for all shards by specifying each part of the presence individually.
      Parameters:
      status - The new online status. Set to null for online.
      game - The new game name. Set to null to clear.
      type - The type of the new game status. Set to null for "playing."
      url - The new URL for the presence. Will be ignored if type is not Presence.ActivityType.STREAMING.

    • status

      default void status(@Nonnull Presence.OnlineStatus status)
      Update the online status for all shards. Will clear the activity status.
      Parameters:
      status - The new online status to set.

    • game

      default void game(@Nonnull String game, @Nonnull Presence.ActivityType type, @Nullable String url)
      Update the activity status for all shards. Will set the online status to Presence.OnlineStatus.ONLINE
      Parameters:
      game - The new game to set.
      type - The type of the activity.
      url - The URL if streaming. Will be ignored if type is not Presence.ActivityType.STREAMING.

    • observable

      default <T> io.reactivex.rxjava3.core.Observable<T> observable(@Nonnull EventType<T> type)
      Add a reactive stream handler for events of the given type. Can be disposed of with Observable.unsubscribeOn(Scheduler). The scheduler argument can be created with rxScheduler().

      This method automatically subscribes on rxScheduler().

      Type Parameters:
      T - The object type of the event being streamed.
      Parameters:
      type - The type of event to stream.
      Returns:
      The observable.

    • flowable

      default <T> io.reactivex.rxjava3.core.Flowable<T> flowable(@Nonnull EventType<T> type)
      Add a reactive stream handler for events of the given type. Can be disposed of with Flowable.unsubscribeOn(Scheduler). The scheduler argument can be created with rxScheduler().

      This method automatically subscribes on rxScheduler().

      Type Parameters:
      T - The object type of the event being streamed.
      Parameters:
      type - The type of event to stream.
      Returns:
      The flowable.

    • observable

      default <T, E> io.reactivex.rxjava3.core.Observable<org.apache.commons.lang3.tuple.Pair<T,E>> observable(@Nonnull DoubleEventType<T,E> type)
      Add a reactive stream handler for events of the given type. Can be disposed of with Observable.unsubscribeOn(Scheduler). The scheduler argument can be created with rxScheduler().

      This method automatically subscribes on rxScheduler().

      Type Parameters:
      T - The object type of the event being streamed.
      E - The object type of the event being streamed.
      Parameters:
      type - The type of event to stream.
      Returns:
      The observable.

    • flowable

      default <T, E> io.reactivex.rxjava3.core.Flowable<org.apache.commons.lang3.tuple.Pair<T,E>> flowable(@Nonnull DoubleEventType<T,E> type)
      Add a reactive stream handler for events of the given type. Can be disposed of with Flowable.unsubscribeOn(Scheduler). The scheduler argument can be created with rxScheduler().

      This method automatically subscribes on rxScheduler().

      Type Parameters:
      T - The object type of the event being streamed.
      E - The object type of the event being streamed.
      Parameters:
      type - The type of event to stream.
      Returns:
      The flowable.

    • shutdown

      void shutdown()
      Shutdown the catnip instance, and undeploy all shards.

    • parseWebhook

      default io.reactivex.rxjava3.core.Single<Webhook> parseWebhook(String webhookUrl)
      Get a webhook object for the specified webhook URL. This method will attempt to validate the webhook.
      Parameters:
      webhookUrl - The URL of the webhook.
      Returns:
      A Single that completes when the webhook is validated.

    • parseWebhook

      default io.reactivex.rxjava3.core.Single<Webhook> parseWebhook(String id, String token)
      Get a webhook object for the specified webhook URL. This method will attempt to validate the webhook.
      Parameters:
      id - The webhook's id.
      token - The webhook's token.
      Returns:
      A Single that completes when the webhook is validated.

    • close

      default void close()
      Specified by:
      close in interface AutoCloseable

    • validateSignature

      default boolean validateSignature(@Nonnull String signature, @Nonnull String ts, @Nonnull String data)
      Validates an ed25519 signature for interactions.
      Parameters:
      signature - The signature to validate. This is the x-signature-ed25519 header.
      ts - The timestamp of the request. This is the x-signature-timestamp heaqder.
      data - The data to validate. This is the body of the request.
      Returns:
      Whether or not the signature is valid.

    • entityBuilder

      EntityBuilder entityBuilder()
      The entity builder used by this catnip instance. This is exposed publicly so that, if necessary, it can be used to construct entities from JSON objects as needed.
      Returns:
      This catnip instance's EntityBuilder.