Allow AbstractDateField to provide DST zone names over custom ranges (#11927)

DateTimeField and DateField currently implement a hardcoded logic by which they adjust their time zone names to display daylight-saving time (DST) zone names. Specifically, this hardcoded logic only adjusts the displayed date to DST format if that date falls in one of the years between 1980 and the following 20 years in the future from the current date (that is, until 2040 at the time of this commit).

For some use cases, this is problematic because it is desirable to display proper DST-adjusted time zones beyond the 20 years limit (and possibly also before 1980).

Rather than choosing another arbitrary, hardcoded threshold, this commit extends the AbstractDateField API to allow the user to choose the range (start and end years) between which the DST transition dates are calculated (and hence displayed properly). If the user doesn't invoke this new API, DateTimeField and DateField will default to behave according the existing logic (i.e. display DST zone names between 1980 and 20 years into the future).

Closes #11919

2 files changed, 121 insertions, 10 deletions

diff --git a/server/src/main/java/com/vaadin/ui/AbstractDateField.java b/server/src/main/java/com/vaadin/ui/AbstractDateField.java
index 9c5d9bb656..84a26436c0 100644
--- a/server/src/main/java/com/vaadin/ui/AbstractDateField.java
+++ b/server/src/main/java/com/vaadin/ui/AbstractDateField.java
@@ -179,6 +179,30 @@ public abstract class AbstractDateField<T extends Temporal & TemporalAdjuster &
     };
 
     /**
+     * The default start year (inclusive) from which to calculate the 
+     * daylight-saving time zone transition dates.
+     */
+    private static final int DEFAULT_START_YEAR = 1980;
+
+    /**
+     * The default value of the number of future years from the current date for
+     * which the daylight-saving time zone transition dates are calculated.
+     */
+    private static final int DEFAULT_YEARS_FROM_NOW = 20;
+
+    /**
+     * The optional user-supplied start year (inclusive) from which to calculate
+     * the daylight-saving time zone transition dates.
+     */
+    private Integer startYear;
+
+    /**
+     * The optional user-supplied end year (inclusive) until which to calculate
+     * the daylight-saving time zone transition dates.
+     */
+    private Integer endYear;
+
+    /**
      * Value of the field.
      */
     private T value;
@@ -489,7 +513,7 @@ public abstract class AbstractDateField<T extends Temporal & TemporalAdjuster &
 
     /**
      * Sets the {@link ZoneId}, which is used when {@code z} is included inside
-     * the {@link #setDateFormat(String)}.
+     * the {@link #setDateFormat(String)} .
      *
      * @param zoneId
      *            the zone id
@@ -498,27 +522,82 @@ public abstract class AbstractDateField<T extends Temporal & TemporalAdjuster &
     public void setZoneId(ZoneId zoneId) {
         if (zoneId != this.zoneId
                 || (zoneId != null && !zoneId.equals(this.zoneId))) {
-            updateTimeZoneJSON(zoneId, getLocale());
+            updateTimeZoneJSON(zoneId, getLocale(), getStartYear(),
+                    getEndYear());
         }
         this.zoneId = zoneId;
     }
 
-    private void updateTimeZoneJSON(ZoneId zoneId, Locale locale) {
+    private void updateTimeZoneJSON(ZoneId zoneId, Locale locale, int startYear,
+            int endYear) {
         String timeZoneJSON;
         if (zoneId != null && locale != null) {
-            timeZoneJSON = TimeZoneUtil.toJSON(zoneId, locale);
+            timeZoneJSON = TimeZoneUtil.toJSON(zoneId, locale, startYear,
+                    endYear);
         } else {
             timeZoneJSON = null;
         }
         getState().timeZoneJSON = timeZoneJSON;
     }
 
+    /**
+     * Sets {@link startYear} and {@link endYear}: the start and end years (both
+     * inclusive) between which to calculate the daylight-saving time zone
+     * transition dates. Both parameters are used when '{@code z}' is included
+     * inside the {@link #setDateFormat(String)}, they would have no effect
+     * otherwise. Specifically, these parameters determine the range of years in 
+     * which zone names are are adjusted to show the daylight saving names. 
+     *
+     * If no values are provided, by default {@link startYear} is set to
+     * {@value #DEFAULT_START_YEAR}, and {@link endYear} is set to
+     * {@value #DEFAULT_YEARS_FROM_NOW} years into the future from the current
+     * date.
+     *
+     * @param startYear
+     *            the start year of DST transitions
+     * @param endYear
+     *            the end year of DST transitions
+     * @since 8.11
+     */
+    public void setDaylightSavingTimeRange(int startYear, int endYear) {
+        if (startYear > endYear) {
+            throw new IllegalArgumentException(
+                    "The start year from which to begin calculating the "
+                            + "daylight-saving time zone transition dates must"
+                            + " be less than or equal to the end year.\n"
+                            + startYear + " is greater than " + endYear);
+        }
+        if (this.startYear == null || this.endYear == null
+                || startYear != this.startYear || endYear != this.endYear) {
+            updateTimeZoneJSON(getZoneId(), getLocale(), startYear, endYear);
+        }
+        this.startYear = startYear;
+        this.endYear = endYear;
+    }
+
+    private int getStartYear() {
+        if (startYear == null) {
+            return DEFAULT_START_YEAR;
+        } else {
+            return startYear;
+        }
+    }
+
+    private int getEndYear() {
+        if (endYear == null) {
+            return LocalDate.now().getYear() + DEFAULT_YEARS_FROM_NOW;
+        } else {
+            return endYear;
+        }
+    }
+
     @Override
     public void setLocale(Locale locale) {
         Locale oldLocale = getLocale();
         if (locale != oldLocale
                 || (locale != null && !locale.equals(oldLocale))) {
-            updateTimeZoneJSON(getZoneId(), locale);
+            updateTimeZoneJSON(getZoneId(), locale, getStartYear(),
+                    getEndYear());
         }
         super.setLocale(locale);
     }
