chore: merge main into release [skip ci]

Author: github-actions[bot]

microsphere-java-core/src/main/java/io/microsphere/collection/ListUtils.java

@@ -668,6 +668,22 @@ public static <T> void forEach(List<T> values, Consumer<T> consumer) {
         forEach(values, (i, e) -> consumer.accept(e));
     }
 
+    /**
+     * Adds the specified element to the list if it is not already present.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   List<String> list = new ArrayList<>(Arrays.asList("a", "b"));
+     *   ListUtils.addIfAbsent(list, "c"); // returns true, list = ["a", "b", "c"]
+     *   ListUtils.addIfAbsent(list, "a"); // returns false, list unchanged
+     * }</pre>
+     *
+     * @param values   the list to add the element to
+     * @param newValue the element to add
+     * @param <T>      the type of elements in the list
+     * @return {@code true} if the element was added, {@code false} if already present
+     * @since 1.0.0
+     */
     public static <T> boolean addIfAbsent(List<T> values, T newValue) {
         return values.contains(newValue) ? false : values.add(newValue);
     }

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

@@ -739,12 +739,20 @@ public static List<Annotation> getDeclaredAnnotations(AnnotatedElement annotated
     }
 
     /**
-     * Find all directly declared annotations of the annotated element with filters, not including
-     * meta annotations.
+     * Retrieves all declared annotations from the specified {@link AnnotatedElement}, including those
+     * from its hierarchy, but excluding meta-annotations, applying the given filters.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   List<Annotation> all = AnnotationUtils.findAllDeclaredAnnotations(
+     *       MyClass.class, annotation -> true);
+     *   System.out.println(all); // all declared annotations on MyClass and its superclasses
+     * }</pre>
      *
      * @param annotatedElement    the annotated element
      * @param annotationsToFilter the annotations to filter
      * @return non-null read-only {@link List}
+     * @since 1.0.0
      */
     /**
      * Retrieves all declared annotations from the specified {@link AnnotatedElement}, including those from its hierarchy,
@@ -1220,10 +1228,20 @@ public static Map<String, Object> findAttributesMap(Annotation annotation, Strin
 
     /**
      * Find the attributes map from the specified annotation by the {@link Method attribute method}
+     * filters.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Annotation annotation = ExampleClass.class.getAnnotation(CustomAnnotation.class);
+     *   Map<String, Object> attrs = AnnotationUtils.findAttributesMap(
+     *       annotation, method -> !"toString".equals(method.getName()));
+     *   System.out.println(attrs); // {value=example, count=5}
+     * }</pre>
      *
      * @param annotation         the specified annotation
      * @param attributesToFilter the attribute methods to filter
      * @return non-null read-only {@link Map}
+     * @since 1.0.0
      */
     @Nonnull
     @Immutable

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

@@ -1873,6 +1873,21 @@ public static boolean contains(boolean[] values, boolean value) {
         return false;
     }
 
+    /**
+     * Checks if the specified byte array contains the given value using binary search.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   byte[] sorted = {1, 2, 3, 4, 5};
+     *   boolean found = ArrayUtils.contains(sorted, (byte) 3); // returns true
+     *   boolean notFound = ArrayUtils.contains(sorted, (byte) 6); // returns false
+     * }</pre>
+     *
+     * @param values the sorted byte array to search
+     * @param value  the value to find
+     * @return {@code true} if the array contains the value, {@code false} otherwise
+     * @since 1.0.0
+     */
     public static boolean contains(byte[] values, byte value) {
         return binarySearch(values, value) > -1;
     }

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

