Merge pull request #41 from PXAV/development

Add changes for release 0.1.1

CHANGELOG/kelp-v0.1.1.md

@@ -0,0 +1,26 @@
+# v0.1.1
+> Release date: 04.02.2021
+
+**Events & commands changes**:
+* Rework dynamic listener system:
+  * Dynamic listeners are now built with generic types, meaning that they can adjust to your event, and you don't have to cast your event anymore when handling it.
+  * Add timed/scheduled expires to dynamic listeners: You can now give a specific time in which the listener will expire. 
+  * Add minimal executions: You can now give a specific amount of minimal executions of the listener, which means that it has to be executed `n` amount of times, before it expires, even though other conditional expiry checks would lead to an expiry. Scheduled expires have a higher priority and will unregister the listener even though the event has not been handled `n` times.
+  * Add event criteria: You can now add unlimited criteria to an event. Only if all criteria are fulfilled, the event will be handled. Those criteria can be used to check whether the action of a specific interaction is valid, etc.
+  * Add default event criteria in `EventCriteria`. Common criteria such as checking if the player has a specific permissions are included here to avoid typing the predicates yourself every time.
+* Custom Kelp events now use the new event supertype `KelpPlayerEvent` added in the last release:
+  * `KelpInventoryCloseEvent`
+  * `KelpInventoryOpenEvent`
+  * `KelpInventoryUpdateEvent`
+  * `KelpInventoryCloseEvent`
+  * `KelpPlayerLoginEvent`
+  * `KelpPlayerUpdateSettingsEvent`
+  * `KelpInventoryCloseEvent`
+  * `KelpInventoryCloseEvent`
+  * `KelpInventoryCloseEvent`
+* Add 'smart inject' to listeners using the `@Subscribes` annotation. If your event is a `PlayerEvent` or `KelpPlayerEvent` and has a single parameter with the player of this event, the player parameter will be injected automatically.  
+* Documentation improvements for text animation classes
+* Add `delegatePlayerToConsole(bool)` method to `KelpCommand`, which is a command property that can be assigned in `onCommandRegister`. It executes the `onCommand` method of the console sender if the executor type is set to `PLAYER_AND_CONSOLE` and a player executes the command. If your command has the same behaviour for players and consoles, this is useful to avoid duplicated command handlers.
+* Add `inheritFromMainCommand(bool)` property to `KelpCommand`, which can be used in sub commands to inherit basic properties such as permission and messages from the main command (`@CreateCommand`) to the sub command (`@CreateSubCommand`). So you don't have to assign the properties manually for every command anymore.
+* Fix bug in sidebar cluster system that caused a `NullPointerException` when a player quit during a server reload.
+* Schedulers can now be produced via static factories

core/pom.xml

@@ -5,7 +5,7 @@
   <parent>
     <groupId>com.github.pxav.kelp</groupId>
     <artifactId>parent</artifactId>
-    <version>0.1.0</version>
+    <version>0.1.1</version>
   </parent>
 
   <modelVersion>4.0.0</modelVersion>

core/src/main/java/de/pxav/kelp/core/KelpPlugin.java

@@ -35,7 +35,7 @@
  *
  * @author pxav
  */
-@Plugin(name = "Kelp", version = "0.1.0")
+@Plugin(name = "Kelp", version = "0.1.1")
 @Author("pxav")
 @Description("A cross version spigot framework.")
 @Singleton

core/src/main/java/de/pxav/kelp/core/animation/StaticTextAnimation.java

@@ -4,7 +4,11 @@
 import java.util.List;
 
 /**
- * A class description goes here.
+ * This text animation is used to display static texts where a
+ * {@link TextAnimation} object is required by design. If you have
+ * an animated sidebar for example and you want to display a static
+ * text for example for debugging purposes, you can use this animation
+ * type.
  *
  * @author pxav
  */
@@ -22,6 +26,12 @@ public static StaticTextAnimation create() {
     return new StaticTextAnimation();
   }
 
