Package org.incendo.cloud

Class CommandManager<C>

java.lang.Object

org.incendo.cloud.CommandManager<C>

Type Parameters:

C - the command sender type used to execute commands

All Implemented Interfaces:

CommandBuilderSource<C>, Stateful<RegistrationState>

@API(status=STABLE)
public abstract class CommandManager<C>
extends Object
implements Stateful<RegistrationState>, CommandBuilderSource<C>

The manager is responsible for command registration, parsing delegation, etc.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	CommandManager(@NonNull ExecutionCoordinator<C> executionCoordinator, @NonNull CommandRegistrationHandler<C> commandRegistrationHandler)	Create a new command manager instance.

Method Summary

Modifier and Type	Method	Description
void	appendSuggestionMapper(@NonNull SuggestionMapper<? extends Suggestion> mapper)	Sets the suggestion mapper for suggestionFactory() to the result of appending the provided mapper to the current mapper using SuggestionMapper.then(SuggestionMapper).
@NonNull Collection<@NonNull CloudCapability>	capabilities()	Returns an unmodifiable snapshot of the currently registered capabilities.
@NonNull CaptionFormatter<C,String>	captionFormatter()	Returns the string-producing caption formatter.
void	captionFormatter(@NonNull CaptionFormatter<C,String> captionFormatter)	Sets the string-producing caption formatter.
final @NonNull CaptionRegistry<C>	captionRegistry()	Returns the caption registry.
final void	captionRegistry(@NonNull CaptionRegistry<C> captionRegistry)	Replaces the caption registry.
@NonNull CommandManager<C>	command(@NonNull Command<? extends C> command)	Register a new command to the command manager and insert it into the underlying command tree.
@NonNull CommandManager<C>	command(@NonNull CommandFactory<C> commandFactory)	Creates a command using the given commandFactory and inserts it into the underlying command tree.
@NonNull CommandManager<C>	command(@NonNull Command.Builder<? extends C> command)	Register a new command
@NonNull CommandExecutor<C>	commandExecutor()	Returns the command executor.
@NonNull CommandRegistrationHandler<C>	commandRegistrationHandler()	Returns the command registration handler.
protected final void	commandRegistrationHandler(@NonNull CommandRegistrationHandler<C> commandRegistrationHandler)
final @NonNull Collection<@NonNull Command<C>>	commands()	Returns an unmodifiable view of all registered commands.
@NonNull CommandSyntaxFormatter<C>	commandSyntaxFormatter()	Returns the command syntax formatter.
void	commandSyntaxFormatter(@NonNull CommandSyntaxFormatter<C> commandSyntaxFormatter)	Sets the command syntax formatter.
@NonNull CommandTree<C>	commandTree()	Returns the internal command tree.
<T> @NonNull CommandComponent.Builder<C,T>	componentBuilder(@NonNull Class<T> type, @NonNull String name)	Create a new command component builder.
@NonNull CommandMeta	createDefaultCommandMeta()	Constructs a default CommandMeta instance.
final @NonNull HelpHandler<C>	createHelpHandler()	Creates a new command help handler instance.
final @NonNull HelpHandler<C>	createHelpHandler(@NonNull CommandPredicate<C> filter)	Creates a new command help handler instance.
final @NonNull Command.Builder<C>	decorateBuilder(@NonNull Command.Builder<C> builder)	Invokes Command.Builder.manager(CommandManager) with this instance and returns the updated builder.
void	deleteRootCommand(@NonNull String rootCommand)	Deletes the given rootCommand.
final @NonNull ExceptionController<C>	exceptionController()	Returns the exception controller.
@NonNull CommandFlag.Builder<C,Void>	flagBuilder(@NonNull String name)	Create a new command flag builder
boolean	hasCapability(@NonNull CloudCapability capability)	Checks whether the cloud implementation has the given capability.
abstract boolean	hasPermission(@NonNull C sender, @NonNull String permission)	Check if the command sender has the required permission.
final @NonNull HelpHandlerFactory<C>	helpHandlerFactory()	Returns the help handler factory.
final void	helpHandlerFactory(@NonNull HelpHandlerFactory<C> helpHandlerFactory)	Sets the new help handler factory.
boolean	isCommandRegistrationAllowed()	Check if command registration is allowed.
protected final void	lockRegistration()	Transition the command manager from either RegistrationState.BEFORE_REGISTRATION or RegistrationState.REGISTERING to RegistrationState.AFTER_REGISTRATION.
final @NonNull ParameterInjectorRegistry<C>	parameterInjectorRegistry()	Get the parameter injector registry instance
@NonNull ParserRegistry<C>	parserRegistry()	Returns the parser registry instance.
State	postprocessContext(@NonNull CommandContext<C> context, @NonNull Command<C> command)	Postprocess a command context instance
State	preprocessContext(@NonNull CommandContext<C> context, @NonNull CommandInput commandInput)	Preprocess a command context instance
protected final void	registerCapability(@NonNull CloudCapability capability)	Registers the given capability.
void	registerCommandPostProcessor(@NonNull CommandPostprocessor<C> processor)	Register a new command postprocessor.
void	registerCommandPreProcessor(@NonNull CommandPreprocessor<C> processor)	Register a new command preprocessor.
protected void	registerDefaultExceptionHandlers(@NonNull Consumer<Triplet<CommandContext<C>,Caption,List<@NonNull CaptionVariable>>> messageSender, @NonNull Consumer<Pair<String,Throwable>> logger)	Registers the default exception handlers.
@NonNull Collection<@NonNull String>	rootCommands()	Returns all root command names.
@NonNull Configurable<ManagerSetting>	settings()	Returns a Configurable instance that can be used to modify the settings for this command manager instance.
final @NonNull RegistrationState	state()	Returns the current state.
@NonNull SuggestionFactory<C,? extends Suggestion>	suggestionFactory()	Returns the suggestion factory.
@NonNull SuggestionMapper<? extends Suggestion>	suggestionMapper()	Returns the suggestion mapper for suggestionFactory().
void	suggestionMapper(@NonNull SuggestionMapper<? extends Suggestion> mapper)	Sets the suggestion mapper for suggestionFactory().
@NonNull SuggestionProcessor<C>	suggestionProcessor()	Returns the command suggestion processor used in this command manager.
void	suggestionProcessor(@NonNull SuggestionProcessor<C> suggestionProcessor)	Sets the command suggestion processor.
@NonNull PermissionResult	testPermission(@NonNull C sender, @NonNull Permission permission)	Checks if the command sender has the required permission and returns the result.
final boolean	transitionIfPossible(@NonNull RegistrationState in, @NonNull RegistrationState out)	Transitions from the in state to the out state, unless the current Stateful.state() is identical to the out state.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.incendo.cloud.CommandBuilderSource

