[I] [Enhancement] Add composable annotations support [fesod]

["bengbengbalabalabeng (via GitHub)" <gi...@apache.org>]

bengbengbalabalabeng opened a new issue, #918:
URL: https://github.com/apache/fesod/issues/918

   ### Search before asking
   
   - [x] I searched in the [issues](https://github.com/apache/fesod/issues) and found nothing similar.
   
   
   ### Motivation
   
   This proposal aims to introduce Composable Annotation Support for Fesod-Sheet's Java Model mode, allowing users to create custom, reusable annotation combinations (presets) that group multiple built-in Fesod annotations into a single meta-annotation. This dramatically reduces boilerplate when repetitive style/format configurations are applied across many model classes.
   
   ### Solution
   
   ### Content
   
   Composable annotations solve the above problems by letting users define their own annotations that bundle multiple built-in annotations with preset defaults.
   
   Here, two meta-annotations `@FesodMarked` and `@FesodMarked.AliasFor` are introduced to implement the following composite annotation strategy:
   
   **1. Preset mode:** composable-annotations (marked by `@FesodMarked`) do not declare any attributes themselves; they simply bundle several meta-annotations with fixed default values together into a preset configuration, and users cannot override its attributes.
   **2. AliasFor mode:** composable-annotations (marked with `@FesodMarked`) can explicitly declare attribute mapping relationships through `@FesodMarked.AliasFor`, forwarding their own attribute values to the specified attributes of the target annotation. Users can override its attributes.
   
   > Both class-level and field-level composable annotations are supported. When a direct annotation and a composable annotation of the same type coexist at the same level, the direct annotation takes priority.
   
   ### Supported Annotations
   
   In the `fesod-sheet` module, all built-in annotations except `@ExcelIgnore` and `@ExcelIgnoreUnannotated` can be used within composable annotations.
   
   ## API Usage Example
   
   1. Define a composable annotation with `@FesodMarked.AliasFor`
   
   Create a custom annotation that forwards attribute values to `@ExcelProperty`:
   
   ```java
   @Target({ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   @FesodMarked
   @ExcelProperty
   @Inherited
   public @interface ComposableExcelProperty {
   
     @FesodMarked.AliasFor(annotation = ExcelProperty.class, attribute = "value")
     String[] value() default {""};
   
     @FesodMarked.AliasFor(annotation = ExcelProperty.class, attribute = "index")
     int index() default -1;
   
     @FesodMarked.AliasFor(annotation = ExcelProperty.class, attribute = "order")
     int order() default Integer.MAX_VALUE;
   }
   ```
   
   ```java
   public class ExcelModel {
   
     // Same as @ExcelProperty(value = {"Order ID"}, index = 0)
     @ComposableExcelProperty(value = {"Order ID"}, index = 0)
     private String orderId;
   
     // Same as @ExcelProperty(value = {"Total Amount"}, index = 1)
     @ComposableExcelProperty(value = {"Total Amount"}, index = 1)
     private BigDecimal amount;
   }
   ```
   
   2. Define a no-attributes style preset
   
   Group multiple annotations with fixed defaults into a single reusable annotation:
   
   ```java
   @Target({ElementType.TYPE})
   @Retention(RetentionPolicy.RUNTIME)
   @FesodMarked
   @HeadRowHeight(30)
   @ContentRowHeight(20)
   @OnceAbsoluteMerge(firstRowIndex = 0, lastRowIndex = 0, firstColumnIndex = 0, lastColumnIndex = 3)
   @Inherited
   public @interface CommonTableStyle {}
   ```
   
   ```java
   // Same as:
   // @HeadRowHeight(30)
   // @ContentRowHeight(20)
   // @OnceAbsoluteMerge(firstRowIndex = 0, lastRowIndex = 0, firstColumnIndex = 0, lastColumnIndex = 3)
   @CommonTableStyle
   public class ExcelModel {
   
     @ExcelProperty("Date")
     @DateTimeFormat("yyyy-MM-dd")
     private Date date;
   
     @ExcelProperty("Revenue")
     @NumberFormat("#,##0.00")
     private BigDecimal revenue;
   }
   ```
   
   3. Combine field-level and class-level composable annotations
   
   ```java
   @Target({ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   @FesodMarked
   @ContentStyle(wrapped = BooleanEnum.TRUE, fillForegroundColor = 10)
   @ContentFontStyle(fontName = "Arial", fontHeightInPoints = 12, bold = BooleanEnum.TRUE)
   @Inherited
   public @interface ContentPreset {}
   ```
   
   ```java
   // Same as:
   // @HeadRowHeight(30)
   // @ContentRowHeight(20)
   // @OnceAbsoluteMerge(firstRowIndex = 0, lastRowIndex = 0, firstColumnIndex = 0, lastColumnIndex = 3)
   @CommonTableStyle
   public class ExcelModel {
   
     // Same as @ExcelProperty(value = {"Product Name"})
     @ComposableExcelProperty({"Product Name"})
     private String product;
   
     // Same as:
     // @ContentStyle(wrapped = BooleanEnum.TRUE, fillForegroundColor = 10)
     // @ContentFontStyle(fontName = "Arial", fontHeightInPoints = 12, bold = BooleanEnum.TRUE)
     @ContentPreset
     @NumberFormat("#,##0.00")
     private BigDecimal sales;
   }
   ```
   
   4. Enable composable annotation processing
   
   Composable annotations must be explicitly enabled via `enableMetaMarked(true)`:
   
   ```java
   FesodSheet.write(pathname, ExcelModel.class)
       // default false
       .enableMetaMarked(true)
       .sheet(0)
       .doWrite(dataList);
   ```
   
   5. Direct annotations override composable annotations
   
   When both a direct annotation and a composable annotation of the same type exist at the same level, the direct annotation wins:
   
   ```java
   @Target({ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   @FesodMarked
   @ExcelProperty(value = {"Full Name"})
   @Inherited
   public @interface FullNamePreset {}
   ```
   
   ```java
   public class ExcelModel {
   
     @ExcelProperty("First Name")   // takes priority
     @FullNamePreset
     private String firstName;
   }
   ```
   
   6. `@FesodMarked.AliasFor` targets must be meta-present
   
   Every `@FesodMarked.AliasFor` must reference an annotation that is meta-present on the composable.
   
   ```java
   // INVALID: @ColumnWidth is NOT meta-present on this annotation
   @Target({ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   @FesodMarked
   @Inherited
   public @interface BadComposable {
   
     // will throw
     @FesodMarked.AliasFor(annotation = ColumnWidth.class, attribute = "value")
     int width() default -1;
   }
   ```
   
   7. Custom annotation attribute values must be explicitly marked with `@FesodMarked.AliasFor` if they need to be forwarded. (For now)
   
   ```java
   // INVALID: value() value is not forward into @ExcelProperty because there is no mark @FesodMarked.AliasFor.
   @Target({ElementType.FIELD})
   @Retention(RetentionPolicy.RUNTIME)
   @FesodMarked
   @ExcelProperty
   @Inherited
   public @interface BadComposable {
   
     // not work
     String[] value() default {"Name"};
   }
   ```
   
   ### More
   
   Priority:
   
   - Direct annotations on a field > composable annotations on the same field
   - Annotations on the model class > annotations inherited from parent annotations
   
   Compatibility:
   
   The feature is opt-in (enableMetaMarked defaults to false). Existing code using only direct Fesod annotations is completely unaffected.
   
   ### Alternatives
   
   _No response_
   
   ### Anything else?
   
   _No response_
   
   ### Are you willing to submit a PR?
   
   - [x] I'm willing to submit a PR!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@fesod.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fesod.apache.org
For additional commands, e-mail: commits-help@fesod.apache.org