chore: merge main into release [skip ci]

Author: github-actions[bot]

.github/workflows/wiki-publish.yml

@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Checkout source repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
 
@@ -36,7 +36,7 @@ jobs:
           echo "Total pages: $(ls wiki-output/*.md | wc -l)"
 
       - name: Checkout wiki repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           repository: ${{ github.repository }}.wiki
           path: wiki-repo

microsphere-java-core/src/main/java/io/microsphere/util/AnnotationUtils.java

@@ -38,6 +38,8 @@
 import java.util.function.Predicate;
 
 import static io.microsphere.collection.CollectionUtils.isEmpty;
+import static io.microsphere.collection.CollectionUtils.isNotEmpty;
+import static io.microsphere.collection.ListUtils.first;
 import static io.microsphere.collection.Lists.ofList;
 import static io.microsphere.collection.MapUtils.immutableEntry;
 import static io.microsphere.collection.MapUtils.toFixedMap;
@@ -533,7 +535,7 @@ public static boolean isMetaAnnotation(Annotation annotation,
      */
     public static boolean isMetaAnnotation(Class<? extends Annotation> annotationType,
                                            Class<? extends Annotation> metaAnnotationType) {
-        if (annotationType == null || metaAnnotationType == null || NATIVE_ANNOTATION_TYPES.contains(annotationType)) {
+        if (annotationType == null || metaAnnotationType == null || isNativeAnnotationType(annotationType)) {
             return false;
         }
 
@@ -1674,7 +1676,173 @@ public static boolean isCallerSensitivePresent() {
         return nonNull(CALLER_SENSITIVE_ANNOTATION_CLASS);
     }
 
+    /**
+     * Checks whether the specified annotation type is a native annotation type.
+     * <p>
+     * Native annotation types are those defined by the Java platform itself, such as
+     * {@link Target}, {@link Retention}, {@link Documented}, {@link Inherited},
+     * {@link Native}, and {@link Repeatable}. These annotations are typically used
+     * to define other annotations rather than being applied directly to business logic.
+     * </p>
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     * // Check standard Java meta-annotations
+     * System.out.println(AnnotationUtils.isNativeAnnotationType(Target.class));      // true
+     * System.out.println(AnnotationUtils.isNativeAnnotationType(Retention.class));   // true
+     * System.out.println(AnnotationUtils.isNativeAnnotationType(Documented.class));  // true
+     * System.out.println(AnnotationUtils.isNativeAnnotationType(Inherited.class));   // true
+     * System.out.println(AnnotationUtils.isNativeAnnotationType(Native.class));      // true
+     * System.out.println(AnnotationUtils.isNativeAnnotationType(Repeatable.class));  // true
+     *
+     * // Check custom user-defined annotations
+     * @Target(ElementType.TYPE)
+     * @Retention(RetentionPolicy.RUNTIME)
+     * public @interface MyCustomAnnotation {}
+     *
+     * System.out.println(AnnotationUtils.isNativeAnnotationType(MyCustomAnnotation.class)); // false
+     *
+     * // Handle null input safely
+     * System.out.println(AnnotationUtils.isNativeAnnotationType(null)); // false
+     * }</pre>
+     *
+     * @param annotationType the annotation type to check
+     * @return {@code true} if the annotation type is a native annotation type; otherwise, {@code false}
+     * @see #NATIVE_ANNOTATION_TYPES
+     */
+    public static boolean isNativeAnnotationType(Class<? extends Annotation> annotationType) {
+        return NATIVE_ANNOTATION_TYPES.contains(annotationType);
+    }
+
+    /**
+     * Finds the meta-annotation of the specified type that is directly or indirectly
+     * present on the given {@link AnnotatedElement}.
+     *
+     * <p>This method searches for a meta-annotation of the specified type, considering both
+     * direct annotations and meta-annotations (annotations on annotations). It traverses the
+     * annotation hierarchy to find the first matching meta-annotation.</p>
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     * @Target(TYPE)
+     * @Retention(RUNTIME)
+     * @Inherited
+     * @Documented
+     * public @interface ServiceMode {
+     * }
+     *
+     * @Inherited
+     * @Target(TYPE)
+     * @Retention(RUNTIME)
+     * @ServiceMode
+     * @interface Monitored {
+     * }
+     *
+     * @Inherited
+     * @Target(TYPE)
+     * @Retention(RUNTIME)
+     * @Monitored
+     * @interface DataAccess {
+     * }
+     *
+     * @DataAccess
+     * class A {
+     * }
+     *
+     * // Find the ServiceMode meta-annotation on class A
+     * ServiceMode serviceMode = AnnotationUtils.findMetaAnnotation(A.class, ServiceMode.class);
+     * System.out.println(serviceMode); // Outputs: @ServiceMode
+     *
+     * // Find the Monitored meta-annotation on class A
+     * Monitored monitored = AnnotationUtils.findMetaAnnotation(A.class, Monitored.class);
+     * System.out.println(monitored); // Outputs: @Monitored
+     * }</pre>
+     *
+     * <p>If either the annotated element or the meta-annotation type is {@code null},
+     * this method will return {@code null}.</p>
+     *
+     * @param annotatedElement the element to search for meta-annotations on
+     * @param metaAnnotationType the type of meta-annotation to look for
+     * @param <A> the type of the meta-annotation to find
+     * @return the first matching meta-annotation of the specified type, or {@code null} if none is found
+     */
+    @Nullable
+    public static <A extends Annotation> A findMetaAnnotation(AnnotatedElement annotatedElement, Class<A> metaAnnotationType) {
+        return first(findMetaAnnotations(annotatedElement, metaAnnotationType));
+    }
+
+    /**
+     * Finds all meta-annotations of the specified type that are directly or indirectly
+     * present on the given {@link AnnotatedElement}.
+     *
+     * <p>This method searches for meta-annotations of the specified type, considering both
+     * direct annotations and meta-annotations (annotations on annotations). It traverses the
+     * annotation hierarchy to find all matching meta-annotations.</p>
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     * @Target(TYPE)
+     * @Retention(RUNTIME)
+     * @Inherited
+     * @Documented
+     * public @interface ServiceMode {
+     * }
+     *
+     * @Inherited
+     * @Target(TYPE)
+     * @Retention(RUNTIME)
+     * @ServiceMode
+     * @interface Monitored {
+     * }
+     *
+     * @Inherited
+     * @Target(TYPE)
+     * @Retention(RUNTIME)
+     * @Monitored
+     * @interface DataAccess {
+     * }
+     *
+     * @DataAccess
+     * class A {
+     * }
+     *
+     * // Find all ServiceMode meta-annotations on class A
+     * List<ServiceMode> serviceModes = AnnotationUtils.findMetaAnnotations(A.class, ServiceMode.class);
+     * System.out.println(serviceModes); // Outputs: [@ServiceMode]
+     *
+     * // Find all Monitored meta-annotations on class A
+     * List<Monitored> monitoredList = AnnotationUtils.findMetaAnnotations(A.class, Monitored.class);
+     * System.out.println(monitoredList); // Outputs: [@Monitored]
+     *
+     * // When no meta-annotation is found
+     * List<ServiceMode> emptyList = AnnotationUtils.findMetaAnnotations(String.class, ServiceMode.class);
+     * System.out.println(emptyList); // Outputs: []
+     * }</pre>
+     *
+     * <p>If either the annotated element or the meta-annotation type is {@code null},
+     * this method will return an empty list.</p>
+     *
+     * @param annotatedElement the element to search for meta-annotations on
+     * @param metaAnnotationType the type of meta-annotation to look for
+     * @param <A> the type of the meta-annotation to find
+     * @return a read-only list of all matching meta-annotations of the specified type, never {@code null}
+     */
+    @Nonnull
+    @Immutable
+    public static <A extends Annotation> List<A> findMetaAnnotations(AnnotatedElement annotatedElement, Class<A> metaAnnotationType) {
+        return (List<A>) findDeclaredAnnotations(annotatedElement, annotation -> {
+            Class<? extends Annotation> annotationType = annotation.annotationType();
+            if (isNativeAnnotationType(annotationType)) {
+                return false;
+            }
+            if (annotationType.equals(metaAnnotationType)) {
+                return true;
+            }
+            return isNotEmpty(findMetaAnnotations(annotationType, metaAnnotationType));
+        });
+    }
+
     private AnnotationUtils() {
     }
 
-}
+}

microsphere-java-core/src/test/java/io/microsphere/util/AnnotationUtilsTest.java

@@ -59,6 +59,8 @@
 import static io.microsphere.util.AnnotationUtils.findAttributeValue;
 import static io.microsphere.util.AnnotationUtils.findAttributesMap;
 import static io.microsphere.util.AnnotationUtils.findDeclaredAnnotations;
+import static io.microsphere.util.AnnotationUtils.findMetaAnnotation;
+import static io.microsphere.util.AnnotationUtils.findMetaAnnotations;
 import static io.microsphere.util.AnnotationUtils.getAllDeclaredAnnotations;
 import static io.microsphere.util.AnnotationUtils.getAttributeValue;
 import static io.microsphere.util.AnnotationUtils.getAttributesMap;
@@ -627,6 +629,39 @@ void testIsCallerSensitivePresent() {
         assertEquals(CALLER_SENSITIVE_ANNOTATION_CLASS != null, isCallerSensitivePresent());
     }
 
+    @Test
+    void testFindMetaAnnotation() {
+        assertNotNull(findMetaAnnotation(A.class, Monitored.class));
+        assertNotNull(findMetaAnnotation(B.class, Monitored.class));
+
+        assertNotNull(findMetaAnnotation(A.class, ServiceMode.class));
+        assertNotNull(findMetaAnnotation(B.class, ServiceMode.class));
+
+        assertNotNull(findMetaAnnotation(A.class, Template.class));
+        assertNotNull(findMetaAnnotation(B.class, Template.class));
+
+        assertNull(findMetaAnnotation(AnnotationUtils.class, Monitored.class));
+        assertNull(findMetaAnnotation(AnnotationUtils.class, ServiceMode.class));
+        assertNull(findMetaAnnotation(AnnotationUtils.class, Template.class));
+    }
+
+    @Test
+    void testFindMetaAnnotations() {
+        assertFindMetaAnnotations(A.class, Monitored.class);
+        assertFindMetaAnnotations(B.class, Monitored.class);
+
+        assertFindMetaAnnotations(A.class, ServiceMode.class);
+        assertFindMetaAnnotations(B.class, ServiceMode.class);
+
+        assertFindMetaAnnotations(A.class, Template.class);
+        assertFindMetaAnnotations(B.class, Template.class);
+    }
+
+    private void assertFindMetaAnnotations(AnnotatedElement annotatedElement, Class<? extends Annotation> metaAnnotationType) {
+        List<? extends Annotation> metaAnnotations = findMetaAnnotations(annotatedElement, metaAnnotationType);
+        assertEquals(1, metaAnnotations.size());
+    }
+
     private void assertFilterAnnotations(Annotation[] annotations) {
         assertEquals(ofList(annotations), filterAnnotations(annotations, annotation -> true));
         assertEquals(ofList(annotations), filterAnnotations(ofList(annotations), annotation -> true));
@@ -639,6 +674,14 @@ private void assertFilterAnnotations(Annotation[] annotations) {
     @Retention(RUNTIME)
     @Inherited
     @Documented
+    public @interface Template {
+    }
+
+    @Target(TYPE)
+    @Retention(RUNTIME)
+    @Inherited
+    @Documented
+    @Template
     public @interface ServiceMode {
     }