Merge pull request #166 from microsphere-projects/dev

Release 0.1.2

Author: mercyblitz

microsphere-annotation-processor/src/main/java/io/microsphere/annotation/processor/ConfigurationPropertyAnnotationProcessor.java

@@ -44,6 +44,23 @@
 /**
  * The {@link Processor} for the {@link ConfigurationProperty} annotation
  *
+ * <p>This class processes the {@link ConfigurationProperty} annotations during the compilation phase,
+ * collects metadata about annotated elements, and generates a JSON metadata file that contains
+ * configuration property information.
+ *
+ * <ul>
+ *     <li>{@link #init(ProcessingEnvironment)} initializes required utilities such as the Messager and ResourceProcessor.</li>
+ *     <li>{@link #process(Set, RoundEnvironment)} handles each processing round:
+ *         <ul>
+ *             <li>During normal rounds, it resolves metadata from annotated elements.</li>
+ *             <li>On the final round, it writes collected metadata into a resource file.</li>
+ *         </ul>
+ *     </li>
+ *     <li>{@link #resolveMetadata(RoundEnvironment)} traverses all root elements to extract configuration property metadata.</li>
+ *     <li>{@link #writeMetadata()} writes the generated metadata into a JSON file under
+ *         {@value #CONFIGURATION_PROPERTY_METADATA_RESOURCE_NAME} using a writer.</li>
+ * </ul>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see ConfigurationProperty
  * @since 1.0.0

microsphere-annotation-processor/src/main/java/io/microsphere/annotation/processor/FilerProcessor.java

@@ -28,11 +28,17 @@
 import static io.microsphere.reflect.FieldUtils.getFieldValue;
 
 /**
- * The {@link Filer} Processor
+ * A processor class that provides safe and exception-handled operations for interacting with the {@link Filer}
+ * in an annotation processing environment. This class wraps calls to the underlying {@link Filer} instance
+ * obtained from the provided {@link ProcessingEnvironment}, ensuring robust resource handling and simplifying
+ * error management through functional interfaces.
+ *
+ * <p>It supports executing operations on the {@link Filer} using a callback model, allowing custom logic to be
+ * applied while handling exceptions gracefully using provided handlers.</p>
  *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
- * @see ProcessingEnvironment
- * @see Filer
+ * @see #processInFiler(ThrowableFunction)
+ * @see #processInFiler(ThrowableFunction, BiFunction)
  * @since 1.0.0
  */
 public class FilerProcessor {

microsphere-annotation-processor/src/main/java/io/microsphere/annotation/processor/ResourceProcessor.java

@@ -41,10 +41,22 @@
 import static java.util.Optional.of;
 
 /**
- * The {@link ProcessingEnvironment} Processor
+ * A processor class that provides a comprehensive and exception-safe mechanism for handling resources during annotation processing.
+ * It extends the capabilities of the {@link FilerProcessor} to manage both reading from and writing to resources using various I/O operations.
+ * This class abstracts away boilerplate code required for resource management, including opening/closing streams, handling exceptions,
+ * and caching accessed file objects to avoid redundant operations.
+ *
+ * <p>It supports functional-style interaction with resources through callback interfaces like {@link ThrowableFunction},
+ * allowing custom logic to be applied on resources such as reading content, writing data, or manipulating streams in a type-safe manner.</p>
+ *
+ * <p>The class also maintains an internal cache of accessed file objects to optimize performance by avoiding repeated calls to locate or create them.
+ * It handles both input (read) and output (write) operations seamlessly, offering convenience methods for common use cases like:
+ * - Processing resources via InputStream or Reader
+ * - Manipulating resources via OutputStream or Writer
+ * - Reading or modifying the content directly as CharSequence</p>
  *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
- * @see ProcessingEnvironment
+ * @see FilerProcessor
  * @since 1.0.0
  */
 public class ResourceProcessor {

microsphere-annotation-processor/src/main/java/io/microsphere/annotation/processor/util/AnnotationUtils.java

@@ -36,14 +36,41 @@
  */
 public interface ClassUtils extends Utils {
 
+    /**
+     * Returns the fully qualified name of the class represented by the given {@link TypeMirror}.
+     *
+     * @param type the type mirror to get the class name from
+     * @return the fully qualified class name
+     */
     static String getClassName(TypeMirror type) {
         return ofTypeElement(type).getQualifiedName().toString();
     }
 
+
+    /**
+     * Loads the class represented by the given {@link TypeMirror}.
+     *
+     * <p>This method attempts to resolve the class using the fully qualified name derived from the type mirror.
+     * If the class cannot be resolved directly, an attempt is made to resolve it as a nested or inner class by
+     * replacing the last dot ({@code .}) with a dollar sign ({@code $}).
+     *
+     * @param type the type mirror representing the class to load
+     * @return the resolved {@link Class}, or {@code null} if the class cannot be found
+     */
     static Class loadClass(TypeMirror type) {
         return loadClass(getClassName(type));
     }
 
+    /**
+     * Loads the class represented by the given fully qualified class name.
+     *
+     * <p>This method attempts to resolve the class using the provided class name and the class loader
+     * obtained from {@link ClassUtils}. If the class is not found, an attempt is made to resolve it
+     * as a nested or inner class by replacing the last dot ({@code .}) with a dollar sign ({@code $}).
+     *
+     * @param className the fully qualified name of the class to load
+     * @return the resolved {@link Class}, or {@code null} if the class cannot be found
+     */
     static Class loadClass(String className) {
         ClassLoader classLoader = getClassLoader(ClassUtils.class);
         Class<?> klass = resolveClass(className, classLoader);

microsphere-annotation-processor/src/main/java/io/microsphere/annotation/processor/util/ClassUtils.java

@@ -245,14 +245,34 @@ static boolean matchesElementType(Element element, ElementType... elementTypes)
     }
 
 
+    /**
+     * Checks whether the specified {@link Element} has the specified {@link ElementKind}.
+     *
+     * @param member the {@link Element} to check, may be {@code null}
+     * @param kind   the {@link ElementKind} to match, may be {@code null}
+     * @return {@code true} if the element is not null and its kind matches the specified kind; otherwise, {@code false}
+     */
     static boolean matchesElementKind(Element member, ElementKind kind) {
         return member == null || kind == null ? false : kind.equals(member.getKind());
     }
 
+    /**
+     * Checks whether the specified {@link Element} is public and non-static.
+     *
+     * @param member the {@link Element} to check, may be {@code null}
+     * @return {@code true} if the element is public and not static; otherwise, {@code false}
+     */
     static boolean isPublicNonStatic(Element member) {
         return hasModifiers(member, PUBLIC) && !hasModifiers(member, STATIC);
     }
 
+    /**
+     * Checks whether the specified {@link Element} has all of the specified {@link Modifier}s.
+     *
+     * @param member   the {@link Element} to check, may be {@code null}
+     * @param modifiers the array of {@link Modifier}s to match, may be {@code null}
+     * @return {@code true} if the element is not null and contains all specified modifiers; otherwise, {@code false}
+     */
     static boolean hasModifiers(Element member, Modifier... modifiers) {
         if (member == null || modifiers == null) {
             return false;
@@ -266,6 +286,17 @@ static boolean hasModifiers(Element member, Modifier... modifiers) {
         return true;
     }
 
+    /**
+     * Filters the provided list of {@link Element} objects based on the given array of {@link Predicate} conditions.
+     *
+     * <p>If the input list of elements is empty or the array of predicates is null, an empty list is returned.</p>
+     *
+     * @param elements          The list of elements to be filtered, may be {@code null}
+     * @param elementPredicates An array of predicates used to filter the elements, may be {@code null}
+     * @param <E>               The type of the elements, which must be a subclass of {@link Element}
+     * @return A filtered list of elements that match all the provided predicates. Returns an empty list if no elements match,
+     *         or if the input list or predicate array is invalid.
+     */
     static <E extends Element> List<E> filterElements(List<E> elements, Predicate<? super E>... elementPredicates) {
         if (isEmpty(elements) || elementPredicates == null) {
             return emptyList();
@@ -277,15 +308,52 @@ static <E extends Element> List<E> filterElements(List<E> elements, Predicate<?
         return elements.isEmpty() ? emptyList() : elements;
     }
 
+    /**
+     * Checks whether the parameter types of the given {@link ExecutableElement} match the specified {@link Type types}.
+     *
+     * <p>
+     * If either the executable element or the parameter types array is {@code null}, this method returns {@code false}.
+     * Otherwise, it compares the fully qualified type names of the parameters.
+     * </p>
+     *
+     * @param executableElement the executable element whose parameters are to be checked, may be {@code null}
+     * @param parameterTypes    the expected parameter types, may be {@code null}
+     * @return {@code true} if the parameter types match; {@code false} otherwise
+     */
     static boolean matchParameterTypes(ExecutableElement executableElement, Type... parameterTypes) {
         return executableElement == null || parameterTypes == null ? false :
                 matchParameterTypeNames(executableElement.getParameters(), getTypeNames(parameterTypes));
     }
 
+    /**
+     * Checks whether the parameter types of the given list of {@link VariableElement} parameters match the specified {@link Type types}.
+     *
+     * <p>
+     * If either the parameters list or the parameter types array is {@code null}, this method returns {@code false}.
+     * Otherwise, it compares the fully qualified type names of the parameters.
+     * </p>
+     *
+     * @param parameters       the list of variable elements representing the parameters, may be {@code null}
+     * @param parameterTypes   the expected parameter types, may be {@code null}
+     * @return {@code true} if the parameter types match; {@code false} otherwise
+     */
     static boolean matchParameterTypes(List<? extends VariableElement> parameters, Type... parameterTypes) {
         return parameters == null || parameterTypes == null ? false : matchParameterTypeNames(parameters, getTypeNames(parameterTypes));
     }
 
+    /**
+     * Checks whether the parameter types of the given list of {@link VariableElement} parameters match the specified type names.
+     *
+     * <p>
+     * If either the parameters list or the parameter type names array is {@code null}, this method returns {@code false}.
+     * It also returns {@code false} if the sizes of the two arrays do not match.
+     * Otherwise, it compares each parameter's type with the corresponding type name using {@link TypeUtils#isSameType(Element, CharSequence)}.
+     * </p>
+     *
+     * @param parameters         the list of variable elements representing the parameters, may be {@code null}
+     * @param parameterTypeNames the expected fully qualified type names of the parameters, may be {@code null}
+     * @return {@code true} if all parameter types match their corresponding type names; {@code false} otherwise
+     */
     static boolean matchParameterTypeNames(List<? extends VariableElement> parameters, CharSequence... parameterTypeNames) {
         if (parameters == null || parameterTypeNames == null) {
             return false;