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

✨ Give CommandManager a registration state (#148)

Browse source 
* Make CommandManager track its availability for registration

This prevents situations where changes to the manager
would result in undefined state in other places.

* Add unsafe registration capability

* Very minor formatting + `@since` tags

* Add changes to changelog

Co-authored-by: Alexander Söderberg <sauilitired@gmail.com>
This commit is contained in:
zml 2020-11-29 06:29:41 -08:00 • committed by Alexander Söderberg
parent 65684d0036
commit 013d2d61f4
11 changed files with 273 additions and 155 deletions
Download patch file Download diff file Expand all files Collapse all files

114
cloud-core/src/main/java/cloud/commandframework/CommandManager.java
View file

@ -69,6 +69,7 @@ import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.atomic.AtomicReference;
import java.util.function.BiConsumer;
import java.util.function.Function;
@ -95,6 +96,7 @@ public abstract class CommandManager<C> {
private CommandSuggestionProcessor<C> commandSuggestionProcessor = new FilteringCommandSuggestionProcessor<>();
private CommandRegistrationHandler commandRegistrationHandler;
private CaptionRegistry<C> captionRegistry;
private final AtomicReference<RegistrationState> state = new AtomicReference<>(RegistrationState.BEFORE_REGISTRATION);
/**
* Create a new command manager instance
@ -207,6 +209,11 @@ public abstract class CommandManager<C> {
* return {@code this}.
*/
public @NonNull CommandManager<C> command(final @NonNull Command<C> command) {
if (!(this.transitionIfPossible(RegistrationState.BEFORE_REGISTRATION, RegistrationState.REGISTERING)
|| this.isCommandRegistrationAllowed())) {
throw new IllegalStateException("Unable to register commands because the manager is no longer in a registration "
+ "state. Your platform may allow unsafe registrations by enabling the appropriate manager setting.");
}
this.commandTree.insertCommand(command);
this.commands.add(command);
return this;
@ -250,6 +257,7 @@ public abstract class CommandManager<C> {
}
protected final void setCommandRegistrationHandler(final @NonNull CommandRegistrationHandler commandRegistrationHandler) {
this.requireState(RegistrationState.BEFORE_REGISTRATION);
this.commandRegistrationHandler = commandRegistrationHandler;
}
@ -767,6 +775,71 @@ public abstract class CommandManager<C> {
}
}
/**
* Transition from the {@code in} state to the {@code out} state, if the manager is not already in that state.
*
* @param in The starting state
* @param out The ending state
* @throws IllegalStateException if the manager is in any state but {@code in} or {@code out}
* @since 1.2.0
*/
protected final void transitionOrThrow(final @NonNull RegistrationState in, final @NonNull RegistrationState out) {
if (!this.transitionIfPossible(in, out)) {
throw new IllegalStateException("Command manager was in state " + this.state.get() + ", while we were expecting a state "
+ "of " + in + " or " + out + "!");
}
}
/**
* Transition from the {@code in} state to the {@code out} state, if the manager is not already in that state.
*
* @param in The starting state
* @param out The ending state
* @return {@code true} if the state transition was successful, or the manager was already in the desired state
* @since 1.2.0
*/
protected final boolean transitionIfPossible(final @NonNull RegistrationState in, final @NonNull RegistrationState out) {
return this.state.compareAndSet(in, out) || this.state.get() == out;
}
/**
* Require that the commands manager is in a certain state.
*
* @param expected The required state
* @throws IllegalStateException if the manager is not in the expected state
* @since 1.2.0
*/
protected final void requireState(final @NonNull RegistrationState expected) {
if (this.state.get() != expected) {
throw new IllegalStateException("This operation required the commands manager to be in state " + expected + ", but it "
+ "was in " + this.state.get() + " instead!");
}
}
/**
* Get the active registration state for this manager.
* <p>
* If this state is {@link RegistrationState#AFTER_REGISTRATION}, commands can no longer be registered
*
* @return The current state
* @since 1.2.0
*/
public final @NonNull RegistrationState getRegistrationState() {
return this.state.get();
}
/**
* Check if command registration is allowed.
* <p>
* On platforms where unsafe registration is possible, this can be overridden by enabling the
* {@link ManagerSettings#ALLOW_UNSAFE_REGISTRATION} setting.
*
* @return {@code true} if the registration is allowed, else {@code false}
* @since 1.2.0
*/
public boolean isCommandRegistrationAllowed() {
return this.getSetting(ManagerSettings.ALLOW_UNSAFE_REGISTRATION) || this.state.get() != RegistrationState.AFTER_REGISTRATION;
}
/**
* Configurable command related settings
@ -785,7 +858,46 @@ public abstract class CommandManager<C> {
* Force sending of an empty suggestion (i.e. a singleton list containing an empty string)
* when no suggestions are present
*/
FORCE_SUGGESTION
FORCE_SUGGESTION,
/**
* Allow registering commands even when doing so has the potential to produce inconsistent results.
* <p>
* For example, if a platform serializes the command tree and sends it to clients,
* this will allow modifying the command tree after it has been sent, as long as these modifications are not blocked by
* the underlying platform
*/
ALLOW_UNSAFE_REGISTRATION
}
/**
* The point in the registration lifecycle for this commands manager
*
* @since 1.2.0
*/
public enum RegistrationState {
/**
* The point when no commands have been registered yet.
*
* <p>At this point, all configuration options can be changed.</p>
*/
BEFORE_REGISTRATION,
/**
* When at least one command has been registered, and more commands have been registered.
*
* <p>In this state, some options that affect how commands are registered with the platform are frozen. Some platforms
* will remain in this state for their lifetime.</p>
*/
REGISTERING,
/**
* Once registration has been completed.
*
* <p>At this point, the command manager is effectively immutable. On platforms where command registration happens via
* callback, this state is achieved the first time the manager's callback is executed for registration.</p>
*/
AFTER_REGISTRATION
}
}

