zhdev/oblak
1
0
Fork 0
Code Issues Pull requests Activity

📚 Improve the Bukkit and PaperCommandManager documentation

Browse source
This commit is contained in:
Alexander Söderberg 2020-10-17 18:58:31 +02:00 • committed by Alexander Söderberg
parent de0666aa73
commit d6cdeca1c3
2 changed files with 55 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

26
cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/BukkitCommandManager.java
View file

@ -85,8 +85,24 @@ public class BukkitCommandManager<C> extends CommandManager<C> {
/** /**
* Construct a new Bukkit command manager * Construct a new Bukkit command manager
* *
* @param owningPlugin Plugin that is constructing the manager * @param owningPlugin Plugin that is constructing the manager. This will be used when registering the
* @param commandExecutionCoordinator Coordinator provider * commands to the Bukkit command map.
* @param 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 example, an entirely asynchronous coordinator is not suitable
* when the parsers used in your commands 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
* {@link CommandExecutionCoordinator#simpleCoordinator()} and
* {@link cloud.commandframework.execution.AsynchronousCommandExecutionCoordinator}.
* <p>
* A word of caution: When using the asynchronous command executor in Bukkit, it is very
* likely that you will have to perform manual synchronization when executing the commands
* in many cases, as Bukkit makes no guarantees of thread safety in common classes. To
* make this easier, {@link #taskRecipe()} is provided. Furthermore, it may be unwise to
* use asynchronous command parsing, especially when dealing with things such as players
* and entities. To make this more safe, the asynchronous command execution allows you
* to state that you want synchronous command parsing.
* @param commandSenderMapper Function that maps {@link CommandSender} to the command sender type * @param commandSenderMapper Function that maps {@link CommandSender} to the command sender type
* @param backwardsCommandSenderMapper Function that maps the command sender type to {@link CommandSender} * @param backwardsCommandSenderMapper Function that maps the command sender type to {@link CommandSender}
* @throws Exception If the construction of the manager fails * @throws Exception If the construction of the manager fails
@ -219,6 +235,12 @@ public class BukkitCommandManager<C> extends CommandManager<C> {
this.splitAliases = value; this.splitAliases = value;
} }
/**
* Check whether or not Brigadier can be used on the server instance
*
* @throws BrigadierFailureException An exception is thrown if Brigadier isn't available. The exception
* will contain the reason for this.
*/
protected final void checkBrigadierCompatibility() throws BrigadierFailureException { protected final void checkBrigadierCompatibility() throws BrigadierFailureException {
if (!this.queryCapability(CloudBukkitCapabilities.BRIGADIER)) { if (!this.queryCapability(CloudBukkitCapabilities.BRIGADIER)) {
throw new BrigadierFailureException( throw new BrigadierFailureException(

34
cloud-minecraft/cloud-paper/src/main/java/cloud/commandframework/paper/PaperCommandManager.java
View file

@ -44,8 +44,32 @@ public class PaperCommandManager<C> extends BukkitCommandManager<C> {
/** /**
* Construct a new Paper command manager * Construct a new Paper command manager
* *
* @param owningPlugin Plugin that is constructing the manager * @param owningPlugin Plugin that is constructing the manager. This will be used when registering the
* @param commandExecutionCoordinator Coordinator provider * commands to the Bukkit command map.
* @param 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 example, an entirely asynchronous coordinator is not suitable
* when the parsers used in your commands 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
* {@link CommandExecutionCoordinator#simpleCoordinator()} and
* {@link cloud.commandframework.execution.AsynchronousCommandExecutionCoordinator}.
* <p>
* A word of caution: When using the asynchronous command executor in Bukkit, it is very
* likely that you will have to perform manual synchronization when executing the commands
* in many cases, as Bukkit makes no guarantees of thread safety in common classes. To
* make this easier, {@link #taskRecipe()} is provided. Furthermore, it may be unwise to
* use asynchronous command parsing, especially when dealing with things such as players
* and entities. To make this more safe, the asynchronous command execution allows you
* to state that you want synchronous command parsing.
* <p>
* The execution coordinator will not have an impact on command suggestions. More
* specifically, using an asynchronous command executor does not mean that command
* suggestions will be provided asynchronously. Instead, use
* {@link #registerAsynchronousCompletions()} to register asynchronous completions. This
* will only work on Paper servers. Be aware that cloud does not synchronize the command
* suggestions for you, and this should only be used if your command suggestion providers
* are thread safe.
* @param commandSenderMapper Function that maps {@link CommandSender} to the command sender type * @param commandSenderMapper Function that maps {@link CommandSender} to the command sender type
* @param backwardsCommandSenderMapper Function that maps the command sender type to {@link CommandSender} * @param backwardsCommandSenderMapper Function that maps the command sender type to {@link CommandSender}
* @throws Exception If the construction of the manager fails * @throws Exception If the construction of the manager fails
@ -89,12 +113,16 @@ public class PaperCommandManager<C> extends BukkitCommandManager<C> {
* is up to the caller to guarantee that such is the case * is up to the caller to guarantee that such is the case
* *
* @throws IllegalStateException when the server does not support asynchronous completions. * @throws IllegalStateException when the server does not support asynchronous completions.
* @see #queryCapability(CloudBukkitCapabilities) Check if the capability is present
*/ */
public void registerAsynchronousCompletions() throws IllegalStateException { public void registerAsynchronousCompletions() throws IllegalStateException {
if (!this.queryCapability(CloudBukkitCapabilities.ASYNCHRONOUS_COMPLETION)) { if (!this.queryCapability(CloudBukkitCapabilities.ASYNCHRONOUS_COMPLETION)) {
throw new IllegalStateException("Failed to register asynchronous command completion listener."); throw new IllegalStateException("Failed to register asynchronous command completion listener.");
} }
Bukkit.getServer().getPluginManager().registerEvents(new AsyncCommandSuggestionsListener<>(this), this.getOwningPlugin()); Bukkit.getServer().getPluginManager().registerEvents(
new AsyncCommandSuggestionsListener<>(this),
this.getOwningPlugin()
);
} }
} }