@@ -25,6 +25,20 @@
 @Deprecated
 public abstract class BaseUtils {
 
+    /**
+     * The base class for utility classes. Instantiation is not supported.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   // Subclass BaseUtils to create a utility class:
+     *   public class MyUtils extends BaseUtils {
+     *       // utility methods
+     *   }
+     * }</pre>
+     *
+     * @throws IllegalStateException always, as utility classes should not be instantiated
+     * @since 1.0.0
+     */
     protected BaseUtils() throws IllegalStateException {
         throw new IllegalStateException("Not Supported!");
     }

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

@@ -46,6 +46,23 @@ public class CharSequenceComparator implements Comparator<CharSequence> {
     private CharSequenceComparator() {
     }
 
+    /**
+     * Compares two {@link CharSequence} instances lexicographically.
+     * Null values are considered less than non-null values. Two null values are considered equal.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   int result = CharSequenceComparator.INSTANCE.compare("apple", "banana"); // negative
+     *   int equal = CharSequenceComparator.INSTANCE.compare("same", "same");     // 0
+     *   int nullFirst = CharSequenceComparator.INSTANCE.compare(null, "text");   // negative
+     * }</pre>
+     *
+     * @param c1 the first {@link CharSequence} to compare; may be {@code null}
+     * @param c2 the second {@link CharSequence} to compare; may be {@code null}
+     * @return a negative integer, zero, or a positive integer as {@code c1} is less than,
+     *         equal to, or greater than {@code c2}
+     * @since 1.0.0
+     */
     @Override
     public int compare(CharSequence c1, CharSequence c2) {
         String string1 = toString(c1);

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

@@ -216,6 +216,22 @@ public static ClassLoader getDefaultClassLoader() {
         return getDefaultClassLoader(classLoader);
     }
 
+    /**
+     * Returns the given {@link ClassLoader} if it is non-null, otherwise falls back to
+     * the {@linkplain ClassLoader#getSystemClassLoader() system ClassLoader}. A {@code null}
+     * classLoader typically indicates the bootstrap ClassLoader.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   ClassLoader cl = Thread.currentThread().getContextClassLoader();
+     *   ClassLoader effective = ClassLoaderUtils.getDefaultClassLoader(cl);
+     *   // If cl is null (bootstrap), effective will be the system ClassLoader
+     * }</pre>
+     *
+     * @param classLoader the {@link ClassLoader} to use, may be {@code null}
+     * @return the provided classLoader if non-null, or the system ClassLoader otherwise
+     * @since 1.0.0
+     */
     static ClassLoader getDefaultClassLoader(ClassLoader classLoader) {
         // classLoader is null indicates the bootstrap ClassLoader
         return classLoader == null ? getSystemClassLoader() : classLoader;
@@ -546,6 +562,29 @@ public static Class<?> loadClass(@Nullable ClassLoader classLoader, @Nullable St
         return doLoadClass(actualClassLoader, className);
     }
 
+    /**
+     * Loads a {@link Class} with the specified name using the given {@link ClassLoader}.
+     * Returns {@code null} for blank class names. If the class cannot be loaded, this method
+     * attempts to resolve it as a primitive type before returning {@code null}.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   ClassLoader cl = Thread.currentThread().getContextClassLoader();
+     *   Class<?> klass = ClassLoaderUtils.doLoadClass(cl, "java.lang.String");
+     *   System.out.println(klass); // class java.lang.String
+     *
+     *   Class<?> primitive = ClassLoaderUtils.doLoadClass(cl, "int");
+     *   System.out.println(primitive); // int
+     *
+     *   Class<?> missing = ClassLoaderUtils.doLoadClass(cl, "  ");
+     *   System.out.println(missing); // null
+     * }</pre>
+     *
+     * @param classLoader the {@link ClassLoader} used to load the class
+     * @param className   the fully qualified name of the class to load, may be blank
+     * @return the loaded {@link Class}, or {@code null} if the name is blank or the class cannot be found
+     * @since 1.0.0
+     */
     protected static Class<?> doLoadClass(ClassLoader classLoader, String className) {
         if (isBlank(className)) {
             return null;
@@ -1000,6 +1039,24 @@ public static Set<ClassLoader> getInheritableClassLoaders(@Nullable ClassLoader
         return unmodifiableSet(doGetInheritableClassLoaders(actualClassLoader));
     }
 
+    /**
+     * Traverses the parent chain of the given {@link ClassLoader} and collects every
+     * ClassLoader in the hierarchy into a {@link Set}, starting from the provided
+     * classLoader up to (but not including) the bootstrap ClassLoader ({@code null} parent).
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   ClassLoader appCl = ClassLoaderUtils.class.getClassLoader();
+     *   Set<ClassLoader> hierarchy = ClassLoaderUtils.doGetInheritableClassLoaders(appCl);
+     *   // hierarchy contains appCl and its parent (e.g. PlatformClassLoader)
+     *   hierarchy.forEach(cl -> System.out.println(cl));
+     * }</pre>
+     *
+     * @param classLoader the starting {@link ClassLoader}; must not be {@code null}
+     * @return a non-null {@link Set} of ClassLoaders in the inheritance chain
+     * @throws NullPointerException if {@code classLoader} is {@code null}
+     * @since 1.0.0
+     */
     @Nonnull
     static Set<ClassLoader> doGetInheritableClassLoaders(ClassLoader classLoader) throws NullPointerException {
         Set<ClassLoader> classLoadersSet = newLinkedHashSet();
@@ -1752,6 +1809,25 @@ static ClassLoader getCallerClassLoader(int invocationFrame) {
         return classLoader;
     }
 
+    /**
+     * Resolves the effective {@link ClassLoader} to use. Returns the provided classLoader
+     * if it is non-null; otherwise delegates to {@link #getDefaultClassLoader()} to obtain
+     * a suitable default.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   ClassLoader provided = new URLClassLoader(new URL[0]);
+     *   ClassLoader result = ClassLoaderUtils.findClassLoader(provided);
+     *   // result == provided
+     *
+     *   ClassLoader fallback = ClassLoaderUtils.findClassLoader(null);
+     *   // fallback is the thread-context or system ClassLoader
+     * }</pre>
+     *
+     * @param classLoader the {@link ClassLoader} to use, may be {@code null}
+     * @return the provided classLoader if non-null, or the default ClassLoader otherwise
+     * @since 1.0.0
+     */
     @Nullable
     static ClassLoader findClassLoader(@Nullable ClassLoader classLoader) {
         return classLoader == null ? getDefaultClassLoader() : classLoader;
@@ -1775,11 +1851,50 @@ static Class<?> invokeFindLoadedClassMethod(ClassLoader classLoader, String clas
         return loadedClass;
     }
 
+    /**
+     * Logs an error message when the reflective invocation of
+     * {@link ClassLoader#findLoadedClass(String)} fails. The log includes the class name,
+     * the ClassLoader instance, and the current JVM vendor and version for diagnostics.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   try {
+     *       // attempt reflective findLoadedClass invocation
+     *   } catch (Throwable e) {
+     *       ClassLoaderUtils.logOnFindLoadedClassInvocationFailed(
+     *           Thread.currentThread().getContextClassLoader(),
+     *           "com.example.MyClass", e);
+     *   }
+     * }</pre>
+     *
+     * @param classLoader the {@link ClassLoader} on which the invocation was attempted
+     * @param className   the name of the class that was being looked up
+     * @param e           the {@link Throwable} that caused the failure
+     * @since 1.0.0
+     */
     static void logOnFindLoadedClassInvocationFailed(ClassLoader classLoader, String className, Throwable e) {
         logger.error("The findLoadedClass(className : '{}' : String) method of java.lang.ClassLoader[{}] can't be invoked in the current JVM[vendor : {} , version : {}]",
                 className, classLoader, JAVA_VENDOR, JAVA_VERSION, e);
     }
 
+    /**
+     * Builds a cache key by concatenating the class name with the hash code of the given
+     * {@link ClassLoader}. This key uniquely identifies a class within a specific ClassLoader
+     * for caching purposes.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   ClassLoader cl = Thread.currentThread().getContextClassLoader();
+     *   String key = ClassLoaderUtils.buildCacheKey(cl, "com.example.MyClass");
+     *   // key is something like "com.example.MyClass1234567890"
+     *   System.out.println(key);
+     * }</pre>
+     *
+     * @param classLoader the {@link ClassLoader} whose hash code is appended to the key
+     * @param className   the fully qualified class name
+     * @return a cache key string composed of the class name and ClassLoader hash code
+     * @since 1.0.0
+     */
     static String buildCacheKey(ClassLoader classLoader, String className) {
         String cacheKey = className + classLoader.hashCode();
         return cacheKey;
@@ -1829,6 +1944,21 @@ boolean supports(String name) {
                 return true;
             }
 
+            /**
+             * Returns the resource name as-is without any transformation, since
+             * the {@code DEFAULT} resource type applies no normalization.
+             *
+             * <h3>Example Usage</h3>
+             * <pre>{@code
+             *   String name = "META-INF/services/com.example.MyService";
+             *   String normalized = ResourceType.DEFAULT.normalize(name);
+             *   // normalized is "META-INF/services/com.example.MyService"
+             * }</pre>
+             *
+             * @param name the resource name to normalize
+             * @return the same resource name, unchanged
+             * @since 1.0.0
+             */
             @Override
             public String normalize(String name) {
                 return name;
@@ -1853,6 +1983,24 @@ boolean supports(String name) {
                 return endsWith(name, CLASS_EXTENSION);
             }
 
+            /**
+             * Normalizes a class resource name by replacing package-separator dots with
+             * slashes and ensuring the name ends with the {@code .class} extension.
+             * Returns {@code null} if the input is {@code null}.
+             *
+             * <h3>Example Usage</h3>
+             * <pre>{@code
+             *   String normalized = ResourceType.CLASS.normalize("com.example.MyClass.class");
+             *   // normalized is "com/example/MyClass.class"
+             *
+             *   String withoutExt = ResourceType.CLASS.normalize("com.example.MyClass");
+             *   // withoutExt is "com/example/MyClass.class"
+             * }</pre>
+             *
+             * @param name the class resource name to normalize, may be {@code null}
+             * @return the normalized path-style class resource name, or {@code null} if {@code name} is {@code null}
+             * @since 1.0.0
+             */
             @Override
             public String normalize(String name) {
                 if (name == null) {
@@ -1887,6 +2035,24 @@ boolean supports(String name) {
                 return !CLASS.supports(name) && !contains(name, SLASH) && !contains(name, BACK_SLASH);
             }
 
+            /**
+             * Normalizes a package resource name by replacing dots with slashes and
+             * ensuring the result ends with a trailing slash. Returns {@code null}
+             * if the input is {@code null}.
+             *
+             * <h3>Example Usage</h3>
+             * <pre>{@code
+             *   String normalized = ResourceType.PACKAGE.normalize("com.example.mypackage");
+             *   // normalized is "com/example/mypackage/"
+             *
+             *   String alreadySlashed = ResourceType.PACKAGE.normalize("com/example/mypackage/");
+             *   // alreadySlashed is "com/example/mypackage/"
+             * }</pre>
+             *
+             * @param name the dot-separated package name to normalize, may be {@code null}
+             * @return the slash-separated package path ending with a slash, or {@code null} if {@code name} is {@code null}
+             * @since 1.0.0
+             */
             @Override
             String normalize(String name) {
                 if (name == null) {

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

@@ -76,6 +76,23 @@ private static Set<String> initClassPaths() {
         return resolveClassPaths(true, runtimeMXBean::getClassPath);
     }
 
+    /**
+     * Resolves class paths from the given supplier if class path is supported.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Set<String> paths = ClassPathUtils.resolveClassPaths(true, () -> "/lib/a.jar:/lib/b.jar");
+     *   // paths contains ["/lib/a.jar", "/lib/b.jar"]
+     *
+     *   Set<String> empty = ClassPathUtils.resolveClassPaths(false, () -> "");
+     *   // empty set returned when not supported
+     * }</pre>
+     *
+     * @param classPathSupported whether the class path is supported
+     * @param classPathSupplier  the supplier providing the class path string
+     * @return a set of resolved class paths, or an empty set if not supported
+     * @since 1.0.0
+     */
     static Set<String> resolveClassPaths(boolean classPathSupported, Supplier<String> classPathSupplier) {
         if (classPathSupported) {
             return resolveClassPaths(classPathSupplier.get());