Incendo · Citymonstret · Jan 30, 2024 · Jan 29, 2024
diff --git a/.palantir/revapi.yml b/.palantir/revapi.yml
@@ -11,6 +11,39 @@ acceptedBreaks:
       new: "class cloud.commandframework.services.types.ConsumerService.PipeBurst"
       justification: "no practical effect, the constructor was private already"
   "2.0.0-beta.1":
+    org.incendo:cloud-annotations:
+    - code: "java.method.parameterTypeChanged"
+      old: "parameter org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor\
+        \ org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor::of(java.lang.reflect.Parameter,\
+        \ java.lang.String, java.lang.String, java.lang.String, ===java.lang.String===,\
+        \ org.incendo.cloud.description.Description)"
+      new: "parameter org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor\
+        \ org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor::of(java.lang.reflect.Parameter,\
+        \ java.lang.String, java.lang.String, java.lang.String, ===org.incendo.cloud.component.DefaultValue<?,\
+        \ ?>===, org.incendo.cloud.description.Description)"
+      justification: "Change of internal annotation API between beta releases"
+    - code: "java.method.parameterTypeChanged"
+      old: "parameter org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor\
+        \ org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor::withDefaultValue(===java.lang.String===)"
+      new: "parameter org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor\
+        \ org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor::withDefaultValue(===org.incendo.cloud.component.DefaultValue<?,\
+        \ ?>===)"
+      justification: "Change of internal annotation API between beta releases"
+    - code: "java.method.parameterTypeChanged"
+      old: "parameter org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor.Builder\
+        \ org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor.Builder::defaultValue(===java.lang.String===)"
+      new: "parameter org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor.Builder\
+        \ org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor.Builder::defaultValue(===org.incendo.cloud.component.DefaultValue<?,\
+        \ ?>===)"
+      justification: "Change of internal annotation API between beta releases"
+    - code: "java.method.returnTypeChanged"
+      old: "method java.lang.String org.incendo.cloud.annotations.descriptor.ArgumentDescriptor::defaultValue()"
+      new: "method org.incendo.cloud.component.DefaultValue<?, ?> org.incendo.cloud.annotations.descriptor.ArgumentDescriptor::defaultValue()"
+      justification: "Change of internal annotation API between beta releases"
+    - code: "java.method.returnTypeChanged"
+      old: "method java.lang.String org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor::defaultValue()"
+      new: "method org.incendo.cloud.component.DefaultValue<?, ?> org.incendo.cloud.annotations.descriptor.ImmutableArgumentDescriptor::defaultValue()"
+      justification: "Change of internal annotation API between beta releases"
     org.incendo:cloud-core:
     - code: "java.annotation.attributeValueChanged"
       old: "method void org.incendo.cloud.Command<C>::<init>(java.util.List<org.incendo.cloud.component.CommandComponent<C>>,\