commandBuilder, commandBuilder, commandBuilder, commandBuilder, commandBuilder, commandBuilder

Methods inherited from interface org.incendo.cloud.state.Stateful

requireState, transitionOrThrow

Constructor Details

CommandManager

protected CommandManager(@NonNull ExecutionCoordinator<C> executionCoordinator,
 @NonNull CommandRegistrationHandler<C> commandRegistrationHandler)

Create a new command manager instance.

Parameters:

executionCoordinator - Execution coordinator instance. When choosing the appropriate coordinator for your project, be sure to consider any limitations noted by the platform documentation.

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

commandExecutor

@API(status=STABLE)
public @NonNull CommandExecutor<C> commandExecutor()

Returns the command executor.

The executor is used to parse & execute commands.

Returns:

the command executor

suggestionFactory

@API(status=STABLE)
public @NonNull SuggestionFactory<C,? extends Suggestion> suggestionFactory()

Returns the suggestion factory.

Will map results using suggestionMapper().

Returns:

the suggestion factory

suggestionMapper

public @NonNull SuggestionMapper<? extends Suggestion> suggestionMapper()

Returns the suggestion mapper for suggestionFactory().

Platform command managers may replace the default mapper to better support platform suggestion types. Therefore it's encouraged to chain any additional mappers using SuggestionMapper.then(SuggestionMapper) or appendSuggestionMapper(SuggestionMapper), rather than replacing the mapper directly.

Returns:

the suggestion mapper

appendSuggestionMapper

public void appendSuggestionMapper(@NonNull SuggestionMapper<? extends Suggestion> mapper)

Sets the suggestion mapper for suggestionFactory() to the result of appending the provided mapper to the current mapper using SuggestionMapper.then(SuggestionMapper).

Parameters:

mapper - suggestion mapper

suggestionMapper

public void suggestionMapper(@NonNull SuggestionMapper<? extends Suggestion> mapper)

Sets the suggestion mapper for suggestionFactory().

Parameters:

mapper - suggestion mapper

See Also:

• suggestionMapper()

command

public @NonNull CommandManager<C> command(@NonNull Command<? extends 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

@API(status=STABLE)
public @NonNull CommandManager<C> command(@NonNull CommandFactory<C> commandFactory)

Creates a command using the given commandFactory and inserts 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:

commandFactory - the command factory 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<? extends C> command)

Register a new command

Parameters:

command - Command to register. Command.Builder.build()} will be invoked.

Returns:

The command manager instance

captionFormatter

@API(status=STABLE)
public @NonNull CaptionFormatter<C,String> captionFormatter()

Returns the string-producing caption formatter.

Returns:

the formatter

See Also:

• captionFormatter(CaptionFormatter)

captionFormatter

