Implement @Attribute Injection. (#5547)

### Motivation:
- In the past, users could get a value from `ServiceRequestContext` by
using `ServiceRequestContext.attr(key)`. however, if it were possible to
inject values which in `ServiceRequestContext` into method parameters
using any annotation, users would be able to use it more conveniently.

### Modifications:
- New annotation. `@Attribute` is added.
- Make new field `rawType` in `AnnotatedValueResolver` to validate type
cast.
- New methods `ofAttribute()` and `attributeResolver()` are added to
`AnnotatedValueResolver` to get values from `ServiceRequestContext` and
inject them method parameters.
- `findName()` in `AnnotatedElementNameUtil` method have been merged
into a single method. (refactoring for internal use)
- Add test codes. 
- Add document explaining how to use the `@Attribute` annotation.

### Result:
- Closes #5514
- Users can inject values from the `ServiceRequestContext` into method
parameters using the `@Attribute` annotation without
`ServiceRequestContext.attr(key)`.

---------

Co-authored-by: Trustin Lee <t@motd.kr>
Co-authored-by: Ikhun Um <ih.pert@gmail.com>
Co-authored-by: minux <songmw725@gmail.com>

core/src/main/java/com/linecorp/armeria/internal/server/annotation/AnnotatedElementNameUtil.java

@@ -21,52 +21,29 @@
 import java.lang.reflect.Field;
 import java.lang.reflect.Parameter;
 
-import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Ascii;
 import com.google.common.base.CaseFormat;
 
+import com.linecorp.armeria.server.annotation.Attribute;
 import com.linecorp.armeria.server.annotation.Header;
 import com.linecorp.armeria.server.annotation.Param;
 
 final class AnnotatedElementNameUtil {
 
     /**
-     * Returns the value of the {@link Param} annotation which is specified on the {@code element} if
-     * the value is not blank. If the value is blank, it returns the name of the specified
-     * {@code nameRetrievalTarget} object which is an instance of {@link Parameter} or {@link Field}.
+     * Returns the value of {@link Header}, {@link Param}, {@link Attribute} if the value is not blank.
+     * If the value is blank, it returns the name of the specified {@code nameRetrievalTarget} object
+     * which is an instance of {@link Header}, {@link Param}, {@link Attribute} or {@link Field}.
      */
-    static String findName(Param param, Object nameRetrievalTarget) {
+    static String findName(Object nameRetrievalTarget, String value) {
         requireNonNull(nameRetrievalTarget, "nameRetrievalTarget");
-
-        final String value = param.value();
         if (DefaultValues.isSpecified(value)) {
             checkArgument(!value.isEmpty(), "value is empty.");
             return value;
         }
         return getName(nameRetrievalTarget);
     }
 
-    /**
-     * Returns the value of the {@link Header} annotation which is specified on the {@code element} if
-     * the value is not blank. If the value is blank, it returns the name of the specified
-     * {@code nameRetrievalTarget} object which is an instance of {@link Parameter} or {@link Field}.
-     *
-     * <p>Note that the name of the specified {@code nameRetrievalTarget} will be converted as
-     * {@link CaseFormat#LOWER_HYPHEN} that the string elements are separated with one hyphen({@code -})
-     * character. The value of the {@link Header} annotation will not be converted because it is clearly
-     * specified by a user.
-     */
-    static String findName(Header header, Object nameRetrievalTarget) {
-        requireNonNull(nameRetrievalTarget, "nameRetrievalTarget");
-
-        final String value = header.value();
-        if (DefaultValues.isSpecified(value)) {
-            checkArgument(!value.isEmpty(), "value is empty.");
-            return value;
-        }
-        return toHeaderName(getName(nameRetrievalTarget));
-    }
-
     /**
      * Returns the name of the specified element or the default name if it can't get.
      */
@@ -89,8 +66,7 @@ static String getName(Object element) {
                 throw new IllegalArgumentException(
                         "cannot obtain the name of the parameter or field automatically. " +
                         "Please make sure you compiled your code with '-parameters' option. " +
-                        "If not, you need to specify parameter and header names with @" +
-                        Param.class.getSimpleName() + " and @" + Header.class.getSimpleName() + '.');
+                        "Alternatively, you could specify the name explicitly in the annotation.");
             }
             return parameter.getName();
         }
@@ -100,7 +76,6 @@ static String getName(Object element) {
         throw new IllegalArgumentException("cannot find the name: " + element.getClass().getName());
     }
 
-    @VisibleForTesting
     static String toHeaderName(String name) {
         requireNonNull(name, "name");
         checkArgument(!name.isEmpty(), "name is empty.");

core/src/main/java/com/linecorp/armeria/internal/server/annotation/AnnotatedValueResolver.java

@@ -22,6 +22,7 @@
 import static com.linecorp.armeria.internal.server.annotation.AnnotatedElementNameUtil.findName;
 import static com.linecorp.armeria.internal.server.annotation.AnnotatedElementNameUtil.getName;
 import static com.linecorp.armeria.internal.server.annotation.AnnotatedElementNameUtil.getNameOrDefault;
+import static com.linecorp.armeria.internal.server.annotation.AnnotatedElementNameUtil.toHeaderName;
 import static com.linecorp.armeria.internal.server.annotation.AnnotatedServiceFactory.findDescription;
 import static com.linecorp.armeria.internal.server.annotation.AnnotatedServiceTypeUtil.stringToType;
 import static com.linecorp.armeria.internal.server.annotation.DefaultValues.getSpecifiedValue;
@@ -64,6 +65,7 @@
 import com.google.common.base.Splitter;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Iterables;
+import com.google.common.primitives.Primitives;
 
 import com.linecorp.armeria.common.AggregatedHttpRequest;
 import com.linecorp.armeria.common.Cookie;
@@ -85,6 +87,7 @@
 import com.linecorp.armeria.internal.server.annotation.AnnotatedBeanFactoryRegistry.BeanFactoryId;
 import com.linecorp.armeria.server.ServiceRequestContext;
 import com.linecorp.armeria.server.annotation.AnnotatedService;
+import com.linecorp.armeria.server.annotation.Attribute;
 import com.linecorp.armeria.server.annotation.ByteArrayRequestConverterFunction;
 import com.linecorp.armeria.server.annotation.Default;
 import com.linecorp.armeria.server.annotation.Delimiter;
@@ -100,6 +103,7 @@
 import com.linecorp.armeria.server.docs.DescriptionInfo;
 
 import io.netty.handler.codec.http.HttpConstants;
+import io.netty.util.AttributeKey;
 import scala.concurrent.ExecutionContext;
 
 final class AnnotatedValueResolver {
@@ -445,9 +449,16 @@ private static AnnotatedValueResolver of(AnnotatedElement annotatedElement,
         requireNonNull(dependencyInjector, "dependencyInjector");
 
         final DescriptionInfo description = findDescription(annotatedElement);
+
+        final Attribute attr = annotatedElement.getAnnotation(Attribute.class);
+        if (attr != null) {
+            final String name = findName(typeElement, attr.value());
+            return ofAttribute(name, attr, annotatedElement, typeElement, type, description);
+        }
+
         final Param param = annotatedElement.getAnnotation(Param.class);
         if (param != null) {
-            final String name = findName(param, typeElement);
+            final String name = findName(typeElement, param.value());
             if (type == File.class || type == Path.class || type == MultipartFile.class) {
                 return ofFileParam(name, annotatedElement, typeElement, type, description);
             }
@@ -460,7 +471,7 @@ private static AnnotatedValueResolver of(AnnotatedElement annotatedElement,
 
         final Header header = annotatedElement.getAnnotation(Header.class);
         if (header != null) {
-            final String name = findName(header, typeElement);
+            final String name = toHeaderName(findName(typeElement, header.value()));
             return ofHeader(name, annotatedElement, typeElement, type, description);
         }
 
@@ -521,6 +532,7 @@ static List<RequestObjectResolver> addToFirstIfExists(List<RequestObjectResolver
 
     private static boolean isAnnotationPresent(AnnotatedElement element) {
         return element.isAnnotationPresent(Param.class) ||
+               element.isAnnotationPresent(Attribute.class) ||
                element.isAnnotationPresent(Header.class) ||
                element.isAnnotationPresent(RequestObject.class);
     }
@@ -622,6 +634,34 @@ private static AnnotatedValueResolver ofRequestObject(String name, AnnotatedElem
                 .build();
     }
 
+    private static AnnotatedValueResolver ofAttribute(String name,
+                                                      Attribute attr,
+                                                      AnnotatedElement annotatedElement,
+                                                      AnnotatedElement typeElement, Class<?> type,
+                                                      DescriptionInfo description) {
+
+        final ImmutableList.Builder<AttributeKey<?>> builder = ImmutableList.builder();
+
+        if (attr.prefix() != Attribute.class) {
+            builder.add(AttributeKey.valueOf(attr.prefix(), name));
+        } else {
+            final Class<?> serviceClass = ((Parameter) annotatedElement).getDeclaringExecutable()
+                                                                        .getDeclaringClass();
+            builder.add(AttributeKey.valueOf(serviceClass, name));
+            builder.add(AttributeKey.valueOf(name));
+        }
+
+        final ImmutableList<AttributeKey<?>> attrKeys = builder.build();
+        return new Builder(annotatedElement, type, name)
+                .annotationType(Attribute.class)
+                .typeElement(typeElement)
+                .supportDefault(true)
+                .supportContainer(true)
+                .description(description)
+                .resolver(attributeResolver(attrKeys))
+                .build();
+    }
+
     @Nullable
     private static AnnotatedValueResolver ofInjectableTypes(String name, AnnotatedElement annotatedElement,
                                                             Class<?> type, boolean useBlockingExecutor) {
@@ -819,6 +859,36 @@ private static AnnotatedValueResolver ofInjectableTypes0(String name, AnnotatedE
         };
     }
 
+    /**
+     * Returns an attribute resolver which retrieves a value specified by {@code attrKeys}
+     * from the {@link RequestContext}.
+     */
+    private static BiFunction<AnnotatedValueResolver, ResolverContext, Object>
+    attributeResolver(Iterable<AttributeKey<?>> attrKeys) {
+        return (resolver, ctx) -> {
+            Class<?> targetType = resolver.rawType();
+            if (targetType.isPrimitive()) {
+                targetType = Primitives.wrap(targetType);
+            }
+
+            for (AttributeKey<?> attrKey : attrKeys) {
+                final Object value = ctx.context.attr(attrKey);
+                if (value != null) {
+                    if (!targetType.isInstance(value)) {
+                        throw new IllegalStateException(
+                                String.format("Cannot inject the attribute '%s' due to " +
+                                              "mismatching type (expected: %s, actual: %s)",
+                                              attrKey.name(),
+                                              targetType.getName(),
+                                              value.getClass().getName()));
+                    }
+                    return value;
+                }
+            }
+            return resolver.defaultOrException();
+        };
+    }
+
     private static BiFunction<AnnotatedValueResolver, ResolverContext, Object> fileResolver() {
         return (resolver, ctx) -> {
             final FileAggregatedMultipart fileAggregatedMultipart = ctx.aggregatedMultipart();
@@ -897,6 +967,7 @@ static boolean isAnnotatedNullable(AnnotatedElement annotatedElement) {
 
     @Nullable
     private final Class<?> containerType;
+    private final Class<?> rawType;
     private final Class<?> elementType;
     @Nullable
     private final ParameterizedType parameterizedElementType;
@@ -921,6 +992,7 @@ private AnnotatedValueResolver(@Nullable Class<? extends Annotation> annotationT
                                    boolean isPathVariable, boolean shouldExist,
                                    boolean shouldWrapValueAsOptional,
                                    @Nullable Class<?> containerType, Class<?> elementType,
+                                   Class<?> rawType,
                                    @Nullable ParameterizedType parameterizedElementType,
                                    @Nullable String defaultValue,
                                    DescriptionInfo description,
@@ -936,6 +1008,7 @@ private AnnotatedValueResolver(@Nullable Class<? extends Annotation> annotationT
         this.parameterizedElementType = parameterizedElementType;
         this.description = requireNonNull(description, "description");
         this.containerType = containerType;
+        this.rawType = rawType;
         this.resolver = requireNonNull(resolver, "resolver");
         this.beanFactoryId = beanFactoryId;
         this.aggregationStrategy = requireNonNull(aggregationStrategy, "aggregationStrategy");
@@ -981,6 +1054,10 @@ Class<?> containerType() {
         return containerType;
     }
 
+    Class<?> rawType() {
+        return rawType;
+    }
+
     Class<?> elementType() {
         return elementType;
     }
@@ -1053,7 +1130,8 @@ private Object defaultOrException() {
             }
             return defaultValue;
         }
-        throw new IllegalArgumentException("Mandatory parameter/header is missing: " + httpElementName);
+        throw new IllegalArgumentException("Mandatory parameter/header/attribute is missing: " +
+                                           httpElementName);
     }
 
     @Override
@@ -1107,6 +1185,7 @@ private Builder(AnnotatedElement annotatedElement, Type type, String name) {
          */
         private Builder annotationType(Class<? extends Annotation> annotationType) {
             assert annotationType == Param.class ||
+                   annotationType == Attribute.class ||
                    annotationType == Header.class ||
                    annotationType == RequestObject.class : annotationType.getSimpleName();
             this.annotationType = annotationType;
@@ -1241,6 +1320,13 @@ private AnnotatedValueResolver build() {
             }
 
             final Class<?> containerType = getContainerType(unwrappedParameterizedType);
+            final Class<?> rawType;
+            final Class<?> mayRawType = toRawType(unwrappedParameterizedType);
+            if (mayRawType.isPrimitive()) {
+                rawType = Primitives.wrap(mayRawType);
+            } else {
+                rawType = mayRawType;
+            }
             final Class<?> elementType;
             final ParameterizedType parameterizedElementType;
 
@@ -1269,7 +1355,7 @@ private AnnotatedValueResolver build() {
             }
 
             return new AnnotatedValueResolver(annotationType, httpElementName, pathVariable, shouldExist,
-                                              isOptional, containerType, elementType,
+                                              isOptional, containerType, elementType, rawType,
                                               parameterizedElementType, defaultValue, description, resolver,
                                               beanFactoryId, aggregation);
         }

core/src/main/java/com/linecorp/armeria/server/annotation/Attribute.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2016 LINE Corporation
+ *
+ * LINE Corporation licenses this file to you under the Apache License,
+ * version 2.0 (the "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at:
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ */
+
+package com.linecorp.armeria.server.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import com.linecorp.armeria.common.RequestContext;
+import com.linecorp.armeria.common.annotation.UnstableApi;
+
+import io.netty.util.AttributeKey;
+
+/**
+ * Annotation for mapping an attribute of the given {@link AttributeKey}, retrieved
+ * from a {@link RequestContext}, onto the following elements.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.PARAMETER)
+@UnstableApi
+public @interface Attribute {
+
+    /**
+     * The class of the {@link AttributeKey} to bind to. If you created an {@link AttributeKey} with
+     * {@code AttributeKey.valueOf(MyAttributeKeys.class, "INT_ATTR")},
+     * the {@link #prefix()} should be {@code MyAttributeKeys.class}.
+     * See <a href="https://armeria.dev/docs/advanced-custom-attributes/">advanced-customer-attributes</a>.
+     */
+    Class<?> prefix() default Attribute.class;
+
+    /**
+     * The name of the {@link AttributeKey} to bind to.
+     * You might also want to specify the {@link #prefix()}.
+     */
+    String value();
+}