Package org.incendo.cloud.paper

Class LegacyPaperCommandManager<C>

java.lang.Object

org.incendo.cloud.CommandManager<C>

org.incendo.cloud.bukkit.BukkitCommandManager<C>

org.incendo.cloud.paper.LegacyPaperCommandManager<C>

Type Parameters:

C - command sender type

All Implemented Interfaces:

BrigadierManagerHolder<C,Object>, PluginHolder, CommandBuilderSource<C>, SenderMapperHolder<CommandSender,C>, Stateful<RegistrationState>

public class LegacyPaperCommandManager<C>
extends BukkitCommandManager<C>

CommandManager implementation for Bukkit-based platforms (i.e. Spigot, Paper), with specific support for Paper features (gated behind CloudBukkitCapabilities for "backwards-compatibility").

This command manager uses legacy Bukkit command APIs. It's recommended to use the PaperCommandManager instead when supporting Paper 1.20.6+ exclusively.

See Also:

• LegacyPaperCommandManager(Plugin, ExecutionCoordinator, SenderMapper)
• createNative(Plugin, ExecutionCoordinator)

Nested Class Summary

Nested classes/interfaces inherited from class org.incendo.cloud.bukkit.BukkitCommandManager

BukkitCommandManager.BrigadierInitializationException, BukkitCommandManager.InitializationException

Nested classes/interfaces inherited from interface org.incendo.cloud.brigadier.BrigadierManagerHolder

BrigadierManagerHolder.BrigadierManagerNotPresent

Constructor Summary

Constructors

Constructor	Description
LegacyPaperCommandManager(@NonNull Plugin owningPlugin, @NonNull ExecutionCoordinator<C> commandExecutionCoordinator, @NonNull SenderMapper<CommandSender,C> senderMapper)	Create a new Paper command manager.

Method Summary

Modifier and Type	Method	Description
@NonNull CloudBrigadierManager<C,?>	brigadierManager()
static @NonNull LegacyPaperCommandManager<@NonNull CommandSender>	createNative(@NonNull Plugin owningPlugin, @NonNull ExecutionCoordinator<CommandSender> commandExecutionCoordinator)	Create a command manager using Bukkit's CommandSender as the sender type.
boolean	hasBrigadierManager()
void	registerAsynchronousCompletions()	Registers asynchronous completions using the Paper API.
void	registerBrigadier()	Attempts to enable Brigadier command registration through the Paper API, falling back to BukkitCommandManager.registerBrigadier() if that fails.
void	registerLegacyPaperBrigadier()	Deprecated. This method will continue to work while the Paper commands API is still incubating, but will eventually no longer function when the old API is removed.

Methods inherited from class org.incendo.cloud.bukkit.BukkitCommandManager

checkBrigadierCompatibility, hasPermission, owningPlugin, senderMapper, splitAliases, splitAliases

Methods inherited from class org.incendo.cloud.CommandManager

appendSuggestionMapper, capabilities, captionFormatter, captionFormatter, captionRegistry, captionRegistry, command, command, command, commandExecutor, commandRegistrationHandler, commandRegistrationHandler, commands, commandSyntaxFormatter, commandSyntaxFormatter, commandTree, componentBuilder, createDefaultCommandMeta, createHelpHandler, createHelpHandler, decorateBuilder, deleteRootCommand, exceptionController, flagBuilder, hasCapability, helpHandlerFactory, helpHandlerFactory, isCommandRegistrationAllowed, lockRegistration, parameterInjectorRegistry, parserRegistry, postprocessContext, preprocessContext, registerCapability, registerCommandPostProcessor, registerCommandPreProcessor, registerDefaultExceptionHandlers, rootCommands, settings, state, suggestionFactory, suggestionMapper, suggestionMapper, suggestionProcessor, suggestionProcessor, testPermission, transitionIfPossible

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

LegacyPaperCommandManager

@API(status=STABLE,
     since="2.0.0")
public LegacyPaperCommandManager(@NonNull Plugin owningPlugin,
 @NonNull ExecutionCoordinator<C> commandExecutionCoordinator,
 @NonNull SenderMapper<CommandSender,C> senderMapper)
                          throws BukkitCommandManager.InitializationException

Create a new Paper command manager.

Parameters:

owningPlugin - Plugin constructing the manager. Used when registering commands to the command map, registering event listeners, etc.

