Package dev.sympho.modular_commands.execute

Class PipelineBuilder<E extends Event,CTX extends InstrumentedContext & LazyContext,H extends Handlers,I extends SmartIterator<String>>

java.lang.Object
dev.sympho.modular_commands.execute.PipelineBuilder<E,CTX,H,I>
Type Parameters:
E - The type of event that triggers commands.
CTX - The type of command context.
H - The type of handlers.
I - The iterator type used to traverse the received arguments.
public abstract class PipelineBuilder<E extends Event,CTX extends InstrumentedContext & LazyContext,H extends Handlers,I extends SmartIterator<String>> extends Object
Type responsible for building a command processing pipeline.
Since:
1.0
Version:
1.0
API Note:
Note that, for the purposes of this class, there is a distinction between args and arguments:
  • args is the raw sequence of strings provided by the triggering event that identifies the command to execute. It may or may not also contain, after the command identifiers, strings that should be parsed into command arguments.
  • arguments are the values that satisfy the defined parameters of a command. They may be obtain from args that appear after the command identification, or directly from the event in some way (or both).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final AccessManager
    accessManager
    The access manager to use for access checks.
    protected final io.micrometer.core.instrument.MeterRegistry
    meters
    The meter registry to use.
    protected final io.micrometer.observation.ObservationRegistry
    observations
    The observation registry to use.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    PipelineBuilder(AccessManager accessManager, io.micrometer.core.instrument.MeterRegistry meters, io.micrometer.observation.ObservationRegistry observations)
    Creates a new instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected AccessValidator
    accessValidator(E event)
    Creates an access validator for the context of the given event.
    protected final <T> Function<Mono<T>,Mono<T>>
    addTags(E event)
    Creates a function that adds the common instrumentation tags for the given event to Monos.
    Mono<Void>
    buildPipeline(GatewayDiscordClient client, Registry registry)
    Builds a new pipeline with the given client and registry.
    protected abstract Class<H>
    commandType()
    Retrives the command type to use.
    protected boolean
    eventFilter(E event)
    Determines if an event should be processed for commands.
    protected abstract Class<E>
    eventType()
    Retrieves the event type to listen for.
    protected abstract boolean
    fullMatch()
    Determines whether a parsed arg list (as given by parse(Event)) must always be fully matched to a command.
    protected abstract User
    getCaller(E event)
    Retrieves the user that invoked the command from the triggering event.
    protected abstract Mono<MessageChannel>
    getChannel(E event)
    Retrieves the channel where the command was invoked from the triggering event.
    protected abstract Snowflake
    getChannelId(E event)
    Retrieves the ID of the channel where the command was invoked from the triggering event.
    protected abstract Mono<Guild>
    getGuild(E event)
    Retrieves the guild where the command was invoked, if any, from the triggering event.
    protected abstract Optional<Snowflake>
    getGuildId(E event)
    Retrieves the ID of the guild where the command was invoked, if any, from the triggering event.
    protected abstract InvocationHandler<? super CTX>
    getInvocationHandler(H handlers)
    Retrieves the invocation handler specified by the given hander set.
    protected abstract List<? extends ResultHandler<? super CTX>>
    getResultHandlers(H handlers)
    Retrieves the result handlers specified by the given hander set.
    protected abstract InvocationValidator<E>
    getValidator()
    Retrieves the validator to use for validating command invocations.
    protected abstract CTX
    makeContext(E event, Command<? extends H> command, Invocation invocation, I args)
    Creates a command context from a parsed invocation.
    protected abstract I
    parse(E event)
    Parses the raw args from the event.
    protected abstract Metrics.Tag.Type
    tagType()
    Determines the type tag for this pipeline.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • accessManager

      protected final AccessManager accessManager
      The access manager to use for access checks.

    • meters

      protected final io.micrometer.core.instrument.MeterRegistry meters
      The meter registry to use.

    • observations

      protected final io.micrometer.observation.ObservationRegistry observations
      The observation registry to use.

  • Constructor Details

    • PipelineBuilder

      protected PipelineBuilder(AccessManager accessManager, io.micrometer.core.instrument.MeterRegistry meters, io.micrometer.observation.ObservationRegistry observations)
      Creates a new instance.
      Parameters:
      accessManager - The access manager to use for access checks.
      meters - The meter registry to use.
      observations - The observation registry to use.

  • Method Details

    • buildPipeline

      public Mono<Void> buildPipeline(GatewayDiscordClient client, Registry registry)
      Builds a new pipeline with the given client and registry.
      Parameters:
      client - The client to receive events from.
      registry - The registry to use to look up commands.
      Returns:
      The built processing pipeline.

    • tagType

      @Pure protected abstract Metrics.Tag.Type tagType()
      Determines the type tag for this pipeline.
      Returns:
      The tag.

    • addTags

      @SideEffectFree protected final <T> Function<Mono<T>,Mono<T>> addTags(E event)
      Creates a function that adds the common instrumentation tags for the given event to Monos.
      Type Parameters:
      T - The mono value type.
      Parameters:
      event - The event.
      Returns:
      The function.

    • eventType

      @Pure protected abstract Class<E> eventType()
      Retrieves the event type to listen for.
      Returns:
      The event type.

    • commandType

      @Pure protected abstract Class<H> commandType()
      Retrives the command type to use.
      Returns:
      The command type.

    • fullMatch

      @Pure protected abstract boolean fullMatch()
      Determines whether a parsed arg list (as given by parse(Event)) must always be fully matched to a command. If true, the presence of leftover args (as would be received by makeContext(Event, Command, Invocation, SmartIterator)) triggers an error for that event (stopping the processing of that particular event, but without stopping the pipeline).
      Returns:
      true if the parsed args must be fully matched to a command. false if additional args are allowed.
      API Note:
      This check is not related to any user-facing functionality, but purely as an internal sanity check. If an event provides arguments in a way other than the parsed args, with said args being used only to identify the command to execute, it would not make sense for extra args to be received.

      For example, in a slash command, the comand name is provided separately from the arguments, and any subcommands are already labeled as such, so there is no need to evaluate any further args when looking up the command. At the same time, since slash commands (including subcommands) have to be registered with Discord ahead of time to be callable by users, the only way that a slash command event would provide a subcommand that is not found is if the command was registered to Discord without having a corresponding internal handler, without would indicate an inconsistency in the command system (the declared commands do not match the implemented commands), which should be reported to the administrator as a (non-fatal) pipeline error.

    • eventFilter

      @Pure protected boolean eventFilter(E event)
      Determines if an event should be processed for commands. This filter is applied at the start of handling, before any parsing is performed.
      Parameters:
      event - The event to check.
      Returns:
      true if the event should be processed. false if the event should be discarded.
      Implementation Requirements:
      The default is to process all received events.

    • getValidator

      @Pure protected abstract InvocationValidator<E> getValidator()
      Retrieves the validator to use for validating command invocations.

      For performance reasons, the validator should be implemented statelessly, with a single instance being created by the implenting builder which is then returned every time. This avoids the cost of constructing a new instance every time.

      Note that there is no reason why a validator implementation would need to keep state, as it is intended to be a simple filter.

      Returns:
      The validator to use.

    • parse

      @SideEffectFree protected abstract I parse(E event)
      Parses the raw args from the event. This includes the names that identify the command and subcommands, as well as any additional args, if allowed.
      Parameters:
      event - The event to parse args from.
      Returns:
      The parsed args. May have no elements if the event should not be handled as a command.

    • makeContext

      @SideEffectFree protected abstract CTX makeContext(E event, Command<? extends H> command, Invocation invocation, I args)
      Creates a command context from a parsed invocation.
      Parameters:
      event - The event being processed.
      command - The identified command.
      invocation - The invocation that mapped to the command. This may be different from the command's declared Command.invocation() if it was invoked using an alias (when supported).
      args - The args that remained after removing the command identifiers. If fullMatch() is true, this will always be empty.
      Returns:
      The context that represents the given invocation.

    • getGuildId

      @SideEffectFree protected abstract Optional<Snowflake> getGuildId(E event)
      Retrieves the ID of the guild where the command was invoked, if any, from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The ID of the guild where the event was invoked.

    • getGuild

      @SideEffectFree protected abstract Mono<Guild> getGuild(E event)
      Retrieves the guild where the command was invoked, if any, from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The guild where the event was invoked.

    • getChannelId

      @SideEffectFree protected abstract Snowflake getChannelId(E event)
      Retrieves the ID of the channel where the command was invoked from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The ID of the channel where the event was invoked.

    • getChannel

      @SideEffectFree protected abstract Mono<MessageChannel> getChannel(E event)
      Retrieves the channel where the command was invoked from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The channel where the event was invoked.

    • getCaller

      @SideEffectFree protected abstract User getCaller(E event)
      Retrieves the user that invoked the command from the triggering event.
      Parameters:
      event - The triggering event.
      Returns:
      The user that invoked the command.

    • accessValidator

      @SideEffectFree protected AccessValidator accessValidator(E event)
      Creates an access validator for the context of the given event.
      Parameters:
      event - The triggering event.
      Returns:
      The access validator.

    • getInvocationHandler

      @Pure protected abstract InvocationHandler<? super CTX> getInvocationHandler(H handlers)
      Retrieves the invocation handler specified by the given hander set.
      Parameters:
      handlers - The handler set.
      Returns:
      The invocation handler.

    • getResultHandlers

      @Pure protected abstract List<? extends ResultHandler<? super CTX>> getResultHandlers(H handlers)
      Retrieves the result handlers specified by the given hander set.
      Parameters:
      handlers - The handler set.
      Returns:
      The result handlers.