+  /**
+   * Sets the text to be displayed in the static animation.
+   *
+   * @param text The text to be displayed.
+   * @return Instance of the current animation object.
+   */
   public StaticTextAnimation text(String text) {
     this.text = text;
     return this;

core/src/main/java/de/pxav/kelp/core/animation/TextAnimation.java

@@ -3,12 +3,24 @@
 import java.util.List;
 
 /**
- * A class description goes here.
+ * This interface represents the basis of every text animation
+ * used within the Kelp framework. A text animation basically takes
+ * a string and optionally some additional data and converts it to
+ * an animation. The animation consists of a collection of multiple
+ * strings. If you play those strings with a regular interval
+ * it will look like an animation.
  *
  * @author pxav
  */
 public interface TextAnimation {
 
+  /**
+   * This method calculates the given data from the animation class
+   * to a final animation. The list contains all animation states that - if played
+   * one by one - make up the final animation.
+   *
+   * @return The final collection of all states of the animation in a chronological order.
+   */
   List<String> states();
 
 }

core/src/main/java/de/pxav/kelp/core/animation/TextAnimationFactory.java

@@ -5,7 +5,13 @@
 import de.pxav.kelp.core.common.StringUtils;
 
 /**
- * A class description goes here.
+ * This factory class is used to produce instances of
+ * new {@link TextAnimation}s.
+ *
+ * This is useful if you fully follow an object-oriented and dependency-
+ * injecting design approach. For most cases, it would probably also clean
+ * to use static factory methods of the different text animation types such
+ * as {@link BuildingTextAnimation}.
  *
  * @author pxav
  */

core/src/main/java/de/pxav/kelp/core/command/KelpCommand.java

@@ -54,6 +54,16 @@ public class KelpCommand {
   // resets the argument count for sub commands to 0 again.
   private boolean argumentsStartFromZero;
 
+  // if 'true' the onCommand() method for console will be
+  // used although a player executes the command (if executor
+  // type is set to PLAYER_AND_CONSOLE)
+  private boolean delegatePlayerToConsole;
+
+  // whether basic properties such as error messages should be taken
+  // from the parent command, so that they don't have to be defined
+  // manually each time.
+  private boolean inheritFromMainCommand;
+
   /**
    * This method is executed by the command registry, when the command
    * is executed by a player and {@code PLAYER_ONLY} is set as executor type.
@@ -92,13 +102,54 @@ public void onCommand(KelpConsoleSender consoleSender, String[] args) {}
   public void onCommandRegister() {}
 
   /**
+   * Gets a collection of all sub commands associated with this command.
+   *
    * @return  A map of all sub commands, where the key is the command class
    *          of the command and the value is the sub command annotation.
    */
   public Map<KelpCommand, CreateSubCommand> getSubCommands() {
     return subCommands;
   }
 
+  /**
+   * Delegates the command executor from the player to a console. Normally, if executor type
+   * is set to {@link ExecutorType#PLAYER_AND_CONSOLE} and a player executes the command,
+   * the {@link #onCommand(KelpPlayer, String[])} method is called. But if you want the same
+   * command structure to be executed for both types of users, you might not want to copy the
+   * methods for player and console. That's why you can use this method to create a kind of
+   * redirection. If this is enabled, the player will be converted to a console sender and
+   * the {@link #onCommand(KelpConsoleSender, String[])} method will be executed so that
+   * you only have to maintain one command method.
+   *
+   * @param delegate {@code true} if the described redirection/delegation
+   *                             of commands should be done.
+   */
+  public void delegatePlayerToConsole(boolean delegate) {
+    this.delegatePlayerToConsole = delegate;
+  }
+
+  /**
+   * Makes the current command inherit certain properties of the parent command.
+   * This includes:
+   * <ul>
+   *   <li>Command description</li>
+   *   <li>Command permission</li>
+   *   <li>No permission message</li>
+   *   <li>No player message</li>
+   *   <li>No console message</li>
+   * </ul>
+   *
+   * You can of course inherit properties from the parent command and overwrite
+   * them manually later, while keeping the values for the other strings. So if
+   * you only want to change the description you can inherit all properties and overwrite
+   * the description yourself.
+   *
+   * @param inherit {@code true} if you want the listed properties to be inherited from the main command.
+   */
+  public void inheritFromMainCommand(boolean inherit) {
+    this.inheritFromMainCommand = inherit;
+  }
+
   /**
    * Sets the description of the command, which can later be used
    * to display in help commands, etc.
@@ -350,13 +401,19 @@ public KelpCommand argumentsStartFromZero(boolean argumentsStartFromZero) {
   }
 
   /**
+   * Gets the command's description used in the Kelp command
+   * overview for example.
+   *
    * @return The description of the command.
    */
   public String getDescription() {
     return description;
   }
 
   /**
+   * Gets the custom message that is sent to a player when they do not
+   * have sufficient permissions to execute the command.
+   *
    * @return  The message which is sent to players, if they do not have enough
    *          permissions.
    */
@@ -365,6 +422,11 @@ public String getNoPermissionMessage() {
   }
 
   /**
+   * Gets the custom message set by this command which is sent when
+   * a console tries to execute the command, although it is made
+   * for players only. If this is null, the default message of
+   * Kelp will be used.
+   *
    * @return The message which is sent to the console, when it
    *         executes a command, which is meant for players only.
    */
@@ -373,37 +435,67 @@ public String getNoPlayerMessage() {
   }
 
   /**
+   * Gets the custom message set by this command which is sent when
+   * a player executes the command although it is meant for consoles
+   * only. If this is null, the default message will be used.
+   *
    * @return The message which is sent to players when they execute a console command.
    */
   public String getNoConsoleMessage() {
     return noConsoleMessage;
   }
 
   /**
+   * Gets the permission that is needed by a player to execute the command.
+   * A console does not need this permission.
+   *
    * @return Returns the permission string, which is needed for this command.
    */
   public String getPermission() {
     return permission;
   }
 
   /**
+   * Checks whether custom parameters other than sub commands are
+   * accepted by the command. If this is false, you won't be able to
+   * handle such custom user inputs.
+   *
    * @return {@code true} if custom parameters are allowed in this command.
    */
   public boolean customParametersAllowed() {
     return this.allowCustomParameters;
   }
 
   /**
+   * Checks whether the arguments should be reset when queried in a sub command.
+   * For more information see {@link #argumentsStartFromZero(boolean)}
+   *
    * @return {@code true} if the argument count should be reset to 0.
    */
   public boolean shouldArgumentsStartFromZero() {
     return this.argumentsStartFromZero;
   }
 
   /**
+   * Gets a collection of all aliases defined for this command.
+   *
    * @return A collection of all aliases the command has.
    */
   public Collection<String> getAliases() {
     return aliases;
   }
+
+  /**
+   * Checks if the command
+   *
+   * @return
+   */
+  public boolean shouldDelegateToConsole() {
+    return this.delegatePlayerToConsole;
+  }
+
+  public boolean shouldInheritFromMainCommand() {
+    return this.inheritFromMainCommand;
+  }
+
 }

core/src/main/java/de/pxav/kelp/core/command/KelpCommandRepository.java

@@ -88,6 +88,28 @@ public void loadCommands(String... packages) {
 
       commandClass.onCommandRegister();
 
+      // inherit properties from main command to sub commands if needed.
+      commandClass.getSubCommands().forEach((subCommand, subCommandAnnotation) -> {
+        if (!subCommand.shouldInheritFromMainCommand()) {
+          return;
+        }
+        if (subCommand.getNoPermissionMessage() == null) {
+          subCommand.noPermissionMessage(commandClass.getNoPermissionMessage());
+        }
+        if (subCommand.getNoConsoleMessage() == null) {
+          subCommand.noConsoleMessage(commandClass.getNoConsoleMessage());
+        }
+        if (subCommand.getNoPlayerMessage() == null) {
+          subCommand.noPlayerMessage(commandClass.getNoPlayerMessage());
+        }
+        if (subCommand.getPermission() == null) {
+          subCommand.permission(commandClass.getPermission());
+        }
+        if (subCommand.getDescription() == null) {
+          subCommand.description(commandClass.getDescription());
+        }
+      });
+
       // add command to bukkit registry
       registryVersionTemplate.registerCommand(commandClass, commandAnnotation);
       logger.log(LogLevel.DEBUG, "[COMMAND] Registered main command "

core/src/main/java/de/pxav/kelp/core/command/KelpConsoleSender.java

@@ -1,6 +1,8 @@
 package de.pxav.kelp.core.command;
 
+import de.pxav.kelp.core.KelpPlugin;
 import de.pxav.kelp.core.command.version.KelpConsoleSenderVersionTemplate;
+import de.pxav.kelp.core.player.KelpPlayer;
 import org.bukkit.command.CommandSender;
 
 /**
@@ -31,6 +33,13 @@ public class KelpConsoleSender {
     this.versionTemplate = versionTemplate;
   }
 
+  public static KelpConsoleSender create(CommandSender bukkitSender) {
+    return new KelpConsoleSender(
+      bukkitSender,
+      KelpPlugin.getInjector().getInstance(KelpConsoleSenderVersionTemplate.class)
+    );
+  }
+
   /**
    * Sends a message to the console sender.
    * @param message The message you want to send (may contain color codes using §)