@API(status=STABLE)
public void captionFormatter(@NonNull CaptionFormatter<C,String> captionFormatter)

Sets the string-producing caption formatter.

Parameters:

captionFormatter - the new formatter

See Also:

• captionFormatter()

commandSyntaxFormatter

@API(status=STABLE)
public @NonNull CommandSyntaxFormatter<C> commandSyntaxFormatter()

Returns the command syntax formatter.

Returns:

the syntax formatter

See Also:

• commandSyntaxFormatter(CommandSyntaxFormatter)

commandSyntaxFormatter

@API(status=STABLE)
public void commandSyntaxFormatter(@NonNull CommandSyntaxFormatter<C> commandSyntaxFormatter)

Sets the command syntax formatter.

The command syntax formatter is used to format the command syntax hints that are used in help and error messages.

Parameters:

commandSyntaxFormatter - new formatter

See Also:

• commandSyntaxFormatter()

commandRegistrationHandler

public @NonNull CommandRegistrationHandler<C> commandRegistrationHandler()

Returns the command registration handler.

The command registration handler is able to intercept newly created/deleted commands, in order to propagate these changes to the native command handler of the platform.

In platforms without a native command concept, this is likely to return CommandRegistrationHandler.nullCommandRegistrationHandler().

Returns:

the command registration handler

commandRegistrationHandler

@API(status=STABLE)
protected final void commandRegistrationHandler(@NonNull CommandRegistrationHandler<C> commandRegistrationHandler)

registerCapability

@API(status=STABLE)
protected final void registerCapability(@NonNull CloudCapability capability)

Registers the given capability.

Parameters:

capability - the capability

See Also:

• hasCapability(CloudCapability)
• capabilities()

hasCapability

@API(status=STABLE)
public boolean hasCapability(@NonNull CloudCapability capability)

Checks whether the cloud implementation has the given capability.

Parameters:

capability - the capability

Returns:

true if the implementation has the capability, false if not

See Also:

• capabilities()

capabilities

@API(status=STABLE)
public @NonNull Collection<@NonNull CloudCapability> capabilities()

Returns an unmodifiable snapshot of the currently registered capabilities.

Returns:

the currently registered capabilities

See Also:

• hasCapability(CloudCapability)

testPermission

@API(status=STABLE)
public @NonNull PermissionResult testPermission(@NonNull C sender,
 @NonNull Permission permission)

Checks if the command sender has the required permission and returns the result.

Parameters:

sender - the command sender

permission - the permission

Returns:

a PermissionResult representing whether the sender has the permission

captionRegistry

@API(status=STABLE)
public final @NonNull CaptionRegistry<C> captionRegistry()

Returns the caption registry.

Returns:

the caption registry

See Also:

• captionRegistry(CaptionRegistry)

captionRegistry

@API(status=STABLE)
public final void captionRegistry(@NonNull CaptionRegistry<C> captionRegistry)

Replaces the caption registry.

Some platforms may inject their own captions into the default caption 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.

See Also:

• captionRegistry()

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

deleteRootCommand

@API(status=EXPERIMENTAL)
public void deleteRootCommand(@NonNull String rootCommand)
                       throws CloudCapability.CloudCapabilityMissingException

Deletes the given rootCommand.

This will delete all chains that originate at the root command.

Parameters:

rootCommand - The root command to delete

Throws:

CloudCapability.CloudCapabilityMissingException - If CloudCapability.StandardCapabilities.ROOT_COMMAND_DELETION is missing

rootCommands

@API(status=STABLE)
public @NonNull Collection<@NonNull String> rootCommands()

Returns all root command names.

Returns:

Root command names.

decorateBuilder

public final @NonNull Command.Builder<C> decorateBuilder(@NonNull Command.Builder<C> builder)

Invokes Command.Builder.manager(CommandManager) with this instance and returns the updated builder.

Specified by:

decorateBuilder in interface CommandBuilderSource<C>

Parameters:

builder - builder to decorate

Returns:

the decorated builder

componentBuilder

@API(status=STABLE)
public <T> @NonNull CommandComponent.Builder<C,T> componentBuilder(@NonNull Class<T> type,
 @NonNull String name)

Create a new command component builder.

