ICU-8918 Added a small section explaining ambiguous wall time resolution in the class...

X-SVN-Rev: 31962

diff --git a/icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java b/icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java
index e4727b85adcb5bd34aad1fe5057ca4c232f3c882..a1f471e7a52036ca35b17979357b61e243d93485 100644 (file)
--- a/icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java
+++ b/icu4j/main/classes/core/src/com/ibm/icu/util/Calendar.java
@@ -100,11 +100,12 @@ import com.ibm.icu.util.ULocale.Category;
  * designate the week before week 1 of a year as week <em>n</em> of the previous
  * year.
  *
- * <p> When computing a <code>Date</code> from time fields, two special
+ * <p> When computing a <code>Date</code> from time fields, some special
  * circumstances may arise: there may be insufficient information to compute the
- * <code>Date</code> (such as only year and month but no day in the month), or
+ * <code>Date</code> (such as only year and month but no day in the month),
  * there may be inconsistent information (such as "Tuesday, July 15, 1996" --
- * July 15, 1996 is actually a Monday).
+ * July 15, 1996 is actually a Monday), or the input time might be ambiguous
+ * because of time zone transition.
  *
  * <p><strong>Insufficient information.</strong> The calendar will use default
  * information to specify the missing fields. This may vary by calendar; for
@@ -133,6 +134,25 @@ import com.ibm.icu.util.ULocale.Category;
  * HOUR_OF_DAY
  * AM_PM + HOUR</pre>
  * </blockquote>
+ * 
+ * <p><strong>Ambiguous Wall Clock Time.</strong> When time offset from UTC has
+ * changed, it produces ambiguous time slot around the transition. For example,
+ * many US locations observe daylight saving time. On the date switching to daylight
+ * saving time in US, wall clock time jumps from 1:00 AM (standard) to 2:00 AM
+ * (daylight). Therefore, wall clock time from 1:00 AM to 1:59 AM do not exist on
+ * the date. When the input wall time fall into this missing time slot, the ICU
+ * Calendar resolves the time using the UTC offset before the transition by default.
+ * In this example, 1:30 AM is interpreted as 1:30 AM standard time (non-exist),
+ * so the final result will be 2:30 AM daylight time.
+ * 
+ * <p>On the date switching back to standard time, wall clock time is moved back one
+ * hour at 2:00 AM. So wall clock time from 1:00 AM to 1:59 AM occur twice. In this
+ * case, the ICU Calendar resolves the time using the UTC offset after the transition
+ * by default. For example, 1:30 AM on the date is resolved as 1:30 AM standard time.
+ * 
+ * <p>Ambiguous wall clock time resolution behaviors can be customized by Calendar APIs
+ * {@link #setRepeatedWallTimeOption(int)} and {@link #setSkippedWallTimeOption(int)}.
+ * These methods are available in ICU 49 or later versions.
  *
  * <p><strong>Note:</strong> for some non-Gregorian calendars, different
  * fields may be necessary for complete disambiguation. For example, a full