53
cloud-core/src/main/java/cloud/commandframework/LockableCommandManager.java
View file

@ -40,12 +40,11 @@ import java.util.function.Function;
*
* @param <C> Command sender type
* @since 1.1.0
* @deprecated Use a normal {@link CommandManager}'s registration state instead
*/
@Deprecated
public abstract class LockableCommandManager<C> extends CommandManager<C> {
private final Object writeLock = new Object();
private volatile boolean writeLocked = false;
/**
* Create a new command manager instance
*
@ -67,57 +66,11 @@ public abstract class LockableCommandManager<C> extends CommandManager<C> {
super(commandExecutionCoordinator, commandRegistrationHandler);
}
/**
* {@inheritDoc}
* <p>
* This should only be called when {@link #isCommandRegistrationAllowed()} is {@code true},
* else {@link IllegalStateException} will be called
*
* @param command Command to register
* @return The command manager instance
*/
@Override
public final @NonNull CommandManager<C> command(final @NonNull Command<C> command) {
synchronized (this.writeLock) {
if (!isCommandRegistrationAllowed()) {
throw new IllegalStateException(
"Command registration is not allowed. The command manager has been locked."
);
}
return super.command(command);
}
}
/**
* {@inheritDoc}
* <p>
* This should only be called when {@link #isCommandRegistrationAllowed()} is {@code true},
* else {@link IllegalStateException} will be called
*
* @param command Command to register. {@link Command.Builder#build()}} will be invoked.
* @return The command manager instance
*/
@Override
public final @NonNull CommandManager<C> command(final Command.@NonNull Builder<C> command) {
return super.command(command);
}
/**
* Lock writing. After this, {@link #isCommandRegistrationAllowed()} will return {@code false}
*/
protected final void lockWrites() {
synchronized (this.writeLock) {
this.writeLocked = true;
}
}
/**
* Check if command registration is allowed
*
* @return {@code true} if the registration is allowed, else {@code false}
*/
public final boolean isCommandRegistrationAllowed() {
return !this.writeLocked;
this.transitionOrThrow(RegistrationState.REGISTERING, RegistrationState.AFTER_REGISTRATION);
}
}

77
cloud-core/src/test/java/cloud/commandframework/CommandRegistrationStateTest.java Normal file
View file

