Class AnnotationMerger

java.lang.Object
cloud.opencode.base.reflect.AnnotationMerger
public final class AnnotationMerger extends Object
Annotation Merger for composed annotation attribute resolution 注解合并器 - 组合注解属性解析

Resolves composed (meta-) annotation attributes, similar to Spring's AnnotatedElementUtils but standalone and dependency-free. When a composed annotation declares an attribute with the same name as one in its meta-annotation, the composed value overrides the meta value.

解析组合（元）注解属性，类似于 Spring 的 AnnotatedElementUtils， 但独立且无依赖。当组合注解声明了与其元注解同名的属性时， 组合注解的值将覆盖元注解的值。

Usage Examples | 使用示例:

// Given a composed annotation that meta-annotates @BaseAnnotation
@BaseAnnotation(priority = 10)
public @interface ComposedAnnotation {
    String value() default "composed";
}

@ComposedAnnotation(value = "test")
class MyClass {}

// Retrieve merged @BaseAnnotation with overridden attributes
BaseAnnotation merged = AnnotationMerger.getMergedAnnotation(
        MyClass.class, BaseAnnotation.class);
// merged.value() == "test"  (overridden by ComposedAnnotation)
// merged.priority() == 10   (from meta-annotation)

Security | 安全性:

  • Thread-safe: Yes (stateless utility) - 线程安全: 是（无状态工具类）
  • Null-safe: Yes (null element returns null/empty) - 空值安全: 是（null 元素返回 null/空）

Performance | 性能特性:

  • Time complexity: O(d) where d is the meta-annotation depth - 时间复杂度: O(d)，d 为元注解深度
  • Space complexity: O(a) where a is the number of annotation attributes - 空间复杂度: O(a)，a 为注解属性数量
Since:
JDK 25, opencode-base-reflect V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • getMergedAnnotation

      public static <A extends Annotation> A getMergedAnnotation(AnnotatedElement element, Class<A> annotationType)
      Gets a merged annotation, resolving composed annotation attribute overrides. 获取合并后的注解，解析组合注解属性覆盖

      If the annotation is directly present on the element, it is returned as-is. If found via a meta-annotation, attributes with matching names from the composed annotation override the meta-annotation defaults.

      如果注解直接存在于元素上，则直接返回。如果通过元注解找到， 则组合注解中同名的属性将覆盖元注解的默认值。

      Type Parameters:
      A - the annotation type | 注解类型
      Parameters:
      element - the annotated element | 被注解元素
      annotationType - the target annotation type | 目标注解类型
      Returns:
      the merged annotation, or null if not found | 合并后的注解，未找到则返回 null

    • getMergedAttributes

      public static <A extends Annotation> Map<String,Object> getMergedAttributes(AnnotatedElement element, Class<A> annotationType)
      Gets merged annotation attributes as a map. 获取合并后的注解属性映射

      Returns all attributes of the target annotation type with composed annotation overrides applied. Returns null if the annotation is not found on the element.

      返回目标注解类型的所有属性，应用组合注解的覆盖。 如果在元素上未找到注解，则返回 null。

      Type Parameters:
      A - the annotation type | 注解类型
      Parameters:
      element - the annotated element | 被注解元素
      annotationType - the target annotation type | 目标注解类型
      Returns:
      map of attribute names to values, or null if not found | 属性名到值的映射，未找到则返回 null

    • findAllMergedAnnotations

      public static <A extends Annotation> List<A> findAllMergedAnnotations(AnnotatedElement element, Class<A> annotationType)
      Finds all merged annotations of a type, including from composed annotations. 查找所有合并后的指定类型注解，包括来自组合注解的

      Searches the element's annotations and their meta-annotation hierarchies for all occurrences of the target annotation type.

      搜索元素的注解及其元注解层次结构，查找目标注解类型的所有出现。

      Type Parameters:
      A - the annotation type | 注解类型
      Parameters:
      element - the annotated element | 被注解元素
      annotationType - the target annotation type | 目标注解类型
      Returns:
      list of merged annotations (never null) | 合并后的注解列表（不为 null）

    • isAnnotationPresent

      public static boolean isAnnotationPresent(AnnotatedElement element, Class<? extends Annotation> annotationType)
      Checks if an annotation type is present, either directly or as a meta-annotation. 检查注解类型是否存在（直接注解或元注解）
      Parameters:
      element - the annotated element | 被注解元素
      annotationType - the annotation type to check | 要检查的注解类型
      Returns:
      true if present | 如果存在返回 true

    • synthesize

      public static <A extends Annotation> A synthesize(Class<A> annotationType, Map<String,Object> attributes)
      Synthesizes an annotation instance from a map of attributes. 从属性映射合成注解实例

      Creates a dynamic proxy that implements the given annotation type, returning attribute values from the provided map. If an attribute is not in the map, its default value is used.

      创建实现给定注解类型的动态代理，从提供的映射中返回属性值。 如果属性不在映射中，则使用其默认值。

      Type Parameters:
      A - the annotation type | 注解类型
      Parameters:
      annotationType - the annotation type to synthesize | 要合成的注解类型
      attributes - the attribute values | 属性值
      Returns:
      the synthesized annotation instance | 合成的注解实例
      Throws:
      OpenReflectException - if synthesis fails | 如果合成失败