diff --git a/server/src/main/java/com/vaadin/util/TimeZoneUtil.java b/server/src/main/java/com/vaadin/util/TimeZoneUtil.java
index 16e8323f9e..2997378de1 100644
--- a/server/src/main/java/com/vaadin/util/TimeZoneUtil.java
+++ b/server/src/main/java/com/vaadin/util/TimeZoneUtil.java
@@ -42,13 +42,14 @@ import elemental.json.impl.JsonUtil;
 public final class TimeZoneUtil implements Serializable {
 
     /**
-     * The start year used to send the time zone transition dates.
+     * The default start year (inclusive) from which to calculate the
+     * daylight-saving time zone transition dates.
      */
     private static final int STARTING_YEAR = 1980;
 
     /**
-     * Till how many years from now, should we send the time zone transition
-     * dates.
+     * The default value of the number of future years from the current date for
+     * which the daylight-saving time zone transition dates are calculated.
      */
     private static final int YEARS_FROM_NOW = 20;
 
@@ -61,6 +62,12 @@ public final class TimeZoneUtil implements Serializable {
      * which is used in
      * {@link com.google.gwt.i18n.client.TimeZone#createTimeZone(String)}.
      *
+     * This method calculates the JSON string from the year
+     * {@value #STARTING_YEAR} until {@value #YEARS_FROM_NOW} years into the
+     * future from the current date.
+     *
+     * @see #toJSON(ZoneId, Locale, int, int)
+     *
      * @param zoneId
      *            the {@link ZoneId} to get the daylight transitions from
      * @param locale
@@ -69,6 +76,32 @@ public final class TimeZoneUtil implements Serializable {
      * @return the encoded string
      */
     public static String toJSON(ZoneId zoneId, Locale locale) {
+        int endYear = LocalDate.now().getYear() + YEARS_FROM_NOW;
+        return toJSON(zoneId, locale, STARTING_YEAR, endYear);
+    }
+
+    /**
+     * Returns a JSON string of the specified {@code zoneId} and {@link Locale},
+     * which is used in
+     * {@link com.google.gwt.i18n.client.TimeZone#createTimeZone(String)}.
+     *
+     * This method calculates the JSON string from {@code startYear} until
+     * {@code startYear}, both inclusive.
+     *
+     * @param zoneId
+     *            the {@link ZoneId} to get the daylight transitions from
+     * @param locale
+     *            the locale used to determine the short name of the time zone
+     * @param startYear
+     *            the start year of DST transitions
+     * @param endYear
+     *            the end year of DST transitions
+     *
+     * @return the encoded string
+     * @since 8.11
+     */
+    public static String toJSON(ZoneId zoneId, Locale locale, int startYear,
+            int endYear) {
         if (zoneId == null || locale == null) {
             return null;
         }
@@ -78,9 +111,8 @@ public final class TimeZoneUtil implements Serializable {
 
         TimeZoneInfo info = new TimeZoneInfo();
 
-        int endYear = LocalDate.now().getYear() + YEARS_FROM_NOW;
         if (timeZone.useDaylightTime()) {
-            for (int year = STARTING_YEAR; year <= endYear; year++) {
+            for (int year = startYear; year <= endYear; year++) {
                 ZonedDateTime i = LocalDateTime.of(year, 1, 1, 0, 0)
                         .atZone(zoneId);
                 while (true) {