Package cloud.commandframework

Class CommandManager<C>

java.lang.Object
cloud.commandframework.CommandManager<C>
Type Parameters:
C - Command sender type
Direct Known Subclasses:
LockableCommandManager
public abstract class CommandManager<C> extends Object
The manager is responsible for command registration, parsing delegation, etc.

  • Constructor Details

    • CommandManager

      protected CommandManager​(@NonNull Function<@NonNull CommandTree<C>,​@NonNull CommandExecutionCoordinator<C>> commandExecutionCoordinator, @NonNull CommandRegistrationHandler commandRegistrationHandler)
      Create a new command manager instance
      Parameters:
      commandExecutionCoordinator - Execution coordinator instance. The coordinator is in charge of executing incoming commands. Some considerations must be made when picking a suitable execution coordinator for your platform. For example, an entirely asynchronous coordinator is not suitable when the parsers used in that particular platform are not thread safe. If you have commands that perform blocking operations, however, it might not be a good idea to use a synchronous execution coordinator. In most cases you will want to pick between CommandExecutionCoordinator.simpleCoordinator() and AsynchronousCommandExecutionCoordinator
      commandRegistrationHandler - Command registration handler. This will get called every time a new command is registered to the command manager. This may be used to forward command registration to the platform.

  • Method Details

    • executeCommand

      public @NonNull CompletableFuture<CommandResult<C>> executeCommand​(@NonNull C commandSender, @NonNull String input)
      Execute a command and get a future that completes with the result. The command may be executed immediately or at some point in the future, depending on the CommandExecutionCoordinator used in the command manager.

      The command may also be filtered out by preprocessors (see CommandPreprocessor) before they are parsed, or by the CommandArgument command arguments during parsing. The execution may also be filtered out after parsing by a CommandPostprocessor. In the case that a command was filtered out at any of the execution stages, the future will complete with null.

      The future may also complete exceptionally. The command manager contains some utilities that allow users to register exception handlers (registerExceptionHandler(Class, BiConsumer) and these can be retrieved using getExceptionHandler(Class), or used with handleException(Object, Class, Exception, BiConsumer). It is highly recommended that these methods are used in the command manager, as it allows users of the command manager to override the exception handling as they wish.

      Parameters:
      commandSender - Sender of the command
      input - Input provided by the sender. Prefixes should be removed before the method is being called, and the input here will be passed directly to the command parsing pipeline, after having been tokenized.
      Returns:
      future that completes with the command result, or null if the execution was cancelled at any of the processing stages.

    • suggest

      public @NonNull List<@NonNull String> suggest​(@NonNull C commandSender, @NonNull String input)
      Get command suggestions for the "next" argument that would yield a correctly parsing command input. The command suggestions provided by the command argument parsers will be filtered using the CommandSuggestionProcessor before being returned.
      Parameters:
      commandSender - Sender of the command
      input - Input provided by the sender. Prefixes should be removed before the method is being called, and the input here will be passed directly to the command parsing pipeline, after having been tokenized.
      Returns:
      List of suggestions

    • command

      public @NonNull CommandManager<C> command​(@NonNull Command<C> command)
      Register a new command to the command manager and insert it into the underlying command tree. The command will be forwarded to the CommandRegistrationHandler and will, depending on the platform, be forwarded to the platform.

      Different command manager implementations have different requirements for the command registration. It is possible that a command manager may only allow registration during certain stages of the application lifetime. Read the platform command manager documentation to find out more about your particular platform

      Parameters:
      command - Command to register
      Returns:
      The command manager instance. This is returned so that these method calls may be chained. This will always return this.

    • command

      public @NonNull CommandManager<C> command​(@NonNull Command.Builder<C> command)
      Register a new command
      Parameters:
      command - Command to register. Command.Builder.build()} will be invoked.
      Returns:
      The command manager instance

    • getCommandSyntaxFormatter

      public @NonNull CommandSyntaxFormatter<C> getCommandSyntaxFormatter()
      Get the command syntax formatter
      Returns:
      Command syntax formatter

    • setCommandSyntaxFormatter

      public void setCommandSyntaxFormatter​(@NonNull CommandSyntaxFormatter<C> commandSyntaxFormatter)
      Set the command syntax formatter
      Parameters:
      commandSyntaxFormatter - New formatter

    • getCommandRegistrationHandler

      public @NonNull CommandRegistrationHandler getCommandRegistrationHandler()
      Get the command registration handler
      Returns:
      Command registration handler

    • setCommandRegistrationHandler

      protected final void setCommandRegistrationHandler​(@NonNull CommandRegistrationHandler commandRegistrationHandler)

    • hasPermission

      public boolean hasPermission​(@NonNull C sender, @NonNull CommandPermission permission)
      Check if the command sender has the required permission. If the permission node is empty, this should return true
      Parameters:
      sender - Command sender
      permission - Permission node
      Returns:
      true if the sender has the permission, else false

    • getCaptionRegistry

      public final @NonNull CaptionRegistry<C> getCaptionRegistry()
      Get the caption registry
      Returns:
      Caption registry

    • setCaptionRegistry

      public final void setCaptionRegistry​(@NonNull CaptionRegistry<C> captionRegistry)
      Replace the caption registry. Some platforms may inject their own captions into the default registry, and so you may need to insert these captions yourself if you do decide to replace the caption registry.
      Parameters:
      captionRegistry - New caption registry

    • registerDefaultCaptions

      @Deprecated public final void registerDefaultCaptions​(@NonNull CaptionRegistry<C> captionRegistry)
      Deprecated.
      Use setCaptionRegistry(CaptionRegistry) These methods are identical.
      Replace the default caption registry
      Parameters:
      captionRegistry - Caption registry to use

    • hasPermission

      public abstract boolean hasPermission​(@NonNull C sender, @NonNull String permission)
      Check if the command sender has the required permission. If the permission node is empty, this should return true
      Parameters:
      sender - Command sender
      permission - Permission node
      Returns:
      true if the sender has the permission, else false

    • commandBuilder

      @Deprecated public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull Collection<String> aliases, @NonNull Description description, @NonNull CommandMeta meta)
      Deprecated.
      for removal since 1.4.0. Use commandBuilder(String, Collection, Description, CommandMeta) instead.
      Create a new command builder. This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      aliases - Command aliases
      description - Description for the root literal
      meta - Command meta
      Returns:
      Builder instance

    • commandBuilder

      public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull Collection<String> aliases, @NonNull ArgumentDescription description, @NonNull CommandMeta meta)
      Create a new command builder. This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      aliases - Command aliases
      description - Description for the root literal
      meta - Command meta
      Returns:
      Builder instance
      Since:
      1.4.0

    • commandBuilder

      public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull Collection<String> aliases, @NonNull CommandMeta meta)
      Create a new command builder with an empty description.

      This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      aliases - Command aliases
      meta - Command meta
      Returns:
      Builder instance

    • commandBuilder

      @Deprecated public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull CommandMeta meta, @NonNull Description description, @NonNull String... aliases)
      Deprecated.
      for removal since 1.4.0. Use commandBuilder(String, CommandMeta, ArgumentDescription, String...) instead.
      Create a new command builder. This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      meta - Command meta
      description - Description for the root literal
      aliases - Command aliases
      Returns:
      Builder instance

    • commandBuilder

      public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull CommandMeta meta, @NonNull ArgumentDescription description, @NonNull String... aliases)
      Create a new command builder. This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      meta - Command meta
      description - Description for the root literal
      aliases - Command aliases
      Returns:
      Builder instance
      Since:
      1.4.0

    • commandBuilder

      public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull CommandMeta meta, @NonNull String... aliases)
      Create a new command builder with an empty description.

      This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      meta - Command meta
      aliases - Command aliases
      Returns:
      Builder instance

    • commandBuilder

      @Deprecated public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull Description description, @NonNull String... aliases)
      Deprecated.
      for removal since 1.4.0. Use commandBuilder(String, ArgumentDescription, String...) instead.
      Create a new command builder using default command meta created by createDefaultCommandMeta().

      This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      description - Description for the root literal
      aliases - Command aliases
      Returns:
      Builder instance
      Throws:
      UnsupportedOperationException - If the command manager does not support default command meta creation
      See Also:
      Default command meta creation

    • commandBuilder

      public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull ArgumentDescription description, @NonNull String... aliases)
      Create a new command builder using default command meta created by createDefaultCommandMeta().

      This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      description - Description for the root literal
      aliases - Command aliases
      Returns:
      Builder instance
      Throws:
      UnsupportedOperationException - If the command manager does not support default command meta creation
      Since:
      1.4.0
      See Also:
      Default command meta creation

    • commandBuilder

      public @NonNull Command.Builder<C> commandBuilder​(@NonNull String name, @NonNull String... aliases)
      Create a new command builder using default command meta created by createDefaultCommandMeta(), and an empty description.

      This will also register the creating manager in the command builder using Command.Builder.manager(CommandManager), so that the command builder is associated with the creating manager. This allows for parser inference based on the type, with the help of the parser registry

      This method will not register the command in the manager. To do that, command(Command.Builder) or command(Command) has to be invoked with either the Command.Builder instance, or the constructed command instance

      Parameters:
      name - Command name
      aliases - Command aliases
      Returns:
      Builder instance
      Throws:
      UnsupportedOperationException - If the command manager does not support default command meta creation
      See Also:
      Default command meta creation

    • argumentBuilder

      public <T> @NonNull CommandArgument.Builder<C,​T> argumentBuilder​(@NonNull Class<T> type, @NonNull String name)
      Create a new command argument builder.

      This will also invoke CommandArgument.Builder.manager(CommandManager) so that the argument is associated with the calling command manager. This allows for parser inference based on the type, with the help of the parser registry.

      Type Parameters:
      T - Generic argument name
      Parameters:
      type - Argument type
      name - Argument name
      Returns:
      Argument builder

    • flagBuilder

      public @NonNull CommandFlag.Builder<Void> flagBuilder​(@NonNull String name)
      Create a new command flag builder
      Parameters:
      name - Flag name
      Returns:
      Flag builder

    • getCommandTree

      public @NonNull CommandTree<C> getCommandTree()
      Get the internal command tree. This should not be accessed unless you know what you are doing
      Returns:
      Command tree

    • createDefaultCommandMeta

      public abstract @NonNull CommandMeta createDefaultCommandMeta()
      Construct a default command meta instance
      Returns:
      Default command meta
      Throws:
      UnsupportedOperationException - If the command manager does not support this operation

    • registerCommandPreProcessor

      public void registerCommandPreProcessor​(@NonNull CommandPreprocessor<C> processor)
      Register a new command preprocessor. The order they are registered in is respected, and they are called in LIFO order
      Parameters:
      processor - Processor to register
      See Also:
      Preprocess a context

    • registerCommandPostProcessor

      public void registerCommandPostProcessor​(@NonNull CommandPostprocessor<C> processor)
      Register a new command postprocessor. The order they are registered in is respected, and they are called in LIFO order
      Parameters:
      processor - Processor to register
      See Also:
      Preprocess a context

    • preprocessContext

      public cloud.commandframework.services.State preprocessContext​(@NonNull CommandContext<C> context, @NonNull LinkedList<@NonNull String> inputQueue)
      Preprocess a command context instance
      Parameters:
      context - Command context
      inputQueue - Command input as supplied by sender
      Returns:
      State.ACCEPTED if the command should be parsed and executed, else State.REJECTED
      See Also:
      Register a command preprocessor

    • postprocessContext

      public cloud.commandframework.services.State postprocessContext​(@NonNull CommandContext<C> context, @NonNull Command<C> command)
      Postprocess a command context instance
      Parameters:
      context - Command context
      command - Command instance
      Returns:
      State.ACCEPTED if the command should be parsed and executed, else State.REJECTED
      See Also:
      Register a command postprocessor

    • getCommandSuggestionProcessor

      public @NonNull CommandSuggestionProcessor<C> getCommandSuggestionProcessor()
      Get the command suggestions processor instance currently used in this command manager
      Returns:
      Command suggestions processor
      See Also:
      Setting the suggestion processor

    • setCommandSuggestionProcessor

      public void setCommandSuggestionProcessor​(@NonNull CommandSuggestionProcessor<C> commandSuggestionProcessor)
      Set the command suggestions processor for this command manager. This will be called every time suggest(Object, String) is called, to process the list of suggestions before it's returned to the caller
      Parameters:
      commandSuggestionProcessor - New command suggestions processor

    • getParserRegistry

      public ParserRegistry<C> getParserRegistry()
      Get the parser registry instance. The parser registry contains default mappings to ArgumentParser and allows for the registration of custom mappings. The parser registry also contains mappings of annotations to ParserParameter which allows for annotations to be used to customize parser settings.

      When creating a new parser type, it is recommended to register it in the parser registry. In particular, default parser types (shipped with cloud implementations) should be registered in the constructor of the platform CommandManager

      Returns:
      Parser registry instance

    • parameterInjectorRegistry

      public final @NonNull ParameterInjectorRegistry<C> parameterInjectorRegistry()
      Get the parameter injector registry instance
      Returns:
      Parameter injector registry
      Since:
      1.3.0

    • getExceptionHandler

      public final <E extends Exception> @Nullable BiConsumer<@NonNull C,​@NonNull E> getExceptionHandler​(@NonNull Class<E> clazz)
      Get the exception handler for an exception type, if one has been registered
      Type Parameters:
      E - Exception type
      Parameters:
      clazz - Exception class
      Returns:
      Exception handler, or null
      See Also:
      Registering an exception handler

    • registerExceptionHandler

      public final <E extends Exception> void registerExceptionHandler​(@NonNull Class<E> clazz, @NonNull BiConsumer<@NonNull C,​@NonNull E> handler)
      Register an exception handler for an exception type. This will then be used when handleException(Object, Class, Exception, BiConsumer) is called for the particular exception type
      Type Parameters:
      E - Exception type
      Parameters:
      clazz - Exception class
      handler - Exception handler

    • handleException

      public final <E extends Exception> void handleException​(@NonNull C sender, @NonNull Class<E> clazz, @NonNull E exception, @NonNull BiConsumer<C,​E> defaultHandler)
      Handle an exception using the registered exception handler for the exception type, or using the provided default handler if no exception handler has been registered for the exception type
      Type Parameters:
      E - Exception type
      Parameters:
      sender - Executing command sender
      clazz - Exception class
      exception - Exception instance
      defaultHandler - Default exception handler. Will be called if there is no exception handler stored for the exception type

    • getCommands

      public final @NonNull Collection<@NonNull Command<C>> getCommands()
      Get a collection containing all registered commands.
      Returns:
      Unmodifiable view of all registered commands

    • getCommandHelpHandler

      public final @NonNull CommandHelpHandler<C> getCommandHelpHandler()
      Get a command help handler instance. This can be used to assist in the production of command help menus, etc. This command help handler instance will display all commands registered in this command manager.
      Returns:
      Command help handler. A new instance will be created each time this method is called.

    • getCommandHelpHandler

      public final @NonNull CommandHelpHandler<C> getCommandHelpHandler​(@NonNull Predicate<Command<C>> commandPredicate)
      Get a command help handler instance. This can be used to assist in the production of command help menus, etc. A predicate can be specified to filter what commands registered in this command manager are visible in the help menu.
      Parameters:
      commandPredicate - Predicate that filters what commands are displayed in the help menu.
      Returns:
      Command help handler. A new instance will be created each time this method is called.

    • getSetting

      public boolean getSetting​(@NonNull CommandManager.ManagerSettings setting)
      Get a command manager setting
      Parameters:
      setting - Setting
      Returns:
      true if the setting is activated or false if it's not
      See Also:
      Update a manager setting

    • setSetting

      public void setSetting​(@NonNull CommandManager.ManagerSettings setting, boolean value)
      Update a command manager setting
      Parameters:
      setting - Setting to update
      value - Value. In most cases true will enable a feature, whereas false will disable it. The value passed to the method will be reflected in getSetting(ManagerSettings)
      See Also:
      Get a manager setting

    • transitionOrThrow

      protected final void transitionOrThrow​(@NonNull CommandManager.RegistrationState in, @NonNull CommandManager.RegistrationState out)
      Transition from the in state to the out state, if the manager is not already in that state.
      Parameters:
      in - The starting state
      out - The ending state
      Throws:
      IllegalStateException - if the manager is in any state but in or out
      Since:
      1.2.0

    • transitionIfPossible

      protected final boolean transitionIfPossible​(@NonNull CommandManager.RegistrationState in, @NonNull CommandManager.RegistrationState out)
      Transition from the in state to the out state, if the manager is not already in that state.
      Parameters:
      in - The starting state
      out - The ending state
      Returns:
      true if the state transition was successful, or the manager was already in the desired state
      Since:
      1.2.0

    • requireState

      protected final void requireState​(@NonNull CommandManager.RegistrationState expected)
      Require that the commands manager is in a certain state.
      Parameters:
      expected - The required state
      Throws:
      IllegalStateException - if the manager is not in the expected state
      Since:
      1.2.0

    • lockRegistration

      protected final void lockRegistration()
      Transition the command manager from either CommandManager.RegistrationState.BEFORE_REGISTRATION or CommandManager.RegistrationState.REGISTERING to CommandManager.RegistrationState.AFTER_REGISTRATION.
      Throws:
      IllegalStateException - if the manager is not in the expected state
      Since:
      1.4.0

    • getRegistrationState

      public final @NonNull CommandManager.RegistrationState getRegistrationState()
      Get the active registration state for this manager.

      If this state is CommandManager.RegistrationState.AFTER_REGISTRATION, commands can no longer be registered

      Returns:
      The current state
      Since:
      1.2.0

    • isCommandRegistrationAllowed

      public boolean isCommandRegistrationAllowed()
      Check if command registration is allowed.

      On platforms where unsafe registration is possible, this can be overridden by enabling the CommandManager.ManagerSettings.ALLOW_UNSAFE_REGISTRATION setting.

      Returns:
      true if the registration is allowed, else false
      Since:
      1.2.0