diff --git a/cloud-annotations/src/main/java/org/incendo/cloud/annotations/AnnotationParser.java b/cloud-annotations/src/main/java/org/incendo/cloud/annotations/AnnotationParser.java
@@ -42,6 +42,7 @@
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Function;
@@ -134,6 +135,7 @@ public final class AnnotationParser<C> {
     private SuggestionProviderFactory<C> suggestionProviderFactory;
     private ExceptionHandlerFactory<C> exceptionHandlerFactory;
     private DescriptionMapper descriptionMapper;
+    private DefaultValueRegistry<C> defaultValueRegistry;
 
     /**
      * Construct a new annotation parser
@@ -212,6 +214,7 @@ public AnnotationParser(
         this.suggestionProviderFactory = SuggestionProviderFactory.defaultFactory();
         this.exceptionHandlerFactory = ExceptionHandlerFactory.defaultFactory();
         this.builderDecorators = new ArrayList<>();
+        this.defaultValueRegistry = new DefaultValueRegistryImpl<>();
         this.registerBuilderModifier(
                 CommandDescription.class,
                 (description, builder) -> builder.commandDescription(commandDescription(this.mapDescription(description.value())))
@@ -607,6 +610,24 @@ public void descriptionMapper(final @NonNull DescriptionMapper descriptionMapper
         this.descriptionMapper = descriptionMapper;
     }
 
+    /**
+     * Returns the default value registry.
+     *
+     * @return the default value registry
+     */
+    public @NonNull DefaultValueRegistry<C> defaultValueRegistry() {
+        return this.defaultValueRegistry;
+    }
+
+    /**
+     * Sets the default value registry.
+     *
+     * @param defaultValueRegistry default value registry
+     */
+    public void defaultValueRegistry(final @NonNull DefaultValueRegistry<C> defaultValueRegistry) {
+        this.defaultValueRegistry = Objects.requireNonNull(defaultValueRegistry, "defaultValueRegistry");
+    }
+
     /**
      * Parses all known {@link org.incendo.cloud.annotations.processing.CommandContainer command containers}.
      *
@@ -689,6 +710,7 @@ public void descriptionMapper(final @NonNull DescriptionMapper descriptionMapper
      */
     @SuppressWarnings({"unchecked", "rawtypes"})
     public <T> @NonNull Collection<org.incendo.cloud.@NonNull Command<C>> parse(final @NonNull T instance) {
+        this.parseDefaultValues(instance);
         this.parseSuggestions(instance);
         this.parseParsers(instance);
         this.parseExceptionHandlers(instance);
@@ -778,6 +800,24 @@ private <T> void parseExceptionHandlers(final @NonNull T instance) {
         }
     }
 
+    private <T> void parseDefaultValues(final @NonNull T instance) {
+        for (final Method method : instance.getClass().getMethods()) {
+            final Default defaultValue = method.getAnnotation(Default.class);
+            if (defaultValue == null) {
+                continue;
+            }
+
+            final String name;
+            if (defaultValue.name().isEmpty()) {
+                name = method.getName();
+            } else {
+                name = defaultValue.name();
+            }
+
+            this.defaultValueRegistry().register(name, new MethodDefaultValueFactory<>(method, instance));
+        }
+    }
+
     private <T> void parseParsers(final @NonNull T instance) {
         for (final Method method : instance.getClass().getMethods()) {
             final Parser parser = method.getAnnotation(Parser.class);

diff --git a/cloud-annotations/src/main/java/org/incendo/cloud/annotations/Default.java b/cloud-annotations/src/main/java/org/incendo/cloud/annotations/Default.java
@@ -31,21 +31,43 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 /**
- * Used to give an optional command component a
- * {@link org.incendo.cloud.component.DefaultValue#parsed(String) parsed default value}.
+ * <b>When used on a method parameter:</b><br/>
+ * Used to give an optional {@link Argument} a {@link org.incendo.cloud.component.DefaultValue}.
  *
+ * <p>If {@link #value()} is used then a parsed default value will be created. If {@link #name()} is used then a dynamic
+ * default value registered to the {@link DefaultValueRegistry} will be used.</p>
+ *
+ * <hr/>
+ * <b>When used on a method:</b><br>
+ * Used to indicate that a method is a {@link DefaultValueFactory}. The method must return a
+ * {@link org.incendo.cloud.component.DefaultValue} instance. The <i>only</i> accepted method parameter is a
+ * {@link java.lang.reflect.Parameter} which represents the parameter that the default value is being created for.
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target(ElementType.PARAMETER)
+@Target({ElementType.PARAMETER, ElementType.METHOD})
 @API(status = API.Status.STABLE)
 public @interface Default {
 
     /**
-     * Returns the default value.
-     * <p>
-     * This value will be parsed when the command is being parsed in the case that the optional parameter has been omitted.
+     * Returns the default value. {@link #name()} will take priority when non-empty and used on a parameter.
+     *
+     * <p>This value will be parsed when the command is being parsed in the case that the optional parameter has been omitted.</p>
      *
      * @return the default value
      */
-    @NonNull String value();
+    @NonNull String value() default "";
+
+    /**
+     * If used on a parameter this returns the name of the {@link DefaultValueFactory} used to create the default value.
+     *
+     * <p>If used on a method, this indicates the name of the {@link DefaultValueFactory} represented by the method. If this
+     * is empty, the method name will be used.</p>
+     *
+     * <p>The factories must be registered to the {@link DefaultValueRegistry} retrieved
+     * through {@link AnnotationParser#defaultValueRegistry()}. Using {@link AnnotationParser#parse(Object)} will scan &amp;
+     * register all {@code @Default}-annotated methods.</p>
+     *
+     * @return name of the default value registry to use
+     */
+    @NonNull String name() default "";
 }
diff --git a/cloud-annotations/src/main/java/org/incendo/cloud/annotations/DefaultValueFactory.java b/cloud-annotations/src/main/java/org/incendo/cloud/annotations/DefaultValueFactory.java
@@ -0,0 +1,60 @@
+//
+// MIT License
+//
+// Copyright (c) 2024 Incendo
+//
+// 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 org.incendo.cloud.annotations;
+
+import java.lang.reflect.Parameter;
+import org.apiguardian.api.API;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.incendo.cloud.component.DefaultValue;
+
+/**
+ * Factory that produces default value instances.
+ *
+ * @param <C> command sender type
+ * @param <T> value type
+ */
+@FunctionalInterface
+@API(status = API.Status.STABLE)
+public interface DefaultValueFactory<C, T> {
+
+    /**
+     * Creates a default value factory that always returns the given {@code defaultValue}.
+     *
+     * @param <C>          command sender type
+     * @param <T>          type of the value
+     * @param defaultValue default value instance
+     * @return the created factory
+     */
+    static <C, T> @NonNull DefaultValueFactory<C, T> constant(final @NonNull DefaultValue<C, T> defaultValue) {
+        return parameter -> defaultValue;
+    }
+
+    /**
+     * Creates the default value.
+     *
+     * @param parameter parameter to create the default value for
+     * @return the default value
+     */
+    @NonNull DefaultValue<C, T> create(@NonNull Parameter parameter);
+}
diff --git a/cloud-annotations/src/main/java/org/incendo/cloud/annotations/DefaultValueRegistry.java b/cloud-annotations/src/main/java/org/incendo/cloud/annotations/DefaultValueRegistry.java
@@ -0,0 +1,56 @@
+//
+// MIT License
+//
+// Copyright (c) 2024 Incendo
+//
+// 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 org.incendo.cloud.annotations;
+
+import java.util.Optional;
+import org.apiguardian.api.API;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.common.returnsreceiver.qual.This;
+
+/**
+ * Registry that stores mappings between names and {@link DefaultValueFactory default value factories}.
+ *
+ * @param <C> command sender type
+ */
+@API(status = API.Status.STABLE)
+public interface DefaultValueRegistry<C> {
+
+    /**
+     * Registers the named default value.
+     *
+     * @param <T>          default value type
+     * @param name         name of the default value
+     * @param defaultValue default value
+     * @return {@code this}
+     */
+    <T> @This @NonNull DefaultValueRegistry<C> register(@NonNull String name, @NonNull DefaultValueFactory<C, T> defaultValue);
+
+    /**
+     * Returns the default value with the given {@code name}, if it exists.
+     *
+     * @param name name of the default value
+     * @return optional that contains the default value, if it has been {@link #register(String, DefaultValueFactory) registered}
+     */
+    @NonNull Optional<@NonNull DefaultValueFactory<C, ?>> named(@NonNull String name);
+}
diff --git a/cloud-annotations/src/main/java/org/incendo/cloud/annotations/DefaultValueRegistryImpl.java b/cloud-annotations/src/main/java/org/incendo/cloud/annotations/DefaultValueRegistryImpl.java
@@ -0,0 +1,50 @@
+//
+// MIT License
+//
+// Copyright (c) 2024 Incendo
+//
+// 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 org.incendo.cloud.annotations;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.common.returnsreceiver.qual.This;
+
+final class DefaultValueRegistryImpl<C> implements DefaultValueRegistry<C> {
+
+    private final Map<String, DefaultValueFactory<C, ?>> factories = new HashMap<>();
+
+    @Override
+    public @This @NonNull <T> DefaultValueRegistry<C> register(
+            final @NonNull String name,
+            final @NonNull DefaultValueFactory<C, T> defaultValue
+    ) {
+        this.factories.put(Objects.requireNonNull(name, "name"), Objects.requireNonNull(defaultValue, "defaultValue"));
+        return this;
+    }
+
+    @Override
+    public @NonNull Optional<@NonNull DefaultValueFactory<C, ?>> named(final @NonNull String name) {
+        return Optional.ofNullable(this.factories.get(Objects.requireNonNull(name, "name")));
+    }
+}