feat: add ExecutorWrapper annotation and inherited annotations support (#38)

Co-authored-by: Strokkur24 <strokkur.24@gmail.com>

Author: AlexProgrammerDE

annotations-common/src/main/java/net/strokkur/commands/CustomExecutorWrapper.java

@@ -0,0 +1,86 @@
+/*
+ * StrokkCommands - A super simple annotation based zero-shade Paper command API library.
+ * Copyright (C) 2025 Strokkur24
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <https://www.gnu.org/licenses/>.
+ */
+package net.strokkur.commands;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.lang.reflect.Method;
+
+/// Declares that an annotation should be treated as a provider for executor wrappers.
+///
+/// Apply this annotation to your own custom annotation:
+/// ```java
+/// @CustomExecutorWrapper
+/// @interface TimingWrapper {}
+/// ```
+///
+/// ## Annotating the wrapper method
+/// The wrapper method must be annotated with your custom wrapper annotation.
+/// Generally, the wrapper method should be static, except if only used inside a single
+/// command class, in which it may be non-static.
+///
+/// The wrapper method should have a `Command<S>` parameter, returning a `Command<S>`.
+///
+/// Additionally, the wrapper method may define an optional, second parameter to retrieve the
+/// [Method] instance the wrapper was called for.
+///
+/// - `Command<S> wrapper(Command<S>)`
+/// - `Command<S> wrapper(Command<S>, Method)`
+///
+/// ## Example usage
+/// ```java
+/// @TimingWrapper
+/// static Command<CommandSourceStack> time(Command<CommandSourceStack> executor) {
+///   return (ctx) -> {
+///     final long start = System.nanoTime();
+///     try {
+///       return executor.run(ctx);
+///     } finally {
+///       LOGGER.info("Took {} nanoseconds!", System.nanoTime() - start);
+///     }
+///   };
+/// }
+/// ```
+///
+/// ## Using the custom executor wrapper annotation
+/// Apply your wrapper annotation to classes or methods:
+/// ```java
+/// @Command("mycommand")
+/// @TimingWrapper // Applies to all methods in this command
+/// class MyCommand {
+///
+///   @Executes("fast")
+///   void fastCommand(S source) {
+///     // Defaults to @TimingWrapper
+///   }
+///
+///   @Executes("admin")
+///   @DifferentWrapper // Override with a different wrapper for this method
+///   void adminCommand(S source) {
+///     // ...
+///   }
+/// }
+/// ```
+///
+/// @see UnsetExecutorWrapper
+@Retention(RetentionPolicy.SOURCE)
+@Target(ElementType.ANNOTATION_TYPE)
+public @interface CustomExecutorWrapper {
+}

annotations-common/src/main/java/net/strokkur/commands/DefaultExecutes.java

@@ -62,7 +62,7 @@
 /// If multiple [DefaultExecutes]-annotated methods are present, the **deeper one** in the tree takes precedence.
 /// If multiple [DefaultExecutes]-annotated methods are present on the same path, the first declared one takes precedence.
 @Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.METHOD)
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
 public @interface DefaultExecutes {
   /// A literal path to prepend to the method.
   ///

annotations-common/src/main/java/net/strokkur/commands/Executes.java

@@ -35,7 +35,7 @@
 /// }
 /// ```
 @Retention(RetentionPolicy.SOURCE)
-@Target(ElementType.METHOD)
+@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
 public @interface Executes {
   /// A literal path to prepend to the method.
   ///

annotations-common/src/main/java/net/strokkur/commands/Subcommand.java

@@ -43,7 +43,7 @@
 /// }
 /// ```
 @Retention(RetentionPolicy.SOURCE)
-@Target({ElementType.TYPE, ElementType.FIELD})
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.ANNOTATION_TYPE})
 public @interface Subcommand {
   /// {@return the literal path to prepend to the nested subcommand}
   String value() default "";

annotations-common/src/main/java/net/strokkur/commands/UnsetExecutorWrapper.java

@@ -0,0 +1,51 @@
+/*
+ * StrokkCommands - A super simple annotation based zero-shade Paper command API library.
+ * Copyright (C) 2025 Strokkur24
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <https://www.gnu.org/licenses/>.
+ */
+package net.strokkur.commands;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/// Unsets an inherited executor wrapper. This annotation can be used if an entire class is annotated
+/// with a [CustomExecutorWrapper]-annotated annotation, but certain children should be excluded from this.
+///
+/// ## Example usage
+/// ```java
+/// @TimingsExecutor
+/// @Command("heavy-command")
+/// class HeavyCommand {
+///
+///   @Executes
+///   void someHeavyOperation() {
+///     // This is wrapped by `@TimingsExecutor`
+///   }
+///
+///   @Executes("light")
+///   @UnsetExecutorWrapper
+///   void someLightOperation() {
+///     // This handler is *not* wrapped by `@TimingsExecutor`
+///   }
+/// }
+/// ```
+///
+/// @see CustomExecutorWrapper
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
+public @interface UnsetExecutorWrapper {
+}

processor-common/src/main/java/net/strokkur/commands/internal/NodeUtils.java

@@ -18,8 +18,10 @@
 package net.strokkur.commands.internal;
 
 import net.strokkur.commands.Literal;
+import net.strokkur.commands.UnsetExecutorWrapper;
 import net.strokkur.commands.internal.abstraction.AnnotationsHolder;
 import net.strokkur.commands.internal.abstraction.SourceClass;
+import net.strokkur.commands.internal.abstraction.SourceElement;
 import net.strokkur.commands.internal.abstraction.SourceVariable;
 import net.strokkur.commands.internal.arguments.BrigadierArgumentConverter;
 import net.strokkur.commands.internal.arguments.BrigadierArgumentType;
@@ -31,9 +33,11 @@
 import net.strokkur.commands.internal.exceptions.ConversionException;
 import net.strokkur.commands.internal.intermediate.attributes.Attributable;
 import net.strokkur.commands.internal.intermediate.attributes.AttributeKey;
+import net.strokkur.commands.internal.intermediate.registrable.ExecutorWrapperRegistry;
 import net.strokkur.commands.internal.intermediate.registrable.RegistrableRegistry;
 import net.strokkur.commands.internal.intermediate.registrable.RequirementRegistry;
 import net.strokkur.commands.internal.intermediate.registrable.SuggestionsRegistry;
+import net.strokkur.commands.internal.intermediate.tree.CommandNode;
 import net.strokkur.commands.internal.util.ForwardingMessagerWrapper;
 import net.strokkur.commands.internal.util.MessagerWrapper;
 
@@ -47,9 +51,25 @@ public record NodeUtils(
     MessagerWrapper messager,
     BrigadierArgumentConverter converter,
     SuggestionsRegistry suggestionsRegistry,
-    RequirementRegistry requirementRegistry
+    RequirementRegistry requirementRegistry,
+    ExecutorWrapperRegistry executorWrapperRegistry
 ) implements ForwardingMessagerWrapper {
 
+  public void applyExecutorTransform(final Attributable node, final AnnotationsHolder element) {
+    if (element.hasAnnotationInherited(UnsetExecutorWrapper.class)) {
+      node.setAttribute(AttributeKey.EXECUTOR_WRAPPER_UNSET, true);
+      return;
+    }
+
+    this.applyRegistrableProvider(
+        node,
+        element,
+        this.executorWrapperRegistry(),
+        AttributeKey.EXECUTOR_WRAPPER,
+        "executor wrapper"
+    );
+  }
+
   public List<CommandArgument> parseArguments(final List<? extends SourceVariable> variables) {
     final List<CommandArgument> arguments = new ArrayList<>(variables.size());
 
@@ -87,20 +107,20 @@ public List<CommandArgument> parseArguments(final List<? extends SourceVariable>
   }
 
   public <T> void applyRegistrableProvider(
-      final Attributable argument,
-      final AnnotationsHolder parameter,
+      final Attributable attributable,
+      final AnnotationsHolder element,
       final RegistrableRegistry<T> registry,
       final AttributeKey<T> key,
       final String name
   ) {
     boolean found = false;
-    for (final SourceClass annotationType : parameter.getAllAnnotations()) {
+    for (final SourceClass annotationType : element.getAllAnnotations()) {
       final Optional<T> provider = registry.getProvider(annotationType);
       if (provider.isPresent()) {
         if (found) {
-          this.infoSource("Multiple %s providers has been declared", parameter, name);
+          this.infoSource("Multiple %s providers has been declared", element, name);
         } else {
-          argument.setAttribute(key, provider.get());
+          attributable.setAttribute(key, provider.get());
           found = true;
         }
       }

processor-common/src/main/java/net/strokkur/commands/internal/StrokkCommandsProcessor.java

@@ -17,6 +17,7 @@
  */
 package net.strokkur.commands.internal;
 
+import net.strokkur.commands.CustomExecutorWrapper;
 import net.strokkur.commands.CustomRequirement;
 import net.strokkur.commands.CustomSuggestion;
 import net.strokkur.commands.internal.abstraction.SourceClass;
@@ -26,6 +27,7 @@
 import net.strokkur.commands.internal.arguments.BrigadierArgumentConverter;
 import net.strokkur.commands.internal.exceptions.ProviderAlreadyRegisteredException;
 import net.strokkur.commands.internal.intermediate.CommonTreePostProcessor;
+import net.strokkur.commands.internal.intermediate.registrable.ExecutorWrapperRegistry;
 import net.strokkur.commands.internal.intermediate.registrable.RegistrableRegistry;
 import net.strokkur.commands.internal.intermediate.registrable.RequirementRegistry;
 import net.strokkur.commands.internal.intermediate.registrable.SuggestionsRegistry;
@@ -92,8 +94,9 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
     final MessagerWrapper messagerWrapper = MessagerWrapper.wrap(super.processingEnv.getMessager());
     final SuggestionsRegistry suggestionsRegistry = createAndFillRegistry(CustomSuggestion.class, SuggestionsRegistry::new, roundEnv, messagerWrapper);
     final RequirementRegistry requirementRegistry = createAndFillRegistry(CustomRequirement.class, RequirementRegistry::new, roundEnv, messagerWrapper);
+    final ExecutorWrapperRegistry executorWrapperRegistry = createAndFillRegistry(CustomExecutorWrapper.class, ExecutorWrapperRegistry::new, roundEnv, messagerWrapper);
 
-    final NodeUtils nodeUtils = new NodeUtils(getPlatformUtils(), messagerWrapper, getConverter(messagerWrapper), suggestionsRegistry, requirementRegistry);
+    final NodeUtils nodeUtils = new NodeUtils(getPlatformUtils(), messagerWrapper, getConverter(messagerWrapper), suggestionsRegistry, requirementRegistry, executorWrapperRegistry);
     final CommandParser parser = new CommandParserImpl(
         messagerWrapper,
         nodeUtils,
@@ -168,7 +171,7 @@ private void processElement(
     boolean debug = System.getProperty(MessagerWrapper.DEBUG_SYSTEM_PROPERTY) != null;
 
     final C commandInformation = getCommandInformation(sourceClass);
-    final CommandNode commandTree = parser.createCommandTree(getCommandName(sourceClass.getAnnotationElseThrow(targetAnnotationClass())), sourceClass);
+    final CommandNode commandTree = parser.createCommandTree(getCommandName(sourceClass.getAnnotationInheritedElseThrow(targetAnnotationClass())), sourceClass);
     if (commandTree == null) {
       return;
     }
@@ -212,15 +215,15 @@ private <T extends RegistrableRegistry<?>> T createAndFillRegistry(
     for (final Element element : roundEnv.getElementsAnnotatedWith(annotationClass)) {
       try {
         if (element.getKind() != ElementKind.ANNOTATION_TYPE || !(element instanceof TypeElement typeElement)) {
-          messager.errorElement("non-annotation type annotated with @CustomSuggestion", element);
+          messager.errorElement("non-annotation type annotated with @" + annotationClass.getSimpleName(), element);
           continue;
         }
 
-        for (final Element annotatedElements : roundEnv.getElementsAnnotatedWith(typeElement)) {
+        for (final Element annotatedElement : roundEnv.getElementsAnnotatedWith(typeElement)) {
           if (registry.tryRegisterProvider(
               messager,
               new SourceClassImpl(this.processingEnv, (DeclaredType) typeElement.asType()),
-              SourceTypeUtils.getSourceElement(this.processingEnv, annotatedElements)
+              SourceTypeUtils.getSourceElement(this.processingEnv, annotatedElement)
           )) {
             break;
           }

processor-common/src/main/java/net/strokkur/commands/internal/abstraction/AnnotationsHolder.java

@@ -30,8 +30,8 @@ public interface AnnotationsHolder extends SourceElement {
 
   List<SourceClass> getAllAnnotations();
 
-  default boolean hasAnnotation(final Class<? extends Annotation> type) {
-    return getAnnotationOptional(type).isPresent();
+  default boolean hasAnnotationInherited(final Class<? extends Annotation> type) {
+    return this.getAnnotationInheritedOptional(type).isPresent();
   }
 
   default <T extends Annotation> @Nullable SourceClass getAnnotationSourceClassField(Class<T> type, String fieldName) throws UnsupportedOperationException {
@@ -42,7 +42,23 @@ default <T extends Annotation> Optional<T> getAnnotationOptional(final Class<T>
     return Optional.ofNullable(getAnnotation(type));
   }
 
-  default <T extends Annotation> T getAnnotationElseThrow(final Class<T> type) throws NoSuchElementException {
-    return getAnnotationOptional(type).orElseThrow(() -> new NoSuchElementException("No annotation of type " + type.getSimpleName() + " is present."));
+  default <T extends Annotation> Optional<T> getAnnotationInheritedOptional(final Class<T> type) {
+    final T direct = this.getAnnotation(type);
+    if (direct != null) {
+      return Optional.of(direct);
+    }
+
+    for (final SourceClass annotationClass : this.getAllAnnotations()) {
+      final T inherited = annotationClass.getAnnotation(type);
+      if (inherited != null) {
+        return Optional.of(inherited);
+      }
+    }
+
+    return Optional.empty();
+  }
+
+  default <T extends Annotation> T getAnnotationInheritedElseThrow(final Class<T> type) throws NoSuchElementException {
+    return getAnnotationInheritedOptional(type).orElseThrow(() -> new NoSuchElementException("No annotation of type " + type.getSimpleName() + " is present."));
   }
 }

processor-common/src/main/java/net/strokkur/commands/internal/intermediate/attributes/Attributable.java

@@ -17,6 +17,7 @@
  */
 package net.strokkur.commands.internal.intermediate.attributes;
 
+import org.jetbrains.annotations.Contract;
 import org.jspecify.annotations.Nullable;
 
 import java.util.Objects;
@@ -30,7 +31,8 @@ public interface Attributable {
   @Nullable
   <T> T getAttribute(AttributeKey<T> key);
 
-  default <T> T getAttributeOr(AttributeKey<T> key, T defaultValue) {
+  @Contract("_, !null -> !null")
+  default <T> @Nullable T getAttributeOr(AttributeKey<T> key, @Nullable T defaultValue) {
     return Optional.ofNullable(getAttribute(key)).orElse(defaultValue);
   }
 

processor-common/src/main/java/net/strokkur/commands/internal/intermediate/attributes/AttributeKey.java

@@ -18,6 +18,7 @@
 package net.strokkur.commands.internal.intermediate.attributes;
 
 import net.strokkur.commands.internal.intermediate.access.ExecuteAccess;
+import net.strokkur.commands.internal.intermediate.registrable.ExecutorWrapperProvider;
 import net.strokkur.commands.internal.intermediate.registrable.RequirementProvider;
 import net.strokkur.commands.internal.intermediate.registrable.SuggestionProvider;
 import org.jetbrains.annotations.Contract;
@@ -32,6 +33,9 @@ public interface AttributeKey<T> {
   AttributeKey<DefaultExecutable> DEFAULT_EXECUTABLE = create("default_executable", null);
   AttributeKey<List<ExecuteAccess<?>>> ACCESS_STACK = create("access_stack", null);
 
+  AttributeKey<ExecutorWrapperProvider> EXECUTOR_WRAPPER = create("executor_wrapper", null);
+  AttributeKey<Boolean> EXECUTOR_WRAPPER_UNSET = create("executor_wrapper_unset", false);
+
   AttributeKey<RequirementProvider> REQUIREMENT_PROVIDER = create("requirement_provider", null);
   AttributeKey<SuggestionProvider> SUGGESTION_PROVIDER = create("suggestion_provider", null);