Package cloud.commandframework

Class CommandManager<C>

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

    • Constructor Detail

      • CommandManager

        protected CommandManager​(@NonNull java.util.function.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 Detail

      • executeCommand

        public @NonNull java.util.concurrent.CompletableFuture<CommandResult<C>> executeCommand​(@NonNull C commandSender,
                                                                                        @NonNull java.lang.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 java.util.List<@NonNull java.lang.String> suggest​(@NonNull C commandSender,
                                                                  @NonNull java.lang.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.

      • 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 java.lang.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

        public @NonNull Command.Builder<C> commandBuilder​(@NonNull java.lang.String name,
                                                  @NonNull java.util.Collection<java.lang.String> aliases,
                                                  @NonNull Description 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 - Command description
        meta - Command meta
        Returns:
        Builder instance

      • commandBuilder

        public @NonNull Command.Builder<C> commandBuilder​(@NonNull java.lang.String name,
                                                  @NonNull java.util.Collection<java.lang.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

        public @NonNull Command.Builder<C> commandBuilder​(@NonNull java.lang.String name,
                                                  @NonNull CommandMeta meta,
                                                  @NonNull Description description,
                                                  @NonNull java.lang.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 - Command description
        aliases - Command aliases
        Returns:
        Builder instance

      • commandBuilder

        public @NonNull Command.Builder<C> commandBuilder​(@NonNull java.lang.String name,
                                                  @NonNull CommandMeta meta,
                                                  @NonNull java.lang.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

        public @NonNull Command.Builder<C> commandBuilder​(@NonNull java.lang.String name,
                                                  @NonNull Description description,
                                                  @NonNull java.lang.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 - Command description
        aliases - Command aliases
        Returns:
        Builder instance
        Throws:
        java.lang.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 java.lang.String name,
                                                  @NonNull java.lang.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:
        java.lang.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 java.lang.Class<T> type,
                                                                       @NonNull java.lang.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<java.lang.Void> flagBuilder​(@NonNull java.lang.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:
        java.lang.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 java.util.LinkedList<@NonNull java.lang.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

      • 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

      • getExceptionHandler

        public final <E extends java.lang.Exception> @Nullable java.util.function.BiConsumer<@NonNull C,​@NonNull E> getExceptionHandler​(@NonNull java.lang.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 java.lang.Exception> void registerExceptionHandler​(@NonNull java.lang.Class<E> clazz,
                                                                           @NonNull java.util.function.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 java.lang.Exception> void handleException​(@NonNull C sender,
                                                                  @NonNull java.lang.Class<E> clazz,
                                                                  @NonNull E exception,
                                                                  @NonNull java.util.function.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 java.util.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.
        Returns:
        Command help handler. A new instance will be created each time this method is called.