This will also invoke CommandComponent.Builder.commandManager(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:

Component builder

flagBuilder

public @NonNull CommandFlag.Builder<C,Void> flagBuilder(@NonNull String name)

Create a new command flag builder

Parameters:

name - Flag name

Returns:

Flag builder

commandTree

@API(status=STABLE)
public @NonNull CommandTree<C> commandTree()

Returns the internal command tree.

Be careful when accessing the command tree. Do not interact with it, unless you absolutely know what you're doing.

Returns:

the command tree

createDefaultCommandMeta

public @NonNull CommandMeta createDefaultCommandMeta()

Constructs a default CommandMeta instance.

Specified by:

createDefaultCommandMeta in interface CommandBuilderSource<C>

Returns:

default command meta

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

@API(status=STABLE)
public State preprocessContext(@NonNull CommandContext<C> context,
 @NonNull CommandInput commandInput)

Preprocess a command context instance

Parameters:

context - Command context

commandInput - 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 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

suggestionProcessor

public @NonNull SuggestionProcessor<C> suggestionProcessor()

Returns the command suggestion processor used in this command manager.

Returns:

the command suggestion processor

See Also:

• suggestionProcessor(SuggestionProcessor)

suggestionProcessor

public void suggestionProcessor(@NonNull SuggestionProcessor<C> suggestionProcessor)

Sets the command suggestion processor.

This will be called every time SuggestionFactory.suggest(CommandContext, String) is called, to process the list of suggestions before it's returned to the caller.

Parameters:

suggestionProcessor - the new command suggestion processor

See Also:

• suggestionProcessor()

parserRegistry

@API(status=STABLE)
public @NonNull ParserRegistry<C> parserRegistry()

Returns the parser registry instance.

The parser registry contains default mappings to argument parsers and allows for the registration of custom mappings. The parser registry also contains mappings between annotations and ParserParameter, which allows for the customization of parser settings by using annotations.

When creating a new parser type, it is highly 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:

the parser registry instance

parameterInjectorRegistry

public final @NonNull ParameterInjectorRegistry<C> parameterInjectorRegistry()

Get the parameter injector registry instance

Returns:

Parameter injector registry

exceptionController

@API(status=STABLE)
public final @NonNull ExceptionController<C> exceptionController()

Returns the exception controller.

The exception controller is responsible for exception handler registration.

Returns:

the exception controller

commands

@API(status=STABLE)
public final @NonNull Collection<@NonNull Command<C>> commands()

Returns an unmodifiable view of all registered commands.

Returns:

unmodifiable view of all registered commands

createHelpHandler

@API(status=STABLE)
public final @NonNull HelpHandler<C> createHelpHandler()

Creates a new command help handler instance.

The command helper handler 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:

a new command helper handler instance

createHelpHandler

@API(status=STABLE)
public final @NonNull HelpHandler<C> createHelpHandler(@NonNull CommandPredicate<C> filter)

Creates a new command help handler instance.

The command helper handler can be used to assist in the production of commad help menus, etc.

A filter can be specified to filter what commands registered in this command manager are visible in the help menu.

Parameters:

filter - predicate that filters what commands are displayed in the help menu.

Returns:

a new command helper handler instance

helpHandlerFactory

@API(status=STABLE)
public final @NonNull HelpHandlerFactory<C> helpHandlerFactory()

Returns the help handler factory.

Returns:

the help handler factory

helpHandlerFactory

@API(status=STABLE)
public final void helpHandlerFactory(@NonNull HelpHandlerFactory<C> helpHandlerFactory)

Sets the new help handler factory.

The help handler factory is used to create HelpHandler instances.

Parameters:

helpHandlerFactory - the new factory instance

settings

@API(status=STABLE)
public @NonNull Configurable<ManagerSetting> settings()

Returns a Configurable instance that can be used to modify the settings for this command manager instance.

Returns:

settings instance

state

public final @NonNull RegistrationState state()

Description copied from interface: Stateful

Returns the current state.

Specified by:

state in interface Stateful<C>

Returns:

the current state

transitionIfPossible

public final boolean transitionIfPossible(@NonNull RegistrationState in,
 @NonNull RegistrationState out)

Description copied from interface: Stateful

Transitions from the in state to the out state, unless the current Stateful.state() is identical to the out state.

Specified by:

transitionIfPossible in interface Stateful<C>

Parameters:

in - the starting state

out - the ending state

Returns:

true if the state transition was successful, or the current state is identical to the out state

lockRegistration

@API(status=STABLE)
protected final void lockRegistration()

Transition the command manager from either RegistrationState.BEFORE_REGISTRATION or RegistrationState.REGISTERING to RegistrationState.AFTER_REGISTRATION.

Throws:

IllegalStateException - if the manager is not in the expected state

isCommandRegistrationAllowed

@API(status=STABLE)
public boolean isCommandRegistrationAllowed()

Check if command registration is allowed.

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

Returns:

true if the registration is allowed, else false

registerDefaultExceptionHandlers

protected void registerDefaultExceptionHandlers(@NonNull Consumer<Triplet<CommandContext<C>,Caption,List<@NonNull CaptionVariable>>> messageSender,
 @NonNull Consumer<Pair<String,Throwable>> logger)

Registers the default exception handlers.

Parameters:

messageSender - consumer that gets invoked when a message should be sent to the command sender

logger - consumer that gets invoked when a message should be logged