Merge pull request #179 from microsphere-projects/dev

Release 0.1.3

Author: mercyblitz

README.md

@@ -1,6 +1,7 @@
 # Microsphere Java Framework
 > The common features used in the other microsphere sub-projects
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/microsphere-projects/microsphere-java)
 [![Maven Build](https://github.com/microsphere-projects/microsphere-java/actions/workflows/maven-build.yml/badge.svg)](https://github.com/microsphere-projects/microsphere-java/actions/workflows/maven-build.yml)
 [![Codecov](https://codecov.io/gh/microsphere-projects/microsphere-java/branch/main/graph/badge.svg)](https://app.codecov.io/gh/microsphere-projects/microsphere-java)
 ![Maven](https://img.shields.io/maven-central/v/io.github.microsphere-projects/microsphere-java.svg)

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

@@ -20,6 +20,7 @@
 import io.microsphere.annotation.ConfigurationProperty;
 import io.microsphere.annotation.processor.model.util.ConfigurationPropertyJSONElementVisitor;
 import io.microsphere.json.JSONArray;
+import io.microsphere.metadata.ConfigurationPropertyJSONGenerator;
 
 import javax.annotation.processing.AbstractProcessor;
 import javax.annotation.processing.Messager;
@@ -31,13 +32,15 @@
 import javax.lang.model.element.Element;
 import javax.lang.model.element.TypeElement;
 import java.util.Iterator;
+import java.util.List;
 import java.util.Set;
 
-import static io.microsphere.annotation.processor.ConfigurationPropertyAnnotationProcessor.CONFIGURATION_PROPERTY_ANNOTATION_CLASS_NAME;
+import static io.microsphere.annotation.processor.model.util.ConfigurationPropertyJSONElementVisitor.CONFIGURATION_PROPERTY_ANNOTATION_CLASS_NAME;
 import static io.microsphere.annotation.processor.util.MessagerUtils.printNote;
 import static io.microsphere.constants.SymbolConstants.COMMA_CHAR;
 import static io.microsphere.constants.SymbolConstants.LEFT_SQUARE_BRACKET_CHAR;
 import static io.microsphere.constants.SymbolConstants.RIGHT_SQUARE_BRACKET_CHAR;
+import static io.microsphere.metadata.ConfigurationPropertyLoader.loadAll;
 import static javax.lang.model.SourceVersion.latestSupported;
 import static javax.tools.StandardLocation.CLASS_OUTPUT;
 
@@ -63,16 +66,16 @@
  *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see ConfigurationProperty
+ * @see ConfigurationPropertyJSONElementVisitor
+ * @see ConfigurationPropertyJSONGenerator
+ * @see ResourceProcessor
+ * @see Messager
+ * @see ProcessingEnvironment
  * @since 1.0.0
  */
 @SupportedAnnotationTypes(value = CONFIGURATION_PROPERTY_ANNOTATION_CLASS_NAME)
 public class ConfigurationPropertyAnnotationProcessor extends AbstractProcessor {
 
-    /**
-     * The {@link Class class} name of {@link ConfigurationProperty}
-     */
-    public static final String CONFIGURATION_PROPERTY_ANNOTATION_CLASS_NAME = "io.microsphere.annotation.ConfigurationProperty";
-
     /**
      * The resource name of {@link ConfigurationProperty} metadata
      */
@@ -84,12 +87,15 @@ public class ConfigurationPropertyAnnotationProcessor extends AbstractProcessor
 
     private ResourceProcessor classPathResourceProcessor;
 
+    private ConfigurationPropertyJSONElementVisitor jsonElementVisitor;
+
     @Override
     public synchronized void init(ProcessingEnvironment processingEnv) {
         super.init(processingEnv);
         this.messager = processingEnv.getMessager();
         this.jsonBuilder = new StringBuilder();
         this.classPathResourceProcessor = new ResourceProcessor(processingEnv, CLASS_OUTPUT);
+        this.jsonElementVisitor = new ConfigurationPropertyJSONElementVisitor(processingEnv);
     }
 
     @Override
@@ -105,15 +111,17 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
     private void resolveMetadata(RoundEnvironment roundEnv) {
         Set<? extends Element> elements = roundEnv.getRootElements();
         if (!elements.isEmpty()) {
-            ConfigurationPropertyJSONElementVisitor visitor = new ConfigurationPropertyJSONElementVisitor(processingEnv);
 
             Iterator<? extends Element> iterator = elements.iterator();
             jsonBuilder.append(LEFT_SQUARE_BRACKET_CHAR);
             while (iterator.hasNext()) {
                 Element element = iterator.next();
-                element.accept(visitor, jsonBuilder);
+                element.accept(jsonElementVisitor, jsonBuilder);
             }
 
+            // append the JSON content generated by ConfigurationPropertyGenerator SPI
+            appendGeneratedConfigurationPropertyJSON(jsonBuilder);
+
             int lastIndex = jsonBuilder.length() - 1;
             if (COMMA_CHAR == jsonBuilder.charAt(lastIndex)) {
                 jsonBuilder.setCharAt(lastIndex, RIGHT_SQUARE_BRACKET_CHAR);
@@ -123,6 +131,21 @@ private void resolveMetadata(RoundEnvironment roundEnv) {
         }
     }
 
+    private void appendGeneratedConfigurationPropertyJSON(StringBuilder jsonBuilder) {
+        List<io.microsphere.beans.ConfigurationProperty> configurationProperties = loadAll();
+        int size = configurationProperties.size();
+        for (int i = 0; i < size; i++) {
+            appendGeneratedConfigurationPropertyJSON(jsonBuilder, configurationProperties.get(i));
+        }
+    }
+
+    private void appendGeneratedConfigurationPropertyJSON(StringBuilder jsonBuilder, io.microsphere.beans.ConfigurationProperty configurationProperty) {
+        ConfigurationPropertyJSONGenerator generator = this.jsonElementVisitor.getGenerator();
+        String json = generator.generate(configurationProperty);
+        jsonBuilder.append(json)
+                .append(COMMA_CHAR);
+    }
+
     private void writeMetadata() {
         classPathResourceProcessor.processInResourceWriter(CONFIGURATION_PROPERTY_METADATA_RESOURCE_NAME, writer -> {
             JSONArray jsonArray = new JSONArray(jsonBuilder.toString());

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

@@ -36,6 +36,36 @@
  * <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>
  *
+ * <h3>Example Usage</h3>
+ * <pre>
+ * // Creating an instance of FilerProcessor
+ * FilerProcessor filerProcessor = new FilerProcessor(processingEnv);
+ *
+ * // Using processInFiler to create a source file
+ * filerProcessor.processInFiler(filer -> {
+ *     JavaFileObject file = filer.createSourceFile("com.example.GeneratedClass");
+ *     try (Writer writer = file.openWriter()) {
+ *         writer.write("// Auto-generated class\npublic class GeneratedClass {}");
+ *     }
+ *     return null;
+ * });
+ *
+ * // Using processInFiler with a custom exception handler
+ * filerProcessor.processInFiler(
+ *     filer -> {
+ *         JavaFileObject file = filer.createSourceFile("com.example.AnotherGeneratedClass");
+ *         try (Writer writer = file.openWriter()) {
+ *             writer.write("// Auto-generated class\npublic class AnotherGeneratedClass {}");
+ *         }
+ *         return null;
+ *     },
+ *     (filer, e) -> {
+ *         System.err.println("Failed to generate file: " + e.getMessage());
+ *         return null;
+ *     }
+ * );
+ * </pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see #processInFiler(ThrowableFunction)
  * @see #processInFiler(ThrowableFunction, BiFunction)

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

@@ -55,6 +55,26 @@
  * - Manipulating resources via OutputStream or Writer
  * - Reading or modifying the content directly as CharSequence</p>
  *
+ * <h3>Example Usage</h3>
+ * <pre>
+ * // Creating an instance of ResourceProcessor
+ * ResourceProcessor resourceProcessor = new ResourceProcessor(processingEnv, StandardLocation.SOURCE_OUTPUT);
+ *
+ * // Reading content from a resource
+ * Optional<String> content = resourceProcessor.processInResourceContent("example.txt", CharBuffer::toString);
+ *
+ * // Writing to a resource
+ * resourceProcessor.processInResourceWriter("output.txt", writer -> {
+ *     writer.write("Hello, World!");
+ * });
+ *
+ * // Processing an InputStream
+ * resourceProcessor.processInResourceInputStream("data.bin", inputStream -> {
+ *     // Process binary data
+ *     return null;
+ * });
+ * </pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see FilerProcessor
  * @since 1.0.0

microsphere-annotation-processor/src/main/java/io/microsphere/annotation/processor/model/element/StringAnnotationValue.java

@@ -17,6 +17,8 @@
 
 package io.microsphere.annotation.processor.model.element;
 
+import io.microsphere.annotation.Immutable;
+
 import javax.lang.model.element.AnnotationValue;
 import javax.lang.model.element.AnnotationValueVisitor;
 
@@ -27,6 +29,7 @@
  * @see AnnotationValue
  * @since 1.0.0
  */
+@Immutable
 public class StringAnnotationValue implements AnnotationValue {
 
     private final String value;

microsphere-annotation-processor/src/main/java/io/microsphere/annotation/processor/model/util/AnnotatedElementJSONElementVisitor.java

@@ -35,7 +35,48 @@
 import static io.microsphere.util.Assert.assertNotNull;
 
 /**
- * {@link ElementVisitor} to assemble JSON on the annotated elements based on the specified {@link Annotation annotation}.
+ * An abstract implementation of {@link ElementVisitor} that generates JSON content for elements
+ * annotated with a specific annotation.
+ *
+ * <p>This class extends {@link JSONElementVisitor}, providing functionality to filter and process
+ * only those elements that are annotated with the specified annotation. It leverages the annotation
+ * processing environment to gather information about the annotated elements and constructs JSON
+ * representations accordingly.</p>
+ *
+ * <h3>Example Usage</h3>
+ *
+ * <p>Suppose you have a custom annotation:</p>
+ *
+ * <pre>{@code
+ * @Retention(RetentionPolicy.SOURCE)
+ * @Target(ElementType.TYPE)
+ * public @interface MyAnnotation {
+ * }
+ * }</pre>
+ *
+ * <p>You can create a concrete implementation of this class to process elements annotated with
+ * {@code MyAnnotation}:</p>
+ *
+ * <pre>{@code
+ * public class MyAnnotatedElementVisitor extends AnnotatedElementJSONElementVisitor {
+ *
+ *     public MyAnnotatedElementVisitor(ProcessingEnvironment processingEnv, String annotationClassName) {
+ *         super(processingEnv, annotationClassName);
+ *     }
+ *
+ *     @Override
+ *     protected boolean doVisitType(TypeElement e, StringBuilder jsonBuilder) {
+ *         // Custom logic to generate JSON for the type element
+ *         jsonBuilder.append("{");
+ *         jsonBuilder.append("\"name\":").append("\"").append(e.getSimpleName()).append("\"");
+ *         jsonBuilder.append("}");
+ *         return true;
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p>The above example demonstrates how to extend this class to create a visitor that processes
+ * type elements annotated with a custom annotation and generates JSON output for them.</p>
  *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see JSONElementVisitor