Package org.miaixz.bus.core.annotation.resolve

Class AnnotatedElements

java.lang.Object
org.miaixz.bus.core.annotation.resolve.AnnotatedElements
public class AnnotatedElements extends Object

AnnotatedElement工具类，提供对层级结构中AnnotatedElement上注解及元注解的访问支持， 并提供诸如基于Alias的属性别名、基于父子注解间的属性值覆盖等特殊的属性映射机制支持。

搜索层级结构

参考 Spring 中AnnotatedElementUtils， 工具类提供get以及find两种语义的搜索：

  • get：表示搜索范围仅限于指定的AnnotatedElement本身；
  • find：表示搜索范围除了指定的AnnotatedElement本身外， 若AnnotatedElement是类，则还会搜索其所有关联的父类和父接口； 若AnnotatedElement是方法，则还会搜索其声明类关联的所有父类和父接口中，与该方法具有相同方法签名的方法对象；
eg: 若类A分别有父类和父接口B、C， 则通过getXXX方法将只能获得A上的注解， 而通过findXXX方法将能获得A、B、C上的注解。

搜索元注解

工具类支持搜索注解的元注解。在所有格式为getXXX或findXXX的静态方法中， 若不带有directly关键字，则该方法支持搜索元注解，否则不支持搜索元注解。 eg: 若类A分别有父类和父接口B、C，上面分别有注解X与其元注解Y， 则此时基于A有：

  • getDirectlyXXX：能够获得A上的注解X；
  • getXXX：能够获得A上的注解X及元注解Y；
  • findDirectlyXXX：能够分别获得A、B、C上的注解X；
  • findXXX：能够分别获得A、B、C上的注解X及元注解Y；
注意：在当前实例中将无视Inherited的效果，即通过directly方法将无法获得父类上带有Inherited的注解。

注解属性映射

工具类支持注解对象属性上的一些属性映射机制，即当注解被扫描时， 将根据一些属性映射机制“解析”为其他类型的属性，这里支持的机制包括：

  • 基于Alias的属性别名：若注解属性通过Alias互相关联，则对其中任意属性赋值，则等同于对所有关联属性赋值； eg： 
    
          // set aliased attributes
         @interface FooAnnotation {
             @Alias("alias")
              default String value() default "";
             @Alias("value")
              default String alias() default "";
          }
         @FooAnnotation("foo")
          class Foo { }

          // get resolved annotation
          FooAnnotation annotation = getResolvedAnnotation(Foo.class, FooAnnotation.class);
          annotation.value(); // = "foo"
          annotation.alias(); // = "foo"
         }
  • 基于父子注解的属性覆写：若子注解中存在属性，与其元注解的属性名称、类型皆相同，则子注解的属性值将会覆写其元注解的属性值， 若被覆写的属性值存在关联别名，则关联别名也会被一并覆写。 eg： 
    
         @interface Meta {
              default String value() default "";
          }
         @Meta("meta")
          @interface Root {
              default String value() default ""; // overwrite for @Meta.value
          }
         @Root("foo")
          class Foo { }

          // get resolved annotation
          Meta meta = getResolvedAnnotation(Foo.class, Meta.class);
          meta.value(); // = "foo"
          Root root = getResolvedAnnotation(Foo.class, Root.class);
          root.value(); // = "foo"

可重复注解支持

工具类中格式为findAllXXX或getAllXXX格式的方法， 支持获得AnnotatedElement上的可重复注解。 此处的可重复注解定义包括两方面：

  • 若AnnotatedElement存在直接声明的注解，该注解有且仅有一个value属性， 该属性类型为注解数组，且数组中注解被Repeatable注解， 则认为被包括的注解为可重复注解； eg: A上存在注解X，该注解是一个容器注解，内部包含可重复注解Y， 解析X后，得到注解X与它包含的可重复注解Y；
  • 若AnnotatedElement存在直接声明的注解，该注解与其他根注解皆有相同的元注解， 则获得元注解时，可以获得多个该相同的元注解。 eg: A上存在注解X、Y，两者皆有元注解Z， 则通过AnnotatedElement可以获得两个Z