commandExecutionCoordinator - Execution coordinator instance. Due to Bukkit blocking the main thread for suggestion requests, it's potentially unsafe to use anything other than ExecutionCoordinator.nonSchedulingExecutor() for ExecutionCoordinator.Builder.suggestionsExecutor(Executor). Once the coordinator, a suggestion provider, parser, or similar routes suggestion logic off of the calling (main) thread, it won't be possible to schedule further logic back to the main thread without a deadlock. When Brigadier support is active, this issue is avoided, as it allows for non-blocking suggestions. Paper's asynchronous completion API can also be used to avoid this issue: registerAsynchronousCompletions()

senderMapper - Mapper between Bukkit's CommandSender and the command sender type C.

Throws:

BukkitCommandManager.InitializationException - if construction of the manager fails

See Also:

• registerBrigadier()

Method Details

createNative

@API(status=STABLE,
     since="2.0.0")
public static @NonNull LegacyPaperCommandManager<@NonNull CommandSender> createNative(@NonNull Plugin owningPlugin,
 @NonNull ExecutionCoordinator<CommandSender> commandExecutionCoordinator)
                                                                               throws BukkitCommandManager.InitializationException

Create a command manager using Bukkit's CommandSender as the sender type.

Parameters:

owningPlugin - plugin owning the command manager

commandExecutionCoordinator - execution coordinator instance

Returns:

a new command manager

Throws:

BukkitCommandManager.InitializationException - if the construction of the manager fails

Since:

1.5.0

See Also:

• for a more thorough explanation

registerBrigadier

public void registerBrigadier()
                       throws BukkitCommandManager.BrigadierInitializationException

Attempts to enable Brigadier command registration through the Paper API, falling back to BukkitCommandManager.registerBrigadier() if that fails.

Callers should check for CloudBukkitCapabilities.NATIVE_BRIGADIER first to avoid exceptions.

A check for CloudBukkitCapabilities.NATIVE_BRIGADIER || CloudBukkitCapabilities.COMMODORE_BRIGADIER may also be appropriate for some use cases (because of the fallback behavior), but not most, as Commodore does not offer any functionality on modern versions (see the documentation for CloudBukkitCapabilities.COMMODORE_BRIGADIER).

Overrides:

registerBrigadier in class BukkitCommandManager<C>

Throws:

BukkitCommandManager.BrigadierInitializationException - when the prerequisite capabilities are not present or some other issue occurs during registration of Brigadier support

See Also:

• CommandManager.hasCapability(CloudCapability)

registerLegacyPaperBrigadier

@Deprecated
public void registerLegacyPaperBrigadier()
                                  throws BukkitCommandManager.BrigadierInitializationException

Deprecated.

This method will continue to work while the Paper commands API is still incubating, but will eventually no longer function when the old API is removed.

Variant of registerBrigadier() that only uses the old Paper-MojangAPI, even when the modern Paper commands API is present. This may be useful for debugging issues with the new Paper command system.

Throws:

BukkitCommandManager.BrigadierInitializationException - when the prerequisite capabilities are not present or some other issue occurs during registration of Brigadier support

hasBrigadierManager

@API(status=STABLE,
     since="2.0.0")
public boolean hasBrigadierManager()

Specified by:

hasBrigadierManager in interface BrigadierManagerHolder<C,Object>

Overrides:

hasBrigadierManager in class BukkitCommandManager<C>

Returns:

Since:

2.0.0

brigadierManager

@API(status=STABLE,
     since="2.0.0")
public @NonNull CloudBrigadierManager<C,?> brigadierManager()

Specified by:

brigadierManager in interface BrigadierManagerHolder<C,Object>

Overrides:

brigadierManager in class BukkitCommandManager<C>

Returns:

Throws:

BrigadierManagerHolder.BrigadierManagerNotPresent - when hasBrigadierManager() is false

Since:

1.2.0

registerAsynchronousCompletions

public void registerAsynchronousCompletions()
                                     throws IllegalStateException

Registers asynchronous completions using the Paper API. This means the calling thread for suggestion queries will be a thread other than the main server thread (or, the sender's thread context on Folia).

Requires the CloudBukkitCapabilities.ASYNCHRONOUS_COMPLETION capability to be present.

It's not recommended to use this in combination with registerBrigadier(), as Brigadier allows for non-blocking suggestions and the async completion API reduces the fidelity of suggestions compared to using Brigadier directly (see LegacyPaperCommandManager(Plugin, ExecutionCoordinator, SenderMapper)).

Throws:

IllegalStateException - when the server does not support asynchronous completions

See Also:

• CommandManager.hasCapability(CloudCapability)