@ -0,0 +1,77 @@
//
// MIT License
//
// Copyright (c) 2020 Alexander Söderberg & Contributors
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
//
package cloud.commandframework;
import cloud.commandframework.internal.CommandRegistrationHandler;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
public class CommandRegistrationStateTest {
@Test
void testInitialState() {
final TestCommandManager manager = new TestCommandManager();
assertEquals(CommandManager.RegistrationState.BEFORE_REGISTRATION, manager.getRegistrationState());
}
@Test
void testRegistrationChangesState() {
final TestCommandManager manager = new TestCommandManager();
manager.command(manager.commandBuilder("test").handler(ctx -> {}));
assertEquals(CommandManager.RegistrationState.REGISTERING, manager.getRegistrationState());
// And a second registration maintains it
manager.command(manager.commandBuilder("test2").handler(ctx -> {}));
assertEquals(CommandManager.RegistrationState.REGISTERING, manager.getRegistrationState());
}
@Test
void testChangingRegistrationHandlerFails() {
final TestCommandManager manager = new TestCommandManager();
manager.command(manager.commandBuilder("test").handler(ctx -> {}));
assertThrows(IllegalStateException.class,
() -> manager.setCommandRegistrationHandler(CommandRegistrationHandler.nullCommandRegistrationHandler()));
}
@Test
void testRegistrationFailsInAfterRegistrationState() {
final TestCommandManager manager = new TestCommandManager();
manager.command(manager.commandBuilder("test").handler(ctx -> {}));
manager.transitionOrThrow(CommandManager.RegistrationState.REGISTERING, CommandManager.RegistrationState.AFTER_REGISTRATION);
assertThrows(IllegalStateException.class, () -> manager.command(manager.commandBuilder("test2").handler(ctx -> {})));
}
@Test
void testAllowUnsafeRegistration() {
final TestCommandManager manager = new TestCommandManager();
manager.setSetting(CommandManager.ManagerSettings.ALLOW_UNSAFE_REGISTRATION, true);
manager.command(manager.commandBuilder("test").handler(ctx -> {}));
manager.transitionOrThrow(CommandManager.RegistrationState.REGISTERING, CommandManager.RegistrationState.AFTER_REGISTRATION);
manager.command(manager.commandBuilder("unsafe").handler(ctx -> {}));
}
}

45
cloud-core/src/test/java/cloud/commandframework/LockableCommandManagerTest.java
View file

@ -1,45 +0,0 @@
//
// MIT License
//
// Copyright (c) 2020 Alexander Söderberg & Contributors
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
//
package cloud.commandframework;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
public class LockableCommandManagerTest {
@Test
void testLockableCommandManager() {
final LockableCommandManager<TestCommandSender> manager = new TestLockableCommandManager();
/* Add a command before locking */
manager.command(manager.commandBuilder("test1"));
/* Lock */
manager.lockWrites();
/* Add a command after locking */
Assertions.assertThrows(
IllegalStateException.class,
() -> manager.command(manager.commandBuilder("test2"))
);
}
}

54
cloud-core/src/test/java/cloud/commandframework/TestLockableCommandManager.java
View file

@ -1,54 +0,0 @@
//
// MIT License
//
// Copyright (c) 2020 Alexander Söderberg & Contributors
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
//
package cloud.commandframework;
import cloud.commandframework.execution.CommandExecutionCoordinator;
import cloud.commandframework.internal.CommandRegistrationHandler;
import cloud.commandframework.meta.SimpleCommandMeta;
public class TestLockableCommandManager extends LockableCommandManager<TestCommandSender> {
/**
* Construct a new test command manager
*/
public TestLockableCommandManager() {
super(
CommandExecutionCoordinator.simpleCoordinator(),
CommandRegistrationHandler.nullCommandRegistrationHandler()
);
}
@Override
public final SimpleCommandMeta createDefaultCommandMeta() {
return SimpleCommandMeta.empty();
}
@Override
public final boolean hasPermission(final TestCommandSender sender, final String permission) {
System.out.printf("Testing permission: %s\n", permission);
return !permission.equalsIgnoreCase("no");
}
}