Merge pull request #3623 from apache/4036-val.digit.constraints

CAUSEWAY-4036: Consistent Decimal Digit constraining API

Author: andi-huber

api/applib/src/main/java/org/apache/causeway/applib/annotation/ValueSemantics.java

@@ -24,6 +24,7 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 import java.math.BigDecimal;
+import java.math.BigInteger;
 import java.time.format.FormatStyle;
 import java.util.Locale;
 
@@ -64,42 +65,96 @@
     String provider()
         default "";
 
-    // -- NUMBER CONSTRAINTS
+    // -- DIGIT CONSTRAINTS
 
     /**
-     * If associated with a {@link Number}, the maximum number of total digits accepted for
-     * this number.<br>
-     * Can be omitted, if {@link Column#precision()} is used.<br>
-     * default = {@code 65}
+     * If associated with {@link BigDecimal}, {@link BigInteger},
+     * or any Java integer type (long, int, short, byte),
+     * the maximum number of total digits accepted for input (editing).
+     *
+     * <p> But input is not constrained for double/float, since those
+     * types have fixed intrinsic precision and their bit representation does not
+     * directly correspond to decimal digits. Further more, double/float may support
+     * scientific notation for input (as well as display), where the notion of 'total digits' is
+     * no longer viable.
+     *
+     * <p> When {@link Column#precision()} {@code >0} is used,
+     * while {@link ValueSemantics#maxTotalDigits()} is not used (<=0),
+     * then {@link Column#precision()} is undersood as an alias for this annotation attribute.
+     *
+     * <p> default = {@code 0} understood as unlimited
+     *
      * @apiNote SQL's DECIMAL(precision, scale) has max-precision=65 and max-scale=30
      * @see Column#precision()
      */
     int maxTotalDigits()
-        default 65;
+        default 0;
+
+    /**
+     * If associated with any Java number type {@link BigDecimal}, {@link BigInteger},
+     * long, int, short, byte, double or float,
+     * the maximum number of integer digits required for
+     * input (editing).
+     *
+     * <p> For double/float specifically, requires their decimal representation, to satisfy this requirement.
+     * Those types may support scientific notation for input (as well as display), where the notion of 'integer digits'
+     * is still viable.
+     *
+     * <p> {@link Digits#integer()} can be used as a replacement. If both are used, the stronger constraint applies.
+     *
+     * <p> default = {@code 0} understood as unlimited
+     *
+     * @see Digits#integer()
+     */
+    int maxIntegerDigits()
+        default 0;
 
     /**
-     * If associated with a {@link Number}, the minimum number of integer digits required for
-     * this number.<br>
-     * default = {@code 1}
+     * If associated with any Java number type {@link BigDecimal}, {@link BigInteger},
+     * long, int, short, byte, double or float,
+     * the minimum number of integer digits required for
+     * input (editing).
+     *
+     * <p> For double/float specifically, requires their decimal representation, to satisfy this requirement.
+     * Those types may support scientific notation for input (as well as display), where the notion of 'integer digits'
+     * is still viable.
+     *
+     * <p> default = {@code 1}
      */
     int minIntegerDigits()
         default 1;
 
     /**
-     * If associated with a {@link BigDecimal}, the maximum number of fractional digits accepted
-     * for this number.<br>
-     * Can be omitted, if {@link Column#scale()} is used.<br>
-     * default = {@code 30}
+     * If associated with any non-integer {@link Number} type,
+     * the maximum number of fractional decimal digits displayed.
+     *
+     * <p> If associated with a {@link BigDecimal} specifically,
+     * also governs the maximum number of fractional digits accepted for input (editing).
+     *
+     * <p> But input is not constrained for double/float, since those
+     * types have fixed intrinsic precision and their bit representation does not
+     * directly correspond to decimal digits.
+     *
+     * <p> {@link Digits#fraction()} can be used as a replacement. If both are used, the stronger constraint applies.
+     *
+     * <p> When {@link Column#scale()} {@code >0} is used on a {@link BigDecimal},
+     * while {@link ValueSemantics#maxFractionalDigits()} is not used (<0),
+     * then {@link Column#scale()} is undersood as an alias for this annotation attribute.
+     *
+     * <p> default = {@code -1} understood as unlimited
+     *
      * @apiNote SQL's DECIMAL(precision, scale) has max-precision=65 and max-scale=30
+     * @see Digits#fraction()
      * @see Column#scale()
      */
     int maxFractionalDigits()
-        default 30;
+        default -1;
 
     /**
-     * If associated with a {@link BigDecimal}, the minimum number of fractional digits
-     * required for this number.<br>
-     * default = {@code 0}
+     * If associated with any non-integer {@link Number} type,
+     * the minimum number of fractional digits displayed.
+     *
+     * <p> default = {@code 0}
      */
     int minFractionalDigits()
         default 0;
@@ -133,8 +188,10 @@ TimePrecision timePrecision()
      * If associated with a temporal value,
      * that has time-zone or time-offset information,
      * the rendering mode, as to whether to transform the rendered value
-     * to the user's local/current time-zone or not.<br>
-     * default = {@link TimeZoneTranslation#TO_LOCAL_TIMEZONE}
+     * to the user's local/current time-zone or not.
+     *
+     * <p>default = {@link TimeZoneTranslation#TO_LOCAL_TIMEZONE}
+     *
      * @see TimeZoneTranslation
      */
     TimeZoneTranslation timeZoneTranslation()
@@ -151,26 +208,20 @@ TimeZoneTranslation timeZoneTranslation()
      * after the actually stored date.
      * For negative <i>n</i> its days before respectively.
      *
-     * <p>
-     * This is intended to be used so that an exclusive end date of an interval
+     * <p>This is intended to be used so that an exclusive end date of an interval
      * can be rendered as 1 day before the actual value stored.
-     * </p>
      *
-     * <p>
-     * For example:
-     * </p>
+     * <p> For example:
      * <pre>
      * public LocalDate getStartDate() { ... }
      *
      * &#64;ValueSemantics(dateRenderAdjustDays = ValueSemantics.AS_DAY_BEFORE)
      * public LocalDate getEndDate() { ... }
      * </pre>
      *
-     * <p>
-     * Here, the interval of the [1-may-2013,1-jun-2013) would be rendered as the dates
+     * <p>Here, the interval of the [1-may-2013,1-jun-2013) would be rendered as the dates
      * 1-may-2013 for the start date but using 31-may-2013 (the day before) for the end date.  What is stored
      * In the domain object, itself, however, the value stored is 1-jun-2013.
-     * </p>
      */
     int dateRenderAdjustDays()
         default 0;