缓存

为了避免注解以及AnnotatedElement层级结构解析过程中的大量反射调用， 工具类为AnnotatedElement及其元注解信息进行了缓存。 缓存功能默认基于WeakConcurrentMap实现，会在gc时自动回收部分缓存数据。 但是若有必要，也可以调用clearCaches()方法主动清空缓存。

Since:
Java 17+
Author:
Kimi Liu
See Also:

  • Constructor Details

    • AnnotatedElements

      public AnnotatedElements()

  • Method Details

    • isAnnotated

      public static boolean isAnnotated(AnnotatedElement element, Class<? extends Annotation> annotationType)
      在element所处层级结构的所有AnnotatedElement上，是否存在该类型的注解或元注解
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      是否

    • findAnnotation

      public static <T extends Annotation> T findAnnotation(AnnotatedElement element, Class<T> annotationType)
      从element所处层级结构的所有AnnotatedElement上，获取该类型的注解或元注解
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • findAllAnnotations

      public static <T extends Annotation> T[] findAllAnnotations(AnnotatedElement element, Class<T> annotationType)
      从element所处层级结构的所有AnnotatedElement上直接声明的注解、 这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • findAnnotations

      public static Annotation[] findAnnotations(AnnotatedElement element)
      从element所处层级结构的所有AnnotatedElement上，获取所有的注解或元注解
      Parameters:
      element - AnnotatedElement
      Returns:
      注解对象

    • findResolvedAnnotation

      public static <T extends Annotation> T findResolvedAnnotation(AnnotatedElement element, Class<T> annotationType)
      从element所处层级结构的所有AnnotatedElement上，获取所有的注解或元注解。 得到的注解支持基于Alias的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • findResolvedAnnotations

      public static Annotation[] findResolvedAnnotations(AnnotatedElement element)
      从element所处层级结构的所有AnnotatedElement上，获取所有的注解或元注解。 得到的注解支持基于Alias的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。
      Parameters:
      element - AnnotatedElement
      Returns:
      注解对象

    • findAllResolvedAnnotations

      public static <T extends Annotation> T[] findAllResolvedAnnotations(AnnotatedElement element, Class<T> annotationType)
      从element所处层级结构的所有AnnotatedElement上直接声明的注解、 这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解。 得到的注解支持基于Alias的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • findDirectlyAnnotation

      public static <T extends Annotation> T findDirectlyAnnotation(AnnotatedElement element, Class<T> annotationType)
      从element所处层级结构的所有AnnotatedElement上获取该类型的注解
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • findAllDirectlyAnnotations

      public static <T extends Annotation> T[] findAllDirectlyAnnotations(AnnotatedElement element, Class<T> annotationType)
      从element上直接声明的注解、这些注解包含的可重复注解， 以及上述所有注解的元注解中获取指定类型注解。
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • findDirectlyAnnotations

      public static Annotation[] findDirectlyAnnotations(AnnotatedElement element)
      从element所处层级结构的所有AnnotatedElement上获取所有的注解
      Parameters:
      element - AnnotatedElement
      Returns:
      注解对象

    • findDirectlyResolvedAnnotation

      public static <T extends Annotation> T findDirectlyResolvedAnnotation(AnnotatedElement element, Class<T> annotationType)
      从element所处层级结构的所有AnnotatedElement上，获取所有的注解。 得到的注解支持基于Alias的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • findDirectlyResolvedAnnotations

      public static Annotation[] findDirectlyResolvedAnnotations(AnnotatedElement element)
      从element所处层级结构的所有AnnotatedElement上获取所有的注解。 得到的注解支持基于Alias的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。
      Parameters:
      element - AnnotatedElement
      Returns:
      注解对象

    • findAllDirectlyResolvedAnnotations

      public static <T extends Annotation> T[] findAllDirectlyResolvedAnnotations(AnnotatedElement element, Class<T> annotationType)
      从element所处层级结构的所有AnnotatedElement上直接声明的注解、 这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解。 得到的注解支持基于Alias的别名、及子注解对元注解中同名同类型属性进行覆写的特殊机制。
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • isAnnotationPresent

      public static boolean isAnnotationPresent(AnnotatedElement element, Class<? extends Annotation> annotationType)
      在element上，是否存在该类型的注解或元注解
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      是否

    • getAnnotation

      public static <T extends Annotation> T getAnnotation(AnnotatedElement element, Class<T> annotationType)
      从element上，获取该类型的注解或元注解
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • getAnnotations

      public static Annotation[] getAnnotations(AnnotatedElement element)
      从element上，获取所有的注解或元注解
      Parameters:
      element - AnnotatedElement
      Returns:
      注解对象

    • getAllAnnotations

      public static <T extends Annotation> T[] getAllAnnotations(AnnotatedElement element, Class<T> annotationType)
      从element上直接声明的注解、这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • getResolvedAnnotation

      public static <T extends Annotation> T getResolvedAnnotation(AnnotatedElement element, Class<T> annotationType)
      从element上，获取所有的注解或元注解。 得到的注解支持基于Alias的别名机制。
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • getResolvedAnnotations

      public static Annotation[] getResolvedAnnotations(AnnotatedElement element)
      从element上，获取所有的注解或元注解。 得到的注解支持基于Alias的别名机制。
      Parameters:
      element - AnnotatedElement
      Returns:
      注解对象

    • getAllResolvedAnnotations

      public static <T extends Annotation> T[] getAllResolvedAnnotations(AnnotatedElement element, Class<T> annotationType)
      从element上直接声明的注解、这些注解包含的可重复注解，以及上述所有注解的元注解中获取指定类型注解 得到的注解支持基于Alias的别名机制。
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • getDirectlyAnnotation

      public static <T extends Annotation> T getDirectlyAnnotation(AnnotatedElement element, Class<T> annotationType)
      从element上获取该类型的注解
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • getAllDirectlyAnnotations

      public static <T extends Annotation> T[] getAllDirectlyAnnotations(AnnotatedElement element, Class<T> annotationType)
      从element上直接声明的注解、这些注解包含的可重复注解中获取指定类型注解
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • getDirectlyAnnotations

      public static Annotation[] getDirectlyAnnotations(AnnotatedElement element)
      从element上获取所有的注解
      Parameters:
      element - AnnotatedElement
      Returns:
      注解对象

    • getDirectlyResolvedAnnotation

      public static <T extends Annotation> T getDirectlyResolvedAnnotation(AnnotatedElement element, Class<T> annotationType)
      从element上，获取所有的注解。 得到的注解支持基于Alias的别名机制。
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • getDirectlyResolvedAnnotations

      public static Annotation[] getDirectlyResolvedAnnotations(AnnotatedElement element)
      从element上，获取所有的注解。 得到的注解支持基于Alias的别名机制。
      Parameters:
      element - AnnotatedElement
      Returns:
      注解对象

    • getAllDirectlyResolvedAnnotations

      public static <T extends Annotation> T[] getAllDirectlyResolvedAnnotations(AnnotatedElement element, Class<T> annotationType)
      从element上直接声明的注解、这些注解包含的可重复注解中获取指定类型注解
      Type Parameters:
      T - 注解类型
      Parameters:
      element - AnnotatedElement
      annotationType - 注解类型
      Returns:
      注解对象

    • toHierarchyMetaElement

      public static AnnotatedElement toHierarchyMetaElement(AnnotatedElement element, boolean resolved)
      扫描element所处层级结构中的AnnotatedElement， 并将其全部转为MetaAnnotatedElement后， 再把所有对象合并为HierarchicalAnnotatedElements。 得到的对象可访问element所处层级结构中所有AnnotatedElement上的注解及元注解。
      Parameters:
      element - 元素
      resolved - 是否解析注解属性，若为true则获得的注解将支持属性别名以及属性覆盖机制
      Returns:
      HierarchicalAnnotatedElements实例
      See Also:
      • getMetaElementCache(AnnotatedElement)
      • getResolvedMetaElementCache(AnnotatedElement)

    • toHierarchyRepeatableMetaElement

      public static AnnotatedElement toHierarchyRepeatableMetaElement(AnnotatedElement element, boolean resolved)

      扫描element所处层级结构中的AnnotatedElement， 并将其全部转为RepeatableMetaAnnotatedElement后， 再把所有对象合并为HierarchicalAnnotatedElements。 得到的对象可访问element所处层级结构中所有AnnotatedElement上的直接声明的注解， 这些注解包含的可重复注解，以及上述注解的所有元注解。

      Parameters:
      element - 元素
      resolved - 是否解析注解属性，若为true则获得的注解将支持属性别名以及属性覆盖机制
      Returns:
      HierarchicalAnnotatedElements实例
      See Also:
      • getRepeatableMetaElementCache(AnnotatedElement)
      • getResolvedRepeatableMetaElementCache(AnnotatedElement)

    • toHierarchyElement

      public static AnnotatedElement toHierarchyElement(AnnotatedElement element)

      扫描element所处层级结构中的AnnotatedElement， 再把所有对象合并为HierarchicalAnnotatedElements 得到的对象可访问element所处层级结构中所有AnnotatedElement上的注解。

      Parameters:
      element - 元素
      Returns:
      AnnotatedElement实例

    • toMetaElement

      public static AnnotatedElement toMetaElement(AnnotatedElement element, boolean resolved)
      将AnnotatedElement转为MetaAnnotatedElement， 得到的对象可访问element上所有的注解及元注解。
      Parameters:
      element - 元素
      resolved - 是否解析注解属性，若为true则获得的注解将支持属性别名以及属性覆盖机制
      Returns:
      AnnotatedElement实例
      See Also:
      • getMetaElementCache(AnnotatedElement)
      • getResolvedMetaElementCache(AnnotatedElement)

    • toRepeatableMetaElement

      public static AnnotatedElement toRepeatableMetaElement(AnnotatedElement element, boolean resolved)
      将AnnotatedElement转为RepeatableMetaAnnotatedElement， 得到的对象可访问AnnotatedElement上的直接声明的注解，这些注解包含的可重复注解，以及上述注解的所有元注解。
      Parameters:
      element - 元素
      resolved - 是否解析注解属性，若为true则获得的注解将支持属性别名以及属性覆盖机制
      Returns:
      AnnotatedElement实例
      See Also:
      • getMetaElementCache(AnnotatedElement)
      • getResolvedMetaElementCache(AnnotatedElement)

    • toRepeatableMetaElement

      public static AnnotatedElement toRepeatableMetaElement(AnnotatedElement element, RepeatableAnnotationCollector collector, boolean resolved)

      将AnnotatedElement转为RepeatableMetaAnnotatedElement， 得到的对象可访问AnnotatedElement上的直接声明的注解， 通过collector从这些注解获得的可重复注解，以及上述注解的所有元注解。 注意：方法将不会通过缓存结果，因此每次调用都需要重新通过反射并获得相关注解。

      Parameters:
      element - 元素
      collector - 可重复注解收集器，为null时等同于RepeatableAnnotationCollector.none()
      resolved - 是否解析注解属性，若为true则获得的注解将支持属性别名以及属性覆盖机制
      Returns:
      AnnotatedElement实例

    • asElement

      public static AnnotatedElement asElement(Annotation... annotations)
      将一组注解中的非null注解对象合并为一个AnnotatedElement
      Parameters:
      annotations - 注解
      Returns:
      AnnotatedElement实例
      See Also:
      • AnnotatedElements.ConstantElement

    • emptyElement

      public static AnnotatedElement emptyElement()
      获取一个不包含任何注解的AnnotatedElement
      Returns:
      AnnotatedElement实例
      See Also:
      • AnnotatedElements.EmptyElement

    • clearCaches

      public static void clearCaches()
      清空相关缓存，包括：
      See Also: