1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html#License
3/*
4*   Copyright (C) 1996-2016, International Business Machines
5*   Corporation and others.  All Rights Reserved.
6*/
7
8package com.ibm.icu.util;
9
10import java.io.Serializable;
11import java.util.Date;
12import java.util.GregorianCalendar;
13import java.util.Locale;
14
15import com.ibm.icu.text.DateFormat;
16import com.ibm.icu.util.ULocale.Category;
17
18/**
19 * {@icuenhanced java.util.Calendar}.{@icu _usage_}
20 *
21 * <p><code>Calendar</code> is an abstract base class for converting between
22 * a <code>Date</code> object and a set of integer fields such as
23 * <code>YEAR</code>, <code>MONTH</code>, <code>DAY</code>, <code>HOUR</code>,
24 * and so on. (A <code>Date</code> object represents a specific instant in
25 * time with millisecond precision. See
26 * {@link Date}
27 * for information about the <code>Date</code> class.)
28 *
29 * <p>Subclasses of <code>Calendar</code> interpret a <code>Date</code>
30 * according to the rules of a specific calendar system.  ICU4J contains
31 * several subclasses implementing different international calendar systems.
32 *
33 * <p>
34 * Like other locale-sensitive classes, <code>Calendar</code> provides a
35 * class method, <code>getInstance</code>, for getting a generally useful
36 * object of this type. <code>Calendar</code>'s <code>getInstance</code> method
37 * returns a calendar of a type appropriate to the locale, whose
38 * time fields have been initialized with the current date and time:
39 * <blockquote>
40 * <pre>Calendar rightNow = Calendar.getInstance()</pre>
41 * </blockquote>
42 *
43 * <p>When a <code>ULocale</code> is used by <code>getInstance</code>, its
44 * '<code>calendar</code>' tag and value are retrieved if present.  If a recognized
45 * value is supplied, a calendar is provided and configured as appropriate.
46 * Currently recognized tags are "buddhist", "chinese", "coptic", "ethiopic",
47 * "gregorian", "hebrew", "islamic", "islamic-civil", "japanese", and "roc".  For
48 * example: <blockquote>
49 * <pre>Calendar cal = Calendar.getInstance(new ULocale("en_US@calendar=japanese"));</pre>
50 * </blockquote> will return an instance of JapaneseCalendar (using en_US conventions for
51 * minimum days in first week, start day of week, et cetera).
52 *
53 * <p>A <code>Calendar</code> object can produce all the time field values
54 * needed to implement the date-time formatting for a particular language and
55 * calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
56 * <code>Calendar</code> defines the range of values returned by certain fields,
57 * as well as their meaning.  For example, the first month of the year has value
58 * <code>MONTH</code> == <code>JANUARY</code> for all calendars.  Other values
59 * are defined by the concrete subclass, such as <code>ERA</code> and
60 * <code>YEAR</code>.  See individual field documentation and subclass
61 * documentation for details.
62 *
63 * <p>When a <code>Calendar</code> is <em>lenient</em>, it accepts a wider range
64 * of field values than it produces.  For example, a lenient
65 * <code>GregorianCalendar</code> interprets <code>MONTH</code> ==
66 * <code>JANUARY</code>, <code>DAY_OF_MONTH</code> == 32 as February 1.  A
67 * non-lenient <code>GregorianCalendar</code> throws an exception when given
68 * out-of-range field settings.  When calendars recompute field values for
69 * return by <code>get()</code>, they normalize them.  For example, a
70 * <code>GregorianCalendar</code> always produces <code>DAY_OF_MONTH</code>
71 * values between 1 and the length of the month.
72 *
73 * <p><code>Calendar</code> defines a locale-specific seven day week using two
74 * parameters: the first day of the week and the minimal days in first week
75 * (from 1 to 7).  These numbers are taken from the locale resource data when a
76 * <code>Calendar</code> is constructed.  They may also be specified explicitly
77 * through the API.
78 *
79 * <p>When setting or getting the <code>WEEK_OF_MONTH</code> or
80 * <code>WEEK_OF_YEAR</code> fields, <code>Calendar</code> must determine the
81 * first week of the month or year as a reference point.  The first week of a
82 * month or year is defined as the earliest seven day period beginning on
83 * <code>getFirstDayOfWeek()</code> and containing at least
84 * <code>getMinimalDaysInFirstWeek()</code> days of that month or year.  Weeks
85 * numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow
86 * it.  Note that the normalized numbering returned by <code>get()</code> may be
87 * different.  For example, a specific <code>Calendar</code> subclass may
88 * designate the week before week 1 of a year as week <em>n</em> of the previous
89 * year.
90 *
91 * <p> When computing a <code>Date</code> from time fields, two special
92 * circumstances may arise: there may be insufficient information to compute the
93 * <code>Date</code> (such as only year and month but no day in the month), or
94 * there may be inconsistent information (such as "Tuesday, July 15, 1996" --
95 * July 15, 1996 is actually a Monday).
96 *
97 * <p><strong>Insufficient information.</strong> The calendar will use default
98 * information to specify the missing fields. This may vary by calendar; for
99 * the Gregorian calendar, the default for a field is the same as that of the
100 * start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc.
101 *
102 * <p><strong>Inconsistent information.</strong> If fields conflict, the calendar
103 * will give preference to fields set more recently. For example, when
104 * determining the day, the calendar will look for one of the following
105 * combinations of fields.  The most recent combination, as determined by the
106 * most recently set single field, will be used.
107 *
108 * <blockquote>
109 * <pre>
110 * MONTH + DAY_OF_MONTH
111 * MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
112 * MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
113 * DAY_OF_YEAR
114 * DAY_OF_WEEK + WEEK_OF_YEAR</pre>
115 * </blockquote>
116 *
117 * For the time of day:
118 *
119 * <blockquote>
120 * <pre>
121 * HOUR_OF_DAY
122 * AM_PM + HOUR</pre>
123 * </blockquote>
124 *
125 * <p><strong>Note:</strong> for some non-Gregorian calendars, different
126 * fields may be necessary for complete disambiguation. For example, a full
127 * specification of the historial Arabic astronomical calendar requires year,
128 * month, day-of-month <em>and</em> day-of-week in some cases.
129 *
130 * <p><strong>Note:</strong> There are certain possible ambiguities in
131 * interpretation of certain singular times, which are resolved in the
132 * following ways:
133 * <ol>
134 *     <li> 24:00:00 "belongs" to the following day. That is,
135 *          23:59 on Dec 31, 1969 &lt; 24:00 on Jan 1, 1970 &lt; 24:01:00 on Jan 1, 1970
136 *
137 *     <li> Although historically not precise, midnight also belongs to "am",
138 *          and noon belongs to "pm", so on the same day,
139 *          12:00 am (midnight) &lt; 12:01 am, and 12:00 pm (noon) &lt; 12:01 pm
140 * </ol>
141 *
142 * <p>The date or time format strings are not part of the definition of a
143 * calendar, as those must be modifiable or overridable by the user at
144 * runtime. Use {@link DateFormat}
145 * to format dates.
146 *
147 * <p><strong>Field manipulation methods</strong></p>
148 *
149 * <p><code>Calendar</code> fields can be changed using three methods:
150 * <code>set()</code>, <code>add()</code>, and <code>roll()</code>.</p>
151 *
152 * <p><strong><code>set(f, value)</code></strong> changes field
153 * <code>f</code> to <code>value</code>.  In addition, it sets an
154 * internal member variable to indicate that field <code>f</code> has
155 * been changed. Although field <code>f</code> is changed immediately,
156 * the calendar's milliseconds is not recomputed until the next call to
157 * <code>get()</code>, <code>getTime()</code>, or
158 * <code>getTimeInMillis()</code> is made. Thus, multiple calls to
159 * <code>set()</code> do not trigger multiple, unnecessary
160 * computations. As a result of changing a field using
161 * <code>set()</code>, other fields may also change, depending on the
162 * field, the field value, and the calendar system. In addition,
163 * <code>get(f)</code> will not necessarily return <code>value</code>
164 * after the fields have been recomputed. The specifics are determined by
165 * the concrete calendar class.</p>
166 *
167 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
168 * originally set to August 31, 1999. Calling <code>set(Calendar.MONTH,
169 * Calendar.SEPTEMBER)</code> sets the calendar to September 31,
170 * 1999. This is a temporary internal representation that resolves to
171 * October 1, 1999 if <code>getTime()</code>is then called. However, a
172 * call to <code>set(Calendar.DAY_OF_MONTH, 30)</code> before the call to
173 * <code>getTime()</code> sets the calendar to September 30, 1999, since
174 * no recomputation occurs after <code>set()</code> itself.</p>
175 *
176 * <p><strong><code>add(f, delta)</code></strong> adds <code>delta</code>
177 * to field <code>f</code>.  This is equivalent to calling <code>set(f,
178 * get(f) + delta)</code> with two adjustments:</p>
179 *
180 * <blockquote>
181 *   <p><strong>Add rule 1</strong>. The value of field <code>f</code>
182 *   after the call minus the value of field <code>f</code> before the
183 *   call is <code>delta</code>, modulo any overflow that has occurred in
184 *   field <code>f</code>. Overflow occurs when a field value exceeds its
185 *   range and, as a result, the next larger field is incremented or
186 *   decremented and the field value is adjusted back into its range.</p>
187 *
188 *   <p><strong>Add rule 2</strong>. If a smaller field is expected to be
189 *   invariant, but &nbsp; it is impossible for it to be equal to its
190 *   prior value because of changes in its minimum or maximum after field
191 *   <code>f</code> is changed, then its value is adjusted to be as close
192 *   as possible to its expected value. A smaller field represents a
193 *   smaller unit of time. <code>HOUR</code> is a smaller field than
194 *   <code>DAY_OF_MONTH</code>. No adjustment is made to smaller fields
195 *   that are not expected to be invariant. The calendar system
196 *   determines what fields are expected to be invariant.</p>
197 * </blockquote>
198 *
199 * <p>In addition, unlike <code>set()</code>, <code>add()</code> forces
200 * an immediate recomputation of the calendar's milliseconds and all
201 * fields.</p>
202 *
203 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
204 * originally set to August 31, 1999. Calling <code>add(Calendar.MONTH,
205 * 13)</code> sets the calendar to September 30, 2000. <strong>Add rule
206 * 1</strong> sets the <code>MONTH</code> field to September, since
207 * adding 13 months to August gives September of the next year. Since
208 * <code>DAY_OF_MONTH</code> cannot be 31 in September in a
209 * <code>GregorianCalendar</code>, <strong>add rule 2</strong> sets the
210 * <code>DAY_OF_MONTH</code> to 30, the closest possible value. Although
211 * it is a smaller field, <code>DAY_OF_WEEK</code> is not adjusted by
212 * rule 2, since it is expected to change when the month changes in a
213 * <code>GregorianCalendar</code>.</p>
214 *
215 * <p><strong><code>roll(f, delta)</code></strong> adds
216 * <code>delta</code> to field <code>f</code> without changing larger
217 * fields. This is equivalent to calling <code>add(f, delta)</code> with
218 * the following adjustment:</p>
219 *
220 * <blockquote>
221 *   <p><strong>Roll rule</strong>. Larger fields are unchanged after the
222 *   call. A larger field represents a larger unit of
223 *   time. <code>DAY_OF_MONTH</code> is a larger field than
224 *   <code>HOUR</code>.</p>
225 * </blockquote>
226 *
227 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
228 * originally set to August 31, 1999. Calling <code>roll(Calendar.MONTH,
229 * 8)</code> sets the calendar to April 30, <strong>1999</strong>.  Add
230 * rule 1 sets the <code>MONTH</code> field to April. Using a
231 * <code>GregorianCalendar</code>, the <code>DAY_OF_MONTH</code> cannot
232 * be 31 in the month April. Add rule 2 sets it to the closest possible
233 * value, 30. Finally, the <strong>roll rule</strong> maintains the
234 * <code>YEAR</code> field value of 1999.</p>
235 *
236 * <p><em>Example</em>: Consider a <code>GregorianCalendar</code>
237 * originally set to Sunday June 6, 1999. Calling
238 * <code>roll(Calendar.WEEK_OF_MONTH, -1)</code> sets the calendar to
239 * Tuesday June 1, 1999, whereas calling
240 * <code>add(Calendar.WEEK_OF_MONTH, -1)</code> sets the calendar to
241 * Sunday May 30, 1999. This is because the roll rule imposes an
242 * additional constraint: The <code>MONTH</code> must not change when the
243 * <code>WEEK_OF_MONTH</code> is rolled. Taken together with add rule 1,
244 * the resultant date must be between Tuesday June 1 and Saturday June
245 * 5. According to add rule 2, the <code>DAY_OF_WEEK</code>, an invariant
246 * when changing the <code>WEEK_OF_MONTH</code>, is set to Tuesday, the
247 * closest possible value to Sunday (where Sunday is the first day of the
248 * week).</p>
249 *
250 * <p><strong>Usage model</strong>. To motivate the behavior of
251 * <code>add()</code> and <code>roll()</code>, consider a user interface
252 * component with increment and decrement buttons for the month, day, and
253 * year, and an underlying <code>GregorianCalendar</code>. If the
254 * interface reads January 31, 1999 and the user presses the month
255 * increment button, what should it read? If the underlying
256 * implementation uses <code>set()</code>, it might read March 3, 1999. A
257 * better result would be February 28, 1999. Furthermore, if the user
258 * presses the month increment button again, it should read March 31,
259 * 1999, not March 28, 1999. By saving the original date and using either
260 * <code>add()</code> or <code>roll()</code>, depending on whether larger
261 * fields should be affected, the user interface can behave as most users
262 * will intuitively expect.</p>
263 *
264 * <p><b>Note:</b> You should always use {@link #roll roll} and {@link #add add} rather
265 * than attempting to perform arithmetic operations directly on the fields
266 * of a <tt>Calendar</tt>.  It is quite possible for <tt>Calendar</tt> subclasses
267 * to have fields with non-linear behavior, for example missing months
268 * or days during non-leap years.  The subclasses' <tt>add</tt> and <tt>roll</tt>
269 * methods will take this into account, while simple arithmetic manipulations
270 * may give invalid results.
271 *
272 * <p><big><big><b>Calendar Architecture in ICU4J</b></big></big></p>
273 *
274 * <p>Recently the implementation of <code>Calendar</code> has changed
275 * significantly in order to better support subclassing. The original
276 * <code>Calendar</code> class was designed to support subclassing, but
277 * it had only one implemented subclass, <code>GregorianCalendar</code>.
278 * With the implementation of several new calendar subclasses, including
279 * the <code>BuddhistCalendar</code>, <code>ChineseCalendar</code>,
280 * <code>HebrewCalendar</code>, <code>IslamicCalendar</code>, and
281 * <code>JapaneseCalendar</code>, the subclassing API has been reworked
282 * thoroughly. This section details the new subclassing API and other
283 * ways in which <code>com.ibm.icu.util.Calendar</code> differs from
284 * <code>java.util.Calendar</code>.
285 * </p>
286 *
287 * <p><big><b>Changes</b></big></p>
288 *
289 * <p>Overview of changes between the classic <code>Calendar</code>
290 * architecture and the new architecture.
291 *
292 * <ul>
293 *
294 *   <li>The <code>fields[]</code> array is <code>private</code> now
295 *     instead of <code>protected</code>.  Subclasses must access it
296 *     using the methods {@link #internalSet} and
297 *     {@link #internalGet}.  <b>Motivation:</b> Subclasses should
298 *     not directly access data members.</li>
299 *
300 *   <li>The <code>time</code> long word is <code>private</code> now
301 *     instead of <code>protected</code>.  Subclasses may access it using
302 *     the method {@link #internalGetTimeInMillis}, which does not
303 *     provoke an update. <b>Motivation:</b> Subclasses should not
304 *     directly access data members.</li>
305 *
306 *   <li>The scope of responsibility of subclasses has been drastically
307 *     reduced. As much functionality as possible is implemented in the
308 *     <code>Calendar</code> base class. As a result, it is much easier
309 *     to subclass <code>Calendar</code>. <b>Motivation:</b> Subclasses
310 *     should not have to reimplement common code. Certain behaviors are
311 *     common across calendar systems: The definition and behavior of
312 *     week-related fields and time fields, the arithmetic
313 *     ({@link #add(int, int) add} and {@link #roll(int, int) roll}) behavior of many
314 *     fields, and the field validation system.</li>
315 *
316 *   <li>The subclassing API has been completely redesigned.</li>
317 *
318 *   <li>The <code>Calendar</code> base class contains some Gregorian
319 *     calendar algorithmic support that subclasses can use (specifically
320 *     in {@link #handleComputeFields}).  Subclasses can use the
321 *     methods <code>getGregorianXxx()</code> to obtain precomputed
322 *     values. <b>Motivation:</b> This is required by all
323 *     <code>Calendar</code> subclasses in order to implement consistent
324 *     time zone behavior, and Gregorian-derived systems can use the
325 *     already computed data.</li>
326 *
327 *   <li>The <code>FIELD_COUNT</code> constant has been removed. Use
328 *     {@link #getFieldCount}.  In addition, framework API has been
329 *     added to allow subclasses to define additional fields.
330 *     <b>Motivation: </b>The number of fields is not constant across
331 *     calendar systems.</li>
332 *
333 *   <li>The range of handled dates has been narrowed from +/-
334 *     ~300,000,000 years to +/- ~5,000,000 years. In practical terms
335 *     this should not affect clients. However, it does mean that client
336 *     code cannot be guaranteed well-behaved results with dates such as
337 *     <code>Date(Long.MIN_VALUE)</code> or
338 *     <code>Date(Long.MAX_VALUE)</code>. Instead, the
339 *     <code>Calendar</code> protected constants should be used.
340 *     <b>Motivation:</b> With
341 *     the addition of the {@link #JULIAN_DAY} field, Julian day
342 *     numbers must be restricted to a 32-bit <code>int</code>.  This
343 *     restricts the overall supported range. Furthermore, restricting
344 *     the supported range simplifies the computations by removing
345 *     special case code that was used to accomodate arithmetic overflow
346 *     at millis near <code>Long.MIN_VALUE</code> and
347 *     <code>Long.MAX_VALUE</code>.</li>
348 *
349 *   <li>New fields are implemented: {@link #JULIAN_DAY} defines
350 *     single-field specification of the
351 *     date. {@link #MILLISECONDS_IN_DAY} defines a single-field
352 *     specification of the wall time. {@link #DOW_LOCAL} and
353 *     {@link #YEAR_WOY} implement localized day-of-week and
354 *     week-of-year behavior.</li>
355 *
356 *   <li>Subclasses can access protected millisecond constants
357 *   defined in <code>Calendar</code>.</li>
358 *
359 *   <li>New API has been added to support calendar-specific subclasses
360 *     of <code>DateFormat</code>.</li>
361 *
362 *   <li>Several subclasses have been implemented, representing
363 *     various international calendar systems.</li>
364 *
365 * </ul>
366 *
367 * <p><big><b>Subclass API</b></big></p>
368 *
369 * <p>The original <code>Calendar</code> API was based on the experience
370 * of implementing a only a single subclass,
371 * <code>GregorianCalendar</code>. As a result, all of the subclassing
372 * kinks had not been worked out. The new subclassing API has been
373 * refined based on several implemented subclasses. This includes methods
374 * that must be overridden and methods for subclasses to call. Subclasses
375 * no longer have direct access to <code>fields</code> and
376 * <code>stamp</code>. Instead, they have new API to access
377 * these. Subclasses are able to allocate the <code>fields</code> array
378 * through a protected framework method; this allows subclasses to
379 * specify additional fields. </p>
380 *
381 * <p>More functionality has been moved into the base class. The base
382 * class now contains much of the computational machinery to support the
383 * Gregorian calendar. This is based on two things: (1) Many calendars
384 * are based on the Gregorian calendar (such as the Buddhist and Japanese
385 * imperial calendars). (2) <em>All</em> calendars require basic
386 * Gregorian support in order to handle timezone computations. </p>
387 *
388 * <p>Common computations have been moved into
389 * <code>Calendar</code>. Subclasses no longer compute the week related
390 * fields and the time related fields. These are commonly handled for all
391 * calendars by the base class. </p>
392 *
393 * <p><b>Subclass computation of time <tt>=&gt;</tt> fields</b>
394 *
395 * <p>The {@link #ERA}, {@link #YEAR},
396 * {@link #EXTENDED_YEAR}, {@link #MONTH},
397 * {@link #DAY_OF_MONTH}, and {@link #DAY_OF_YEAR} fields are
398 * computed by the subclass, based on the Julian day. All other fields
399 * are computed by <code>Calendar</code>.
400 *
401 * <ul>
402 *
403 *   <li>Subclasses should implement {@link #handleComputeFields}
404 *     to compute the {@link #ERA}, {@link #YEAR},
405 *     {@link #EXTENDED_YEAR}, {@link #MONTH},
406 *     {@link #DAY_OF_MONTH}, and {@link #DAY_OF_YEAR} fields,
407 *     based on the value of the {@link #JULIAN_DAY} field. If there
408 *     are calendar-specific fields not defined by <code>Calendar</code>,
409 *     they must also be computed. These are the only fields that the
410 *     subclass should compute. All other fields are computed by the base
411 *     class, so time and week fields behave in a consistent way across
412 *     all calendars. The default version of this method in
413 *     <code>Calendar</code> implements a proleptic Gregorian
414 *     calendar. Within this method, subclasses may call
415 *     <code>getGregorianXxx()</code> to obtain the Gregorian calendar
416 *     month, day of month, and extended year for the given date.</li>
417 *
418 * </ul>
419 *
420 * <p><b>Subclass computation of fields <tt>=&gt;</tt> time</b>
421 *
422 * <p>The interpretation of most field values is handled entirely by
423 * <code>Calendar</code>. <code>Calendar</code> determines which fields
424 * are set, which are not, which are set more recently, and so on. In
425 * addition, <code>Calendar</code> handles the computation of the time
426 * from the time fields and handles the week-related fields. The only
427 * thing the subclass must do is determine the extended year, based on
428 * the year fields, and then, given an extended year and a month, it must
429 * return a Julian day number.
430 *
431 * <ul>
432 *
433 *   <li>Subclasses should implement {@link #handleGetExtendedYear}
434 *     to return the extended year for this calendar system, based on the
435 *     {@link #YEAR}, {@link #EXTENDED_YEAR}, and any fields that
436 *     the calendar system uses that are larger than a year, such as
437 *     {@link #ERA}.</li>
438 *
439 *   <li>Subclasses should implement {@link #handleComputeMonthStart}
440 *     to return the Julian day number
441 *     associated with a month and extended year. This is the Julian day
442 *     number of the day before the first day of the month. The month
443 *     number is zero-based. This computation should not depend on any
444 *     field values.</li>
445 *
446 * </ul>
447 *
448 * <p><b>Other methods</b>
449 *
450 * <ul>
451 *
452 *   <li>Subclasses should implement {@link #handleGetMonthLength}
453 *     to return the number of days in a
454 *     given month of a given extended year. The month number, as always,
455 *     is zero-based.</li>
456 *
457 *   <li>Subclasses should implement {@link #handleGetYearLength}
458 *     to return the number of days in the given
459 *     extended year. This method is used by
460 *     <tt>computeWeekFields</tt> to compute the
461 *     {@link #WEEK_OF_YEAR} and {@link #YEAR_WOY} fields.</li>
462 *
463 *   <li>Subclasses should implement {@link #handleGetLimit}
464 *     to return the protected values of a field, depending on the value of
465 *     <code>limitType</code>. This method only needs to handle the
466 *     fields {@link #ERA}, {@link #YEAR}, {@link #MONTH},
467 *     {@link #WEEK_OF_YEAR}, {@link #WEEK_OF_MONTH},
468 *     {@link #DAY_OF_MONTH}, {@link #DAY_OF_YEAR},
469 *     {@link #DAY_OF_WEEK_IN_MONTH}, {@link #YEAR_WOY}, and
470 *     {@link #EXTENDED_YEAR}.  Other fields are invariant (with
471 *     respect to calendar system) and are handled by the base
472 *     class.</li>
473 *
474 *   <li>Optionally, subclasses may override {@link #validateField}
475 *     to check any subclass-specific fields. If the
476 *     field's value is out of range, the method should throw an
477 *     <code>IllegalArgumentException</code>. The method may call
478 *     <code>super.validateField(field)</code> to handle fields in a
479 *     generic way, that is, to compare them to the range
480 *     <code>getMinimum(field)</code>..<code>getMaximum(field)</code>.</li>
481 *
482 *   <li>Optionally, subclasses may override
483 *     {@link #handleCreateFields} to create an <code>int[]</code>
484 *     array large enough to hold the calendar's fields. This is only
485 *     necessary if the calendar defines additional fields beyond those
486 *     defined by <code>Calendar</code>. The length of the result must be
487 *     be between the base and maximum field counts.</li>
488 *
489 *   <li>Optionally, subclasses may override
490 *     {@link #handleGetDateFormat} to create a
491 *     <code>DateFormat</code> appropriate to this calendar. This is only
492 *     required if a calendar subclass redefines the use of a field (for
493 *     example, changes the {@link #ERA} field from a symbolic field
494 *     to a numeric one) or defines an additional field.</li>
495 *
496 *   <li>Optionally, subclasses may override {@link #roll roll} and
497 *     {@link #add add} to handle fields that are discontinuous. For
498 *     example, in the Hebrew calendar the month &quot;Adar I&quot; only
499 *     occurs in leap years; in other years the calendar jumps from
500 *     Shevat (month #4) to Adar (month #6). The {@link
501 *     HebrewCalendar#add HebrewCalendar.add} and {@link
502 *     HebrewCalendar#roll HebrewCalendar.roll} methods take this into
503 *     account, so that adding 1 month to Shevat gives the proper result
504 *     (Adar) in a non-leap year. The protected utility method {@link
505 *     #pinField pinField} is often useful when implementing these two
506 *     methods. </li>
507 *
508 * </ul>
509 *
510 * <p><big><b>Normalized behavior</b></big>
511 *
512 * <p>The behavior of certain fields has been made consistent across all
513 * calendar systems and implemented in <code>Calendar</code>.
514 *
515 * <ul>
516 *
517 *   <li>Time is normalized. Even though some calendar systems transition
518 *     between days at sunset or at other times, all ICU4J calendars
519 *     transition between days at <em>local zone midnight</em>.  This
520 *     allows ICU4J to centralize the time computations in
521 *     <code>Calendar</code> and to maintain basic correpsondences
522 *     between calendar systems. Affected fields: {@link #AM_PM},
523 *     {@link #HOUR}, {@link #HOUR_OF_DAY}, {@link #MINUTE},
524 *     {@link #SECOND}, {@link #MILLISECOND},
525 *     {@link #ZONE_OFFSET}, and {@link #DST_OFFSET}.</li>
526 *
527 *   <li>DST behavior is normalized. Daylight savings time behavior is
528 *     computed the same for all calendar systems, and depends on the
529 *     value of several <code>GregorianCalendar</code> fields: the
530 *     {@link #YEAR}, {@link #MONTH}, and
531 *     {@link #DAY_OF_MONTH}. As a result, <code>Calendar</code>
532 *     always computes these fields, even for non-Gregorian calendar
533 *     systems. These fields are available to subclasses.</li>
534 *
535 *   <li>Weeks are normalized. Although locales define the week
536 *     differently, in terms of the day on which it starts, and the
537 *     designation of week number one of a month or year, they all use a
538 *     common mechanism. Furthermore, the day of the week has a simple
539 *     and consistent definition throughout history. For example,
540 *     although the Gregorian calendar introduced a discontinuity when
541 *     first instituted, the day of week was not disrupted. For this
542 *     reason, the fields {@link #DAY_OF_WEEK}, <code>WEEK_OF_YEAR,
543 *     WEEK_OF_MONTH</code>, {@link #DAY_OF_WEEK_IN_MONTH},
544 *     {@link #DOW_LOCAL}, {@link #YEAR_WOY} are all computed in
545 *     a consistent way in the base class, based on the
546 *     {@link #EXTENDED_YEAR}, {@link #DAY_OF_YEAR},
547 *     {@link #MONTH}, and {@link #DAY_OF_MONTH}, which are
548 *     computed by the subclass.</li>
549 *
550 * </ul>
551 *
552 * <p><big><b>Supported range</b></big>
553 *
554 * <p>The allowable range of <code>Calendar</code> has been
555 * narrowed. <code>GregorianCalendar</code> used to attempt to support
556 * the range of dates with millisecond values from
557 * <code>Long.MIN_VALUE</code> to <code>Long.MAX_VALUE</code>. This
558 * introduced awkward constructions (hacks) which slowed down
559 * performance. It also introduced non-uniform behavior at the
560 * boundaries. The new <code>Calendar</code> protocol specifies the
561 * maximum range of supportable dates as those having Julian day numbers
562 * of <code>-0x7F000000</code> to <code>+0x7F000000</code>. This
563 * corresponds to years from ~5,000,000 BCE to ~5,000,000 CE. Programmers
564 * should use the protected constants in <code>Calendar</code> to
565 * specify an extremely early or extremely late date.</p>
566 *
567 * <p><big><b>General notes</b></big>
568 *
569 * <ul>
570 *
571 *   <li>Calendars implementations are <em>proleptic</em>. For example,
572 *     even though the Gregorian calendar was not instituted until the
573 *     16th century, the <code>GregorianCalendar</code> class supports
574 *     dates before the historical onset of the calendar by extending the
575 *     calendar system backward in time. Similarly, the
576 *     <code>HebrewCalendar</code> extends backward before the start of
577 *     its epoch into zero and negative years. Subclasses do not throw
578 *     exceptions because a date precedes the historical start of a
579 *     calendar system. Instead, they implement
580 *     {@link #handleGetLimit} to return appropriate limits on
581 *     {@link #YEAR}, {@link #ERA}, etc. fields. Then, if the
582 *     calendar is set to not be lenient, out-of-range field values will
583 *     trigger an exception.</li>
584 *
585 *   <li>Calendar system subclasses compute a <em>extended
586 *     year</em>. This differs from the {@link #YEAR} field in that
587 *     it ranges over all integer values, including zero and negative
588 *     values, and it encapsulates the information of the
589 *     {@link #YEAR} field and all larger fields.  Thus, for the
590 *     Gregorian calendar, the {@link #EXTENDED_YEAR} is computed as
591 *     <code>ERA==AD ? YEAR : 1-YEAR</code>. Another example is the Mayan
592 *     long count, which has years (<code>KUN</code>) and nested cycles
593 *     of years (<code>KATUN</code> and <code>BAKTUN</code>). The Mayan
594 *     {@link #EXTENDED_YEAR} is computed as <code>TUN + 20 * (KATUN
595 *     + 20 * BAKTUN)</code>. The <code>Calendar</code> base class uses
596 *     the {@link #EXTENDED_YEAR} field to compute the week-related
597 *     fields.</li>
598 *
599 * </ul>
600 *
601 * @see          Date
602 * @see          GregorianCalendar
603 * @see          TimeZone
604 * @see          DateFormat
605 * @author Mark Davis, Deborah Goldsmith, Chen-Lieh Huang, Alan Liu, Laura Werner
606 * @stable ICU 2.0
607 */
608public class Calendar implements Serializable, Cloneable, Comparable<Calendar> {
609    private static final long serialVersionUID = 1L;
610
611    /**
612     * @internal
613     */
614    public final java.util.Calendar calendar;
615
616    /**
617     * @internal
618     * @param delegate the Calendar to which to delegate
619     */
620    public Calendar(java.util.Calendar delegate) {
621        this.calendar = delegate;
622    }
623
624    // Data flow in Calendar
625    // ---------------------
626
627    // The current time is represented in two ways by Calendar: as UTC
628    // milliseconds from the epoch start (1 January 1970 0:00 UTC), and as local
629    // fields such as MONTH, HOUR, AM_PM, etc.  It is possible to compute the
630    // millis from the fields, and vice versa.  The data needed to do this
631    // conversion is encapsulated by a TimeZone object owned by the Calendar.
632    // The data provided by the TimeZone object may also be overridden if the
633    // user sets the ZONE_OFFSET and/or DST_OFFSET fields directly. The class
634    // keeps track of what information was most recently set by the caller, and
635    // uses that to compute any other information as needed.
636
637    // If the user sets the fields using set(), the data flow is as follows.
638    // This is implemented by the Calendar subclass's computeTime() method.
639    // During this process, certain fields may be ignored.  The disambiguation
640    // algorithm for resolving which fields to pay attention to is described
641    // above.
642
643    //   local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
644    //           |
645    //           | Using Calendar-specific algorithm
646    //           V
647    //   local standard millis
648    //           |
649    //           | Using TimeZone or user-set ZONE_OFFSET / DST_OFFSET
650    //           V
651    //   UTC millis (in time data member)
652
653    // If the user sets the UTC millis using setTime(), the data flow is as
654    // follows.  This is implemented by the Calendar subclass's computeFields()
655    // method.
656
657    //   UTC millis (in time data member)
658    //           |
659    //           | Using TimeZone getOffset()
660    //           V
661    //   local standard millis
662    //           |
663    //           | Using Calendar-specific algorithm
664    //           V
665    //   local fields (YEAR, MONTH, DATE, HOUR, MINUTE, etc.)
666
667    // In general, a round trip from fields, through local and UTC millis, and
668    // back out to fields is made when necessary.  This is implemented by the
669    // complete() method.  Resolving a partial set of fields into a UTC millis
670    // value allows all remaining fields to be generated from that value.  If
671    // the Calendar is lenient, the fields are also renormalized to standard
672    // ranges when they are regenerated.
673
674    /**
675     * Field number for <code>get</code> and <code>set</code> indicating the
676     * era, e.g., AD or BC in the Julian calendar. This is a calendar-specific
677     * value; see subclass documentation.
678     * @see GregorianCalendar#AD
679     * @see GregorianCalendar#BC
680     * @stable ICU 2.0
681     */
682    public final static int ERA = 0;
683
684    /**
685     * Field number for <code>get</code> and <code>set</code> indicating the
686     * year. This is a calendar-specific value; see subclass documentation.
687     * @stable ICU 2.0
688     */
689    public final static int YEAR = 1;
690
691    /**
692     * Field number for <code>get</code> and <code>set</code> indicating the
693     * month. This is a calendar-specific value. The first month of the year is
694     * <code>JANUARY</code>; the last depends on the number of months in a year.
695     * @see #JANUARY
696     * @see #FEBRUARY
697     * @see #MARCH
698     * @see #APRIL
699     * @see #MAY
700     * @see #JUNE
701     * @see #JULY
702     * @see #AUGUST
703     * @see #SEPTEMBER
704     * @see #OCTOBER
705     * @see #NOVEMBER
706     * @see #DECEMBER
707     * @see #UNDECIMBER
708     * @stable ICU 2.0
709     */
710    public final static int MONTH = 2;
711
712    /**
713     * Field number for <code>get</code> and <code>set</code> indicating the
714     * week number within the current year.  The first week of the year, as
715     * defined by {@link #getFirstDayOfWeek()} and
716     * {@link #getMinimalDaysInFirstWeek()}, has value 1.  Subclasses define
717     * the value of {@link #WEEK_OF_YEAR} for days before the first week of
718     * the year.
719     * @see #getFirstDayOfWeek
720     * @see #getMinimalDaysInFirstWeek
721     * @stable ICU 2.0
722     */
723    public final static int WEEK_OF_YEAR = 3;
724
725    /**
726     * Field number for <code>get</code> and <code>set</code> indicating the
727     * week number within the current month.  The first week of the month, as
728     * defined by {@link #getFirstDayOfWeek()} and
729     * {@link #getMinimalDaysInFirstWeek()}, has value 1.  Subclasses define
730     * the value of {@link #WEEK_OF_MONTH} for days before the first week of
731     * the month.
732     * @see #getFirstDayOfWeek
733     * @see #getMinimalDaysInFirstWeek
734     * @stable ICU 2.0
735     */
736    public final static int WEEK_OF_MONTH = 4;
737
738    /**
739     * Field number for <code>get</code> and <code>set</code> indicating the
740     * day of the month. This is a synonym for {@link #DAY_OF_MONTH}.
741     * The first day of the month has value 1.
742     * @see #DAY_OF_MONTH
743     * @stable ICU 2.0
744     */
745    public final static int DATE = 5;
746
747    /**
748     * Field number for <code>get</code> and <code>set</code> indicating the
749     * day of the month. This is a synonym for {@link #DATE}.
750     * The first day of the month has value 1.
751     * @see #DATE
752     * @stable ICU 2.0
753     */
754    public final static int DAY_OF_MONTH = 5;
755
756    /**
757     * Field number for <code>get</code> and <code>set</code> indicating the day
758     * number within the current year.  The first day of the year has value 1.
759     * @stable ICU 2.0
760     */
761    public final static int DAY_OF_YEAR = 6;
762
763    /**
764     * Field number for <code>get</code> and <code>set</code> indicating the day
765     * of the week.  This field takes values {@link #SUNDAY},
766     * {@link #MONDAY}, {@link #TUESDAY}, {@link #WEDNESDAY},
767     * {@link #THURSDAY}, {@link #FRIDAY}, and {@link #SATURDAY}.
768     * @see #SUNDAY
769     * @see #MONDAY
770     * @see #TUESDAY
771     * @see #WEDNESDAY
772     * @see #THURSDAY
773     * @see #FRIDAY
774     * @see #SATURDAY
775     * @stable ICU 2.0
776     */
777    public final static int DAY_OF_WEEK = 7;
778
779    /**
780     * Field number for <code>get</code> and <code>set</code> indicating the
781     * ordinal number of the day of the week within the current month. Together
782     * with the {@link #DAY_OF_WEEK} field, this uniquely specifies a day
783     * within a month.  Unlike {@link #WEEK_OF_MONTH} and
784     * {@link #WEEK_OF_YEAR}, this field's value does <em>not</em> depend on
785     * {@link #getFirstDayOfWeek()} or
786     * {@link #getMinimalDaysInFirstWeek()}.  <code>DAY_OF_MONTH 1</code>
787     * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
788     * 1</code>; <code>8</code> through <code>15</code> correspond to
789     * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
790     * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
791     * <code>DAY_OF_WEEK_IN_MONTH 1</code>.  Negative values count back from the
792     * end of the month, so the last Sunday of a month is specified as
793     * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>.  Because
794     * negative values count backward they will usually be aligned differently
795     * within the month than positive values.  For example, if a month has 31
796     * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
797     * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
798     * @see #DAY_OF_WEEK
799     * @see #WEEK_OF_MONTH
800     * @stable ICU 2.0
801     */
802    public final static int DAY_OF_WEEK_IN_MONTH = 8;
803
804    /**
805     * Field number for <code>get</code> and <code>set</code> indicating
806     * whether the <code>HOUR</code> is before or after noon.
807     * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
808     * @see #AM
809     * @see #PM
810     * @see #HOUR
811     * @stable ICU 2.0
812     */
813    public final static int AM_PM = 9;
814
815    /**
816     * Field number for <code>get</code> and <code>set</code> indicating the
817     * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
818     * clock.
819     * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
820     * @see #AM_PM
821     * @see #HOUR_OF_DAY
822     * @stable ICU 2.0
823     */
824    public final static int HOUR = 10;
825
826    /**
827     * Field number for <code>get</code> and <code>set</code> indicating the
828     * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
829     * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
830     * @see #HOUR
831     * @stable ICU 2.0
832     */
833    public final static int HOUR_OF_DAY = 11;
834
835    /**
836     * Field number for <code>get</code> and <code>set</code> indicating the
837     * minute within the hour.
838     * E.g., at 10:04:15.250 PM the <code>MINUTE</code> is 4.
839     * @stable ICU 2.0
840     */
841    public final static int MINUTE = 12;
842
843    /**
844     * Field number for <code>get</code> and <code>set</code> indicating the
845     * second within the minute.
846     * E.g., at 10:04:15.250 PM the <code>SECOND</code> is 15.
847     * @stable ICU 2.0
848     */
849    public final static int SECOND = 13;
850
851    /**
852     * Field number for <code>get</code> and <code>set</code> indicating the
853     * millisecond within the second.
854     * E.g., at 10:04:15.250 PM the <code>MILLISECOND</code> is 250.
855     * @stable ICU 2.0
856     */
857    public final static int MILLISECOND = 14;
858
859    /**
860     * Field number for <code>get</code> and <code>set</code> indicating the
861     * raw offset from GMT in milliseconds.
862     * @stable ICU 2.0
863     */
864    public final static int ZONE_OFFSET = 15;
865
866    /**
867     * Field number for <code>get</code> and <code>set</code> indicating the
868     * daylight savings offset in milliseconds.
869     * @stable ICU 2.0
870     */
871    public final static int DST_OFFSET = 16;
872
873//    /**
874//     * {@icu} Field number for <code>get()</code> and <code>set()</code>
875//     * indicating the extended year corresponding to the
876//     * {@link #WEEK_OF_YEAR} field.  This may be one greater or less
877//     * than the value of {@link #EXTENDED_YEAR}.
878//     * @stable ICU 2.0
879//     */
880//    public static final int YEAR_WOY = 17;
881//
882//    /**
883//     * {@icu} Field number for <code>get()</code> and <code>set()</code>
884//     * indicating the localized day of week.  This will be a value from 1
885//     * to 7 inclusive, with 1 being the localized first day of the week.
886//     * @stable ICU 2.0
887//     */
888//    public static final int DOW_LOCAL = 18;
889//
890//    /**
891//     * {@icu} Field number for <code>get()</code> and <code>set()</code>
892//     * indicating the extended year.  This is a single number designating
893//     * the year of this calendar system, encompassing all supra-year
894//     * fields.  For example, for the Julian calendar system, year numbers
895//     * are positive, with an era of BCE or CE.  An extended year value for
896//     * the Julian calendar system assigns positive values to CE years and
897//     * negative values to BCE years, with 1 BCE being year 0.
898//     * @stable ICU 2.0
899//     */
900//    public static final int EXTENDED_YEAR = 19;
901//
902//    /**
903//     * {@icu} Field number for <code>get()</code> and <code>set()</code>
904//     * indicating the modified Julian day number.  This is different from
905//     * the conventional Julian day number in two regards.  First, it
906//     * demarcates days at local zone midnight, rather than noon GMT.
907//     * Second, it is a local number; that is, it depends on the local time
908//     * zone.  It can be thought of as a single number that encompasses all
909//     * the date-related fields.
910//     * @stable ICU 2.0
911//     */
912//    public static final int JULIAN_DAY = 20;
913//
914//    /**
915//     * {@icu} Field number for <code>get()</code> and <code>set()</code>
916//     * indicating the milliseconds in the day.  This ranges from 0 to
917//     * 23:59:59.999 (regardless of DST).  This field behaves
918//     * <em>exactly</em> like a composite of all time-related fields, not
919//     * including the zone fields.  As such, it also reflects
920//     * discontinuities of those fields on DST transition days.  On a day of
921//     * DST onset, it will jump forward.  On a day of DST cessation, it will
922//     * jump backward.  This reflects the fact that is must be combined with
923//     * the DST_OFFSET field to obtain a unique local time value.
924//     * @stable ICU 2.0
925//     */
926//    public static final int MILLISECONDS_IN_DAY = 21;
927//
928//    /**
929//     * {@icu} Field indicating whether or not the current month is a leap month.
930//     * Should have a value of 0 for non-leap months, and 1 for leap months.
931//     * @draft ICU 4.4
932//     * @provisional This API might change or be removed in a future release.
933//     */
934//    public static final int IS_LEAP_MONTH = 22;
935
936    /**
937     * Value of the <code>DAY_OF_WEEK</code> field indicating
938     * Sunday.
939     * @stable ICU 2.0
940     */
941    public final static int SUNDAY = 1;
942
943    /**
944     * Value of the <code>DAY_OF_WEEK</code> field indicating
945     * Monday.
946     * @stable ICU 2.0
947     */
948    public final static int MONDAY = 2;
949
950    /**
951     * Value of the <code>DAY_OF_WEEK</code> field indicating
952     * Tuesday.
953     * @stable ICU 2.0
954     */
955    public final static int TUESDAY = 3;
956
957    /**
958     * Value of the <code>DAY_OF_WEEK</code> field indicating
959     * Wednesday.
960     * @stable ICU 2.0
961     */
962    public final static int WEDNESDAY = 4;
963
964    /**
965     * Value of the <code>DAY_OF_WEEK</code> field indicating
966     * Thursday.
967     * @stable ICU 2.0
968     */
969    public final static int THURSDAY = 5;
970
971    /**
972     * Value of the <code>DAY_OF_WEEK</code> field indicating
973     * Friday.
974     * @stable ICU 2.0
975     */
976    public final static int FRIDAY = 6;
977
978    /**
979     * Value of the <code>DAY_OF_WEEK</code> field indicating
980     * Saturday.
981     * @stable ICU 2.0
982     */
983    public final static int SATURDAY = 7;
984
985    /**
986     * Value of the <code>MONTH</code> field indicating the
987     * first month of the year.
988     * @stable ICU 2.0
989     */
990    public final static int JANUARY = 0;
991
992    /**
993     * Value of the <code>MONTH</code> field indicating the
994     * second month of the year.
995     * @stable ICU 2.0
996     */
997    public final static int FEBRUARY = 1;
998
999    /**
1000     * Value of the <code>MONTH</code> field indicating the
1001     * third month of the year.
1002     * @stable ICU 2.0
1003     */
1004    public final static int MARCH = 2;
1005
1006    /**
1007     * Value of the <code>MONTH</code> field indicating the
1008     * fourth month of the year.
1009     * @stable ICU 2.0
1010     */
1011    public final static int APRIL = 3;
1012
1013    /**
1014     * Value of the <code>MONTH</code> field indicating the
1015     * fifth month of the year.
1016     * @stable ICU 2.0
1017     */
1018    public final static int MAY = 4;
1019
1020    /**
1021     * Value of the <code>MONTH</code> field indicating the
1022     * sixth month of the year.
1023     * @stable ICU 2.0
1024     */
1025    public final static int JUNE = 5;
1026
1027    /**
1028     * Value of the <code>MONTH</code> field indicating the
1029     * seventh month of the year.
1030     * @stable ICU 2.0
1031     */
1032    public final static int JULY = 6;
1033
1034    /**
1035     * Value of the <code>MONTH</code> field indicating the
1036     * eighth month of the year.
1037     * @stable ICU 2.0
1038     */
1039    public final static int AUGUST = 7;
1040
1041    /**
1042     * Value of the <code>MONTH</code> field indicating the
1043     * ninth month of the year.
1044     * @stable ICU 2.0
1045     */
1046    public final static int SEPTEMBER = 8;
1047
1048    /**
1049     * Value of the <code>MONTH</code> field indicating the
1050     * tenth month of the year.
1051     * @stable ICU 2.0
1052     */
1053    public final static int OCTOBER = 9;
1054
1055    /**
1056     * Value of the <code>MONTH</code> field indicating the
1057     * eleventh month of the year.
1058     * @stable ICU 2.0
1059     */
1060    public final static int NOVEMBER = 10;
1061
1062    /**
1063     * Value of the <code>MONTH</code> field indicating the
1064     * twelfth month of the year.
1065     * @stable ICU 2.0
1066     */
1067    public final static int DECEMBER = 11;
1068
1069    /**
1070     * Value of the <code>MONTH</code> field indicating the
1071     * thirteenth month of the year. Although {@link GregorianCalendar}
1072     * does not use this value, lunar calendars do.
1073     * @stable ICU 2.0
1074     */
1075    public final static int UNDECIMBER = 12;
1076
1077    /**
1078     * Value of the <code>AM_PM</code> field indicating the
1079     * period of the day from midnight to just before noon.
1080     * @stable ICU 2.0
1081     */
1082    public final static int AM = 0;
1083
1084    /**
1085     * Value of the <code>AM_PM</code> field indicating the
1086     * period of the day from noon to just before midnight.
1087     * @stable ICU 2.0
1088     */
1089    public final static int PM = 1;
1090
1091    /**
1092     * {@icu} Value returned by getDayOfWeekType(int dayOfWeek) to indicate a
1093     * weekday.
1094     * @see #WEEKEND
1095     * @see #WEEKEND_ONSET
1096     * @see #WEEKEND_CEASE
1097     * @see #getDayOfWeekType
1098     * @stable ICU 2.0
1099     */
1100    public static final int WEEKDAY = 0;
1101
1102    /**
1103     * {@icu} Value returned by getDayOfWeekType(int dayOfWeek) to indicate a
1104     * weekend day.
1105     * @see #WEEKDAY
1106     * @see #WEEKEND_ONSET
1107     * @see #WEEKEND_CEASE
1108     * @see #getDayOfWeekType
1109     * @stable ICU 2.0
1110     */
1111    public static final int WEEKEND = 1;
1112
1113    /**
1114     * {@icu} Value returned by getDayOfWeekType(int dayOfWeek) to indicate a
1115     * day that starts as a weekday and transitions to the weekend.
1116     * Call getWeekendTransition() to get the point of transition.
1117     * @see #WEEKDAY
1118     * @see #WEEKEND
1119     * @see #WEEKEND_CEASE
1120     * @see #getDayOfWeekType
1121     * @stable ICU 2.0
1122     */
1123    public static final int WEEKEND_ONSET = 2;
1124
1125    /**
1126     * {@icu} Value returned by getDayOfWeekType(int dayOfWeek) to indicate a
1127     * day that starts as the weekend and transitions to a weekday.
1128     * Call getWeekendTransition() to get the point of transition.
1129     * @see #WEEKDAY
1130     * @see #WEEKEND
1131     * @see #WEEKEND_ONSET
1132     * @see #getDayOfWeekType
1133     * @stable ICU 2.0
1134     */
1135    public static final int WEEKEND_CEASE = 3;
1136
1137    /**
1138     * {@icu}Option used by {@link #setRepeatedWallTimeOption(int)} and
1139     * {@link #setSkippedWallTimeOption(int)} specifying an ambiguous wall time
1140     * to be interpreted as the latest.
1141     * @see #setRepeatedWallTimeOption(int)
1142     * @see #getRepeatedWallTimeOption()
1143     * @see #setSkippedWallTimeOption(int)
1144     * @see #getSkippedWallTimeOption()
1145     * @draft ICU 49
1146     * @provisional This API might change or be removed in a future release.
1147     */
1148    public static final int WALLTIME_LAST = 0;
1149
1150    /**
1151     * {@icu}Option used by {@link #setRepeatedWallTimeOption(int)} and
1152     * {@link #setSkippedWallTimeOption(int)} specifying an ambiguous wall time
1153     * to be interpreted as the earliest.
1154     * @see #setRepeatedWallTimeOption(int)
1155     * @see #getRepeatedWallTimeOption()
1156     * @see #setSkippedWallTimeOption(int)
1157     * @see #getSkippedWallTimeOption()
1158     * @draft ICU 49
1159     * @provisional This API might change or be removed in a future release.
1160     */
1161    public static final int WALLTIME_FIRST = 1;
1162
1163    /**
1164     * {@icu}Option used by {@link #setSkippedWallTimeOption(int)} specifying an
1165     * ambiguous wall time to be interpreted as the next valid wall time.
1166     * @see #setSkippedWallTimeOption(int)
1167     * @see #getSkippedWallTimeOption()
1168     * @draft ICU 49
1169     * @provisional This API might change or be removed in a future release.
1170     */
1171    public static final int WALLTIME_NEXT_VALID = 2;
1172
1173    /**
1174     * Constructs a Calendar with the default time zone
1175     * and locale.
1176     * @see     TimeZone#getDefault
1177     * @stable ICU 2.0
1178     */
1179    protected Calendar()
1180    {
1181        this(TimeZone.getDefault(), ULocale.getDefault(Category.FORMAT));
1182    }
1183
1184    /**
1185     * Constructs a calendar with the specified time zone and locale.
1186     * @param zone the time zone to use
1187     * @param aLocale the locale for the week data
1188     * @stable ICU 2.0
1189     */
1190    protected Calendar(TimeZone zone, Locale aLocale)
1191    {
1192        this(zone, ULocale.forLocale(aLocale));
1193    }
1194
1195    /**
1196     * Constructs a calendar with the specified time zone and locale.
1197     * @param zone the time zone to use
1198     * @param locale the ulocale for the week data
1199     * @stable ICU 3.2
1200     */
1201    protected Calendar(TimeZone zone, ULocale locale)
1202    {
1203        calendar = java.util.Calendar.getInstance(zone.timeZone, locale.toLocale());
1204    }
1205
1206    /**
1207     * Returns a calendar using the default time zone and locale.
1208     * @return a Calendar.
1209     * @stable ICU 2.0
1210     */
1211    public static synchronized Calendar getInstance()
1212    {
1213        return new Calendar(java.util.Calendar.getInstance(ULocale.getDefault(Category.FORMAT).toLocale()));
1214    }
1215
1216    /**
1217     * Returns a calendar using the specified time zone and default locale.
1218     * @param zone the time zone to use
1219     * @return a Calendar.
1220     * @stable ICU 2.0
1221     */
1222    public static synchronized Calendar getInstance(TimeZone zone)
1223    {
1224        return new Calendar(java.util.Calendar.getInstance(zone.timeZone, ULocale.getDefault(Category.FORMAT).toLocale()));
1225    }
1226
1227    /**
1228     * Returns a calendar using the default time zone and specified locale.
1229     * @param aLocale the locale for the week data
1230     * @return a Calendar.
1231     * @stable ICU 2.0
1232     */
1233    public static synchronized Calendar getInstance(Locale aLocale)
1234    {
1235        return new Calendar(java.util.Calendar.getInstance(aLocale));
1236    }
1237
1238    /**
1239     * Returns a calendar using the default time zone and specified locale.
1240     * @param locale the ulocale for the week data
1241     * @return a Calendar.
1242     * @stable ICU 3.2
1243     */
1244    public static synchronized Calendar getInstance(ULocale locale)
1245    {
1246        return new Calendar(java.util.Calendar.getInstance(locale.toLocale()));
1247    }
1248
1249    /**
1250     * Returns a calendar with the specified time zone and locale.
1251     * @param zone the time zone to use
1252     * @param aLocale the locale for the week data
1253     * @return a Calendar.
1254     * @stable ICU 2.0
1255     */
1256    public static synchronized Calendar getInstance(TimeZone zone,
1257                                                    Locale aLocale) {
1258        return new Calendar(java.util.Calendar.getInstance(zone.timeZone, aLocale));
1259    }
1260
1261    /**
1262     * Returns a calendar with the specified time zone and locale.
1263     * @param zone the time zone to use
1264     * @param locale the ulocale for the week data
1265     * @return a Calendar.
1266     * @stable ICU 3.2
1267     */
1268    public static synchronized Calendar getInstance(TimeZone zone,
1269                                                    ULocale locale) {
1270        return new Calendar(java.util.Calendar.getInstance(zone.timeZone, locale.toLocale()));
1271    }
1272
1273    /**
1274     * Returns the list of locales for which Calendars are installed.
1275     * @return the list of locales for which Calendars are installed.
1276     * @stable ICU 2.0
1277     */
1278    public static Locale[] getAvailableLocales()
1279    {
1280        return java.util.Calendar.getAvailableLocales();
1281    }
1282
1283    /**
1284     * {@icu} Returns the list of locales for which Calendars are installed.
1285     * @return the list of locales for which Calendars are installed.
1286     * @draft ICU 3.2 (retain)
1287     * @provisional This API might change or be removed in a future release.
1288     */
1289    public static ULocale[] getAvailableULocales()
1290    {
1291        if (availableLocales == null) {
1292            synchronized (Calendar.class) {
1293                if (availableLocales == null) {
1294                    Locale[] locales = Locale.getAvailableLocales();
1295                    availableLocales = new ULocale[locales.length];
1296                    for (int i = 0; i < locales.length; i++) {
1297                        availableLocales[i] = ULocale.forLocale(locales[i]);
1298                    }
1299                }
1300            }
1301        }
1302        return availableLocales.clone();
1303    }
1304    private static volatile ULocale[] availableLocales;
1305
1306//    /**
1307//     * {@icu} Given a key and a locale, returns an array of string values in a preferred
1308//     * order that would make a difference. These are all and only those values where
1309//     * the open (creation) of the service with the locale formed from the input locale
1310//     * plus input keyword and that value has different behavior than creation with the
1311//     * input locale alone.
1312//     * @param key           one of the keys supported by this service.  For now, only
1313//     *                      "calendar" is supported.
1314//     * @param locale        the locale
1315//     * @param commonlyUsed  if set to true it will return only commonly used values
1316//     *                      with the given locale in preferred order.  Otherwise,
1317//     *                      it will return all the available values for the locale.
1318//     * @return an array of string values for the given key and the locale.
1319//     * @stable ICU 4.2
1320//     */
1321//    public static final String[] getKeywordValuesForLocale(String key, ULocale locale,
1322//                                                           boolean commonlyUsed) {
1323//        throw new UnsupportedOperationException("Method not supported by com.ibm.icu.base");
1324//    }
1325
1326    /**
1327     * Returns this Calendar's current time.
1328     * @return the current time.
1329     * @stable ICU 2.0
1330     */
1331    public final Date getTime() {
1332        return calendar.getTime();
1333    }
1334
1335    /**
1336     * Sets this Calendar's current time with the given Date.
1337     *
1338     * <p>Note: Calling <code>setTime</code> with
1339     * <code>Date(Long.MAX_VALUE)</code> or <code>Date(Long.MIN_VALUE)</code>
1340     * may yield incorrect field values from {@link #get(int)}.
1341     * @param date the given Date.
1342     * @stable ICU 2.0
1343     */
1344    public final void setTime(Date date) {
1345        calendar.setTime(date);
1346    }
1347
1348    /**
1349     * Returns this Calendar's current time as a long.
1350     * @return the current time as UTC milliseconds from the epoch.
1351     * @stable ICU 2.0
1352     */
1353    public long getTimeInMillis() {
1354        return calendar.getTimeInMillis();
1355    }
1356
1357    /**
1358     * Sets this Calendar's current time from the given long value.
1359     * @param millis the new time in UTC milliseconds from the epoch.
1360     * @stable ICU 2.0
1361     */
1362    public void setTimeInMillis( long millis ) {
1363        calendar.setTimeInMillis(millis);
1364    }
1365
1366    /**
1367     * Returns the value for a given time field.
1368     * @param field the given time field.
1369     * @return the value for the given time field.
1370     * @stable ICU 2.0
1371     */
1372    public final int get(int field)
1373    {
1374        return calendar.get(getJDKField(field));
1375    }
1376
1377    /**
1378     * Sets the time field with the given value.
1379     * @param field the given time field.
1380     * @param value the value to be set for the given time field.
1381     * @stable ICU 2.0
1382     */
1383    public final void set(int field, int value)
1384    {
1385        calendar.set(getJDKField(field), value);
1386    }
1387
1388    /**
1389     * Sets the values for the fields year, month, and date.
1390     * Previous values of other fields are retained.  If this is not desired,
1391     * call {@link #clear()} first.
1392     * @param year the value used to set the YEAR time field.
1393     * @param month the value used to set the MONTH time field.
1394     * Month value is 0-based. e.g., 0 for January.
1395     * @param date the value used to set the DATE time field.
1396     * @stable ICU 2.0
1397     */
1398    public final void set(int year, int month, int date)
1399    {
1400        calendar.set(getJDKField(YEAR), year);
1401        calendar.set(getJDKField(MONTH), month);
1402        calendar.set(getJDKField(DATE), date);
1403    }
1404
1405    /**
1406     * Sets the values for the fields year, month, date, hour, and minute.
1407     * Previous values of other fields are retained.  If this is not desired,
1408     * call {@link #clear()} first.
1409     * @param year the value used to set the YEAR time field.
1410     * @param month the value used to set the MONTH time field.
1411     * Month value is 0-based. e.g., 0 for January.
1412     * @param date the value used to set the DATE time field.
1413     * @param hour the value used to set the HOUR_OF_DAY time field.
1414     * @param minute the value used to set the MINUTE time field.
1415     * @stable ICU 2.0
1416     */
1417    public final void set(int year, int month, int date, int hour, int minute)
1418    {
1419        calendar.set(getJDKField(YEAR), year);
1420        calendar.set(getJDKField(MONTH), month);
1421        calendar.set(getJDKField(DATE), date);
1422        calendar.set(getJDKField(HOUR_OF_DAY), hour);
1423        calendar.set(getJDKField(MINUTE), minute);
1424    }
1425
1426    /**
1427     * Sets the values for the fields year, month, date, hour, minute, and second.
1428     * Previous values of other fields are retained.  If this is not desired,
1429     * call {@link #clear} first.
1430     * @param year the value used to set the YEAR time field.
1431     * @param month the value used to set the MONTH time field.
1432     * Month value is 0-based. e.g., 0 for January.
1433     * @param date the value used to set the DATE time field.
1434     * @param hour the value used to set the HOUR_OF_DAY time field.
1435     * @param minute the value used to set the MINUTE time field.
1436     * @param second the value used to set the SECOND time field.
1437     * @stable ICU 2.0
1438     */
1439    public final void set(int year, int month, int date, int hour, int minute,
1440                          int second)
1441    {
1442        calendar.set(getJDKField(YEAR), year);
1443        calendar.set(getJDKField(MONTH), month);
1444        calendar.set(getJDKField(DATE), date);
1445        calendar.set(getJDKField(HOUR_OF_DAY), hour);
1446        calendar.set(getJDKField(MINUTE), minute);
1447        calendar.set(getJDKField(SECOND), second);
1448    }
1449
1450    /**
1451     * Clears the values of all the time fields.
1452     * @stable ICU 2.0
1453     */
1454    public final void clear()
1455    {
1456        calendar.clear();
1457    }
1458
1459    /**
1460     * Clears the value in the given time field.
1461     * @param field the time field to be cleared.
1462     * @stable ICU 2.0
1463     */
1464    public final void clear(int field)
1465    {
1466        calendar.clear(getJDKField(field));
1467    }
1468
1469    /**
1470     * Determines if the given time field has a value set.
1471     * @return true if the given time field has a value set; false otherwise.
1472     * @stable ICU 2.0
1473     */
1474    public final boolean isSet(int field)
1475    {
1476        return calendar.isSet(getJDKField(field));
1477    }
1478
1479    /**
1480     * Compares this calendar to the specified object.
1481     * The result is <code>true</code> if and only if the argument is
1482     * not <code>null</code> and is a <code>Calendar</code> object that
1483     * represents the same calendar as this object.
1484     * @param obj the object to compare with.
1485     * @return <code>true</code> if the objects are the same;
1486     * <code>false</code> otherwise.
1487     * @stable ICU 2.0
1488     */
1489    public boolean equals(Object obj) {
1490        try {
1491            return calendar.equals(((Calendar)obj).calendar);
1492        } catch (Exception e) {
1493            return false;
1494        }
1495    }
1496
1497    /**
1498     * {@icu} Returns true if the given Calendar object is equivalent to this
1499     * one.  An equivalent Calendar will behave exactly as this one
1500     * does, but it may be set to a different time.  By contrast, for
1501     * the equals() method to return true, the other Calendar must
1502     * be set to the same time.
1503     *
1504     * @param other the Calendar to be compared with this Calendar
1505     * @stable ICU 2.4
1506     */
1507    public boolean isEquivalentTo(Calendar other) {
1508        return calendar.getClass() == other.calendar.getClass() &&
1509            calendar.isLenient() == other.calendar.isLenient() &&
1510            calendar.getFirstDayOfWeek() == other.calendar.getFirstDayOfWeek() &&
1511            calendar.getMinimalDaysInFirstWeek() == other.calendar.getMinimalDaysInFirstWeek() &&
1512            calendar.getTimeZone().equals(other.calendar.getTimeZone());
1513    }
1514
1515    /**
1516     * Returns a hash code for this calendar.
1517     * @return a hash code value for this object.
1518     * @stable ICU 2.0
1519     */
1520    public int hashCode() {
1521        return calendar.hashCode();
1522    }
1523
1524    /**
1525     * Returns the difference in milliseconds between the moment this
1526     * calendar is set to and the moment the given calendar or Date object
1527     * is set to.
1528     */
1529    private long compare(Object that) {
1530        long thatMs;
1531        if (that instanceof Calendar) {
1532            thatMs = ((Calendar)that).getTimeInMillis();
1533        } else if (that instanceof Date) {
1534            thatMs = ((Date)that).getTime();
1535        } else {
1536            throw new IllegalArgumentException(that + "is not a Calendar or Date");
1537        }
1538        return getTimeInMillis() - thatMs;
1539    }
1540
1541    /**
1542     * Compares the time field records.
1543     * Equivalent to comparing result of conversion to UTC.
1544     * @param when the Calendar to be compared with this Calendar.
1545     * @return true if the current time of this Calendar is before
1546     * the time of Calendar when; false otherwise.
1547     * @stable ICU 2.0
1548     */
1549    public boolean before(Object when) {
1550        return compare(when) < 0;
1551    }
1552
1553    /**
1554     * Compares the time field records.
1555     * Equivalent to comparing result of conversion to UTC.
1556     * @param when the Calendar to be compared with this Calendar.
1557     * @return true if the current time of this Calendar is after
1558     * the time of Calendar when; false otherwise.
1559     * @stable ICU 2.0
1560     */
1561    public boolean after(Object when) {
1562        return compare(when) > 0;
1563    }
1564
1565    /**
1566     * Returns the maximum value that this field could have, given the
1567     * current date.  For example, with the Gregorian date February 3, 1997
1568     * and the {@link #DAY_OF_MONTH DAY_OF_MONTH} field, the actual maximum
1569     * is 28; for February 3, 1996 it is 29.
1570     *
1571     * <p>The actual maximum computation ignores smaller fields and the
1572     * current value of like-sized fields.  For example, the actual maximum
1573     * of the DAY_OF_YEAR or MONTH depends only on the year and supra-year
1574     * fields.  The actual maximum of the DAY_OF_MONTH depends, in
1575     * addition, on the MONTH field and any other fields at that
1576     * granularity (such as IS_LEAP_MONTH).  The
1577     * DAY_OF_WEEK_IN_MONTH field does not depend on the current
1578     * DAY_OF_WEEK; it returns the maximum for any day of week in the
1579     * current month.  Likewise for the WEEK_OF_MONTH and WEEK_OF_YEAR
1580     * fields.
1581     *
1582     * @param field the field whose maximum is desired
1583     * @return the maximum of the given field for the current date of this calendar
1584     * @see #getMaximum
1585     * @see #getLeastMaximum
1586     * @stable ICU 2.0
1587     */
1588    public int getActualMaximum(int field) {
1589        return calendar.getActualMaximum(getJDKField(field));
1590    }
1591
1592    /**
1593     * Returns the minimum value that this field could have, given the current date.
1594     * For most fields, this is the same as {@link #getMinimum getMinimum}
1595     * and {@link #getGreatestMinimum getGreatestMinimum}.  However, some fields,
1596     * especially those related to week number, are more complicated.
1597     * <p>
1598     * For example, assume {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek}
1599     * returns 4 and {@link #getFirstDayOfWeek getFirstDayOfWeek} returns SUNDAY.
1600     * If the first day of the month is Sunday, Monday, Tuesday, or Wednesday
1601     * there will be four or more days in the first week, so it will be week number 1,
1602     * and <code>getActualMinimum(WEEK_OF_MONTH)</code> will return 1.  However,
1603     * if the first of the month is a Thursday, Friday, or Saturday, there are
1604     * <em>not</em> four days in that week, so it is week number 0, and
1605     * <code>getActualMinimum(WEEK_OF_MONTH)</code> will return 0.
1606     * <p>
1607     * @param field the field whose actual minimum value is desired.
1608     * @return the minimum of the given field for the current date of this calendar
1609     *
1610     * @see #getMinimum
1611     * @see #getGreatestMinimum
1612     * @stable ICU 2.0
1613     */
1614    public int getActualMinimum(int field) {
1615        return calendar.getActualMinimum(getJDKField(field));
1616    }
1617
1618    /**
1619     * Rolls (up/down) a single unit of time on the given field.  If the
1620     * field is rolled past its maximum allowable value, it will "wrap" back
1621     * to its minimum and continue rolling. For
1622     * example, to roll the current date up by one day, you can call:
1623     * <p>
1624     * <code>roll({@link #DATE}, true)</code>
1625     * <p>
1626     * When rolling on the {@link #YEAR} field, it will roll the year
1627     * value in the range between 1 and the value returned by calling
1628     * {@link #getMaximum getMaximum}({@link #YEAR}).
1629     * <p>
1630     * When rolling on certain fields, the values of other fields may conflict and
1631     * need to be changed.  For example, when rolling the <code>MONTH</code> field
1632     * for the Gregorian date 1/31/96 upward, the <code>DAY_OF_MONTH</code> field
1633     * must be adjusted so that the result is 2/29/96 rather than the invalid
1634     * 2/31/96.
1635     * <p>
1636     * <b>Note:</b> Calling <tt>roll(field, true)</tt> N times is <em>not</em>
1637     * necessarily equivalent to calling <tt>roll(field, N)</tt>.  For example,
1638     * imagine that you start with the date Gregorian date January 31, 1995.  If you call
1639     * <tt>roll(Calendar.MONTH, 2)</tt>, the result will be March 31, 1995.
1640     * But if you call <tt>roll(Calendar.MONTH, true)</tt>, the result will be
1641     * February 28, 1995.  Calling it one more time will give March 28, 1995, which
1642     * is usually not the desired result.
1643     * <p>
1644     * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather
1645     * than attempting to perform arithmetic operations directly on the fields
1646     * of a <tt>Calendar</tt>.  It is quite possible for <tt>Calendar</tt> subclasses
1647     * to have fields with non-linear behavior, for example missing months
1648     * or days during non-leap years.  The subclasses' <tt>add</tt> and <tt>roll</tt>
1649     * methods will take this into account, while simple arithmetic manipulations
1650     * may give invalid results.
1651     * <p>
1652     * @param field the calendar field to roll.
1653     *
1654     * @param up    indicates if the value of the specified time field is to be
1655     *              rolled up or rolled down. Use <code>true</code> if rolling up,
1656     *              <code>false</code> otherwise.
1657     *
1658     * @exception   IllegalArgumentException if the field is invalid or refers
1659     *              to a field that cannot be handled by this method.
1660     * @see #roll(int, int)
1661     * @see #add
1662     * @stable ICU 2.0
1663     */
1664    public final void roll(int field, boolean up)
1665    {
1666        calendar.roll(getJDKField(field), up);
1667    }
1668
1669    /**
1670     * Rolls (up/down) a specified amount time on the given field.  For
1671     * example, to roll the current date up by three days, you can call
1672     * <code>roll(Calendar.DATE, 3)</code>.  If the
1673     * field is rolled past its maximum allowable value, it will "wrap" back
1674     * to its minimum and continue rolling.
1675     * For example, calling <code>roll(Calendar.DATE, 10)</code>
1676     * on a Gregorian calendar set to 4/25/96 will result in the date 4/5/96.
1677     * <p>
1678     * When rolling on certain fields, the values of other fields may conflict and
1679     * need to be changed.  For example, when rolling the {@link #MONTH MONTH} field
1680     * for the Gregorian date 1/31/96 by +1, the {@link #DAY_OF_MONTH DAY_OF_MONTH} field
1681     * must be adjusted so that the result is 2/29/96 rather than the invalid
1682     * 2/31/96.
1683     * <p>
1684     * {@icunote} the ICU implementation of this method is able to roll
1685     * all fields except for {@link #ERA ERA}, {@link #DST_OFFSET DST_OFFSET},
1686     * and {@link #ZONE_OFFSET ZONE_OFFSET}.  Subclasses may, of course, add support for
1687     * additional fields in their overrides of <code>roll</code>.
1688     * <p>
1689     * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather
1690     * than attempting to perform arithmetic operations directly on the fields
1691     * of a <tt>Calendar</tt>.  It is quite possible for <tt>Calendar</tt> subclasses
1692     * to have fields with non-linear behavior, for example missing months
1693     * or days during non-leap years.  The subclasses' <tt>add</tt> and <tt>roll</tt>
1694     * methods will take this into account, while simple arithmetic manipulations
1695     * may give invalid results.
1696     * <p>
1697     * <b>Subclassing:</b><br>
1698     * This implementation of <code>roll</code> assumes that the behavior of the
1699     * field is continuous between its minimum and maximum, which are found by
1700     * calling {@link #getActualMinimum getActualMinimum} and {@link #getActualMaximum getActualMaximum}.
1701     * For most such fields, simple addition, subtraction, and modulus operations
1702     * are sufficient to perform the roll.  For week-related fields,
1703     * the results of {@link #getFirstDayOfWeek getFirstDayOfWeek} and
1704     * {@link #getMinimalDaysInFirstWeek getMinimalDaysInFirstWeek} are also necessary.
1705     * Subclasses can override these two methods if their values differ from the defaults.
1706     * <p>
1707     * Subclasses that have fields for which the assumption of continuity breaks
1708     * down must overide <code>roll</code> to handle those fields specially.
1709     * For example, in the Hebrew calendar the month "Adar I"
1710     * only occurs in leap years; in other years the calendar jumps from
1711     * Shevat (month #4) to Adar (month #6).  The
1712     * {@link HebrewCalendar#roll HebrewCalendar.roll} method takes this into account,
1713     * so that rolling the month of Shevat by one gives the proper result (Adar) in a
1714     * non-leap year.
1715     * <p>
1716     * @param field     the calendar field to roll.
1717     * @param amount    the amount by which the field should be rolled.
1718     *
1719     * @exception   IllegalArgumentException if the field is invalid or refers
1720     *              to a field that cannot be handled by this method.
1721     * @see #roll(int, boolean)
1722     * @see #add
1723     * @stable ICU 2.0
1724     */
1725    public void roll(int field, int amount) {
1726        calendar.roll(getJDKField(field), amount);
1727    }
1728
1729    /**
1730     * Add a signed amount to a specified field, using this calendar's rules.
1731     * For example, to add three days to the current date, you can call
1732     * <code>add(Calendar.DATE, 3)</code>.
1733     * <p>
1734     * When adding to certain fields, the values of other fields may conflict and
1735     * need to be changed.  For example, when adding one to the {@link #MONTH MONTH} field
1736     * for the Gregorian date 1/31/96, the {@link #DAY_OF_MONTH DAY_OF_MONTH} field
1737     * must be adjusted so that the result is 2/29/96 rather than the invalid
1738     * 2/31/96.
1739     * <p>
1740     * {@icunote} The ICU implementation of this method is able to add to
1741     * all fields except for {@link #ERA ERA}, {@link #DST_OFFSET DST_OFFSET},
1742     * and {@link #ZONE_OFFSET ZONE_OFFSET}.  Subclasses may, of course, add support for
1743     * additional fields in their overrides of <code>add</code>.
1744     * <p>
1745     * <b>Note:</b> You should always use <tt>roll</tt> and <tt>add</tt> rather
1746     * than attempting to perform arithmetic operations directly on the fields
1747     * of a <tt>Calendar</tt>.  It is quite possible for <tt>Calendar</tt> subclasses
1748     * to have fields with non-linear behavior, for example missing months
1749     * or days during non-leap years.  The subclasses' <tt>add</tt> and <tt>roll</tt>
1750     * methods will take this into account, while simple arithmetic manipulations
1751     * may give invalid results.
1752     * <p>
1753     * <b>Subclassing:</b><br>
1754     * This implementation of <code>add</code> assumes that the behavior of the
1755     * field is continuous between its minimum and maximum, which are found by
1756     * calling {@link #getActualMinimum getActualMinimum} and
1757     * {@link #getActualMaximum getActualMaximum}.
1758     * For such fields, simple arithmetic operations are sufficient to
1759     * perform the add.
1760     * <p>
1761     * Subclasses that have fields for which this assumption of continuity breaks
1762     * down must overide <code>add</code> to handle those fields specially.
1763     * For example, in the Hebrew calendar the month "Adar I"
1764     * only occurs in leap years; in other years the calendar jumps from
1765     * Shevat (month #4) to Adar (month #6).  The
1766     * {@link HebrewCalendar#add HebrewCalendar.add} method takes this into account,
1767     * so that adding one month
1768     * to a date in Shevat gives the proper result (Adar) in a non-leap year.
1769     * <p>
1770     * @param field     the time field.
1771     * @param amount    the amount to add to the field.
1772     *
1773     * @exception   IllegalArgumentException if the field is invalid or refers
1774     *              to a field that cannot be handled by this method.
1775     * @see #roll(int, int)
1776     * @stable ICU 2.0
1777     */
1778    public void add(int field, int amount) {
1779        calendar.add(getJDKField(field), amount);
1780    }
1781
1782    private static String _getDisplayName(Calendar cal) {
1783        String type = cal.getType();
1784        if (type.equals("japanese")) {
1785            return "Japanese Calendar";
1786        } else if (type.equals("buddhist")) {
1787            return "Buddhist Calendar";
1788        }
1789        return "Gregorian Calendar";
1790    }
1791
1792    /**
1793     * Returns the name of this calendar in the language of the given locale.
1794     * @stable ICU 2.0
1795     */
1796    public String getDisplayName(Locale loc) {
1797        return _getDisplayName(this);
1798    }
1799
1800    /**
1801     * Returns the name of this calendar in the language of the given locale.
1802     * @stable ICU 3.2
1803     */
1804    public String getDisplayName(ULocale loc) {
1805        return _getDisplayName(this);
1806    }
1807
1808    /**
1809     * Compares the times (in millis) represented by two
1810     * <code>Calendar</code> objects.
1811     *
1812     * @param that the <code>Calendar</code> to compare to this.
1813     * @return <code>0</code> if the time represented by
1814     * this <code>Calendar</code> is equal to the time represented
1815     * by that <code>Calendar</code>, a value less than
1816     * <code>0</code> if the time represented by this is before
1817     * the time represented by that, and a value greater than
1818     * <code>0</code> if the time represented by this
1819     * is after the time represented by that.
1820     * @throws NullPointerException if that
1821     * <code>Calendar</code> is null.
1822     * @throws IllegalArgumentException if the time of that
1823     * <code>Calendar</code> can't be obtained because of invalid
1824     * calendar values.
1825     * @stable ICU 3.4
1826     */
1827    public int compareTo(Calendar that) {
1828        return calendar.compareTo(that.calendar);
1829    }
1830
1831    //-------------------------------------------------------------------------
1832    // Interface for creating custon DateFormats for different types of Calendars
1833    //-------------------------------------------------------------------------
1834
1835    /**
1836     * {@icu} Returns a <code>DateFormat</code> appropriate to this calendar.
1837     * Subclasses wishing to specialize this behavior should override
1838     * {@link #handleGetDateFormat}.
1839     * @stable ICU 2.0
1840     */
1841    public DateFormat getDateTimeFormat(int dateStyle, int timeStyle, Locale loc) {
1842        if (dateStyle != DateFormat.NONE) {
1843            if (timeStyle == DateFormat.NONE) {
1844                return DateFormat.getDateInstance((Calendar)this.clone(), dateStyle, loc);
1845            } else {
1846                return DateFormat.getDateTimeInstance((Calendar)this.clone(), dateStyle, timeStyle, loc);
1847            }
1848        } else if (timeStyle != DateFormat.NONE) {
1849            return DateFormat.getTimeInstance((Calendar)this.clone(), timeStyle, loc);
1850        } else {
1851            return null;
1852        }
1853    }
1854
1855    /**
1856     * {@icu} Returns a <code>DateFormat</code> appropriate to this calendar.
1857     * Subclasses wishing to specialize this behavior should override
1858     * {@link #handleGetDateFormat}.
1859     * @stable ICU 3.2
1860     */
1861    public DateFormat getDateTimeFormat(int dateStyle, int timeStyle, ULocale loc) {
1862        return getDateTimeFormat(dateStyle, timeStyle, loc.toLocale());
1863    }
1864
1865    //-------------------------------------------------------------------------
1866    // Constants
1867    //-------------------------------------------------------------------------
1868
1869    /**
1870     * {@icu} Returns the difference between the given time and the time this
1871     * calendar object is set to.  If this calendar is set
1872     * <em>before</em> the given time, the returned value will be
1873     * positive.  If this calendar is set <em>after</em> the given
1874     * time, the returned value will be negative.  The
1875     * <code>field</code> parameter specifies the units of the return
1876     * value.  For example, if <code>fieldDifference(when,
1877     * Calendar.MONTH)</code> returns 3, then this calendar is set to
1878     * 3 months before <code>when</code>, and possibly some additional
1879     * time less than one month.
1880     *
1881     * <p>As a side effect of this call, this calendar is advanced
1882     * toward <code>when</code> by the given amount.  That is, calling
1883     * this method has the side effect of calling <code>add(field,
1884     * n)</code>, where <code>n</code> is the return value.
1885     *
1886     * <p>Usage: To use this method, call it first with the largest
1887     * field of interest, then with progressively smaller fields.  For
1888     * example:
1889     *
1890     * <pre>
1891     * int y = cal.fieldDifference(when, Calendar.YEAR);
1892     * int m = cal.fieldDifference(when, Calendar.MONTH);
1893     * int d = cal.fieldDifference(when, Calendar.DATE);</pre>
1894     *
1895     * computes the difference between <code>cal</code> and
1896     * <code>when</code> in years, months, and days.
1897     *
1898     * <p>Note: <code>fieldDifference()</code> is
1899     * <em>asymmetrical</em>.  That is, in the following code:
1900     *
1901     * <pre>
1902     * cal.setTime(date1);
1903     * int m1 = cal.fieldDifference(date2, Calendar.MONTH);
1904     * int d1 = cal.fieldDifference(date2, Calendar.DATE);
1905     * cal.setTime(date2);
1906     * int m2 = cal.fieldDifference(date1, Calendar.MONTH);
1907     * int d2 = cal.fieldDifference(date1, Calendar.DATE);</pre>
1908     *
1909     * one might expect that <code>m1 == -m2 && d1 == -d2</code>.
1910     * However, this is not generally the case, because of
1911     * irregularities in the underlying calendar system (e.g., the
1912     * Gregorian calendar has a varying number of days per month).
1913     *
1914     * @param when the date to compare this calendar's time to
1915     * @param field the field in which to compute the result
1916     * @return the difference, either positive or negative, between
1917     * this calendar's time and <code>when</code>, in terms of
1918     * <code>field</code>.
1919     * @stable ICU 2.0
1920     */
1921    public int fieldDifference(Date when, int field) {
1922        int min = 0;
1923        long startMs = getTimeInMillis();
1924        long targetMs = when.getTime();
1925        // Always add from the start millis.  This accomodates
1926        // operations like adding years from February 29, 2000 up to
1927        // February 29, 2004.  If 1, 1, 1, 1 is added to the year
1928        // field, the DOM gets pinned to 28 and stays there, giving an
1929        // incorrect DOM difference of 1.  We have to add 1, reset, 2,
1930        // reset, 3, reset, 4.
1931        if (startMs < targetMs) {
1932            int max = 1;
1933            // Find a value that is too large
1934            for (;;) {
1935                setTimeInMillis(startMs);
1936                add(field, max);
1937                long ms = getTimeInMillis();
1938                if (ms == targetMs) {
1939                    return max;
1940                } else if (ms > targetMs) {
1941                    break;
1942                } else {
1943                    max <<= 1;
1944                    if (max < 0) {
1945                        // Field difference too large to fit into int
1946                        throw new RuntimeException();
1947                    }
1948                }
1949            }
1950            // Do a binary search
1951            while ((max - min) > 1) {
1952                int t = (min + max) / 2;
1953                setTimeInMillis(startMs);
1954                add(field, t);
1955                long ms = getTimeInMillis();
1956                if (ms == targetMs) {
1957                    return t;
1958                } else if (ms > targetMs) {
1959                    max = t;
1960                } else {
1961                    min = t;
1962                }
1963            }
1964        } else if (startMs > targetMs) {
1965            //Eclipse stated the following is "dead code"
1966            /*if (false) {
1967                // This works, and makes the code smaller, but costs
1968                // an extra object creation and an extra couple cycles
1969                // of calendar computation.
1970                setTimeInMillis(targetMs);
1971                min = -fieldDifference(new Date(startMs), field);
1972            }*/
1973            int max = -1;
1974            // Find a value that is too small
1975            for (;;) {
1976                setTimeInMillis(startMs);
1977                add(field, max);
1978                long ms = getTimeInMillis();
1979                if (ms == targetMs) {
1980                    return max;
1981                } else if (ms < targetMs) {
1982                    break;
1983                } else {
1984                    max <<= 1;
1985                    if (max == 0) {
1986                        // Field difference too large to fit into int
1987                        throw new RuntimeException();
1988                    }
1989                }
1990            }
1991            // Do a binary search
1992            while ((min - max) > 1) {
1993                int t = (min + max) / 2;
1994                setTimeInMillis(startMs);
1995                add(field, t);
1996                long ms = getTimeInMillis();
1997                if (ms == targetMs) {
1998                    return t;
1999                } else if (ms < targetMs) {
2000                    max = t;
2001                } else {
2002                    min = t;
2003                }
2004            }
2005        }
2006        // Set calendar to end point
2007        setTimeInMillis(startMs);
2008        add(field, min);
2009        return min;
2010    }
2011
2012    /**
2013     * Sets the time zone with the given time zone value.
2014     * @param value the given time zone.
2015     * @stable ICU 2.0
2016     */
2017    public void setTimeZone(TimeZone value)
2018    {
2019        calendar.setTimeZone(value.timeZone);
2020    }
2021
2022    /**
2023     * Returns the time zone.
2024     * @return the time zone object associated with this calendar.
2025     * @stable ICU 2.0
2026     */
2027    public TimeZone getTimeZone()
2028    {
2029        return new TimeZone(calendar.getTimeZone());
2030    }
2031
2032    /**
2033     * Specify whether or not date/time interpretation is to be lenient.  With
2034     * lenient interpretation, a date such as "February 942, 1996" will be
2035     * treated as being equivalent to the 941st day after February 1, 1996.
2036     * With strict interpretation, such dates will cause an exception to be
2037     * thrown.
2038     *
2039     * @see DateFormat#setLenient
2040     * @stable ICU 2.0
2041     */
2042    public void setLenient(boolean lenient)
2043    {
2044        calendar.setLenient(lenient);
2045    }
2046
2047    /**
2048     * Tell whether date/time interpretation is to be lenient.
2049     * @stable ICU 2.0
2050     */
2051    public boolean isLenient()
2052    {
2053        return calendar.isLenient();
2054    }
2055
2056//    /**
2057//     * {@icu}Sets the behavior for handling wall time repeating multiple times
2058//     * at negative time zone offset transitions. For example, 1:30 AM on
2059//     * November 6, 2011 in US Eastern time (Ameirca/New_York) occurs twice;
2060//     * 1:30 AM EDT, then 1:30 AM EST one hour later. When <code>WALLTIME_FIRST</code>
2061//     * is used, the wall time 1:30AM in this example will be interpreted as 1:30 AM EDT
2062//     * (first occurrence). When <code>WALLTIME_LAST</code> is used, it will be
2063//     * interpreted as 1:30 AM EST (last occurrence). The default value is
2064//     * <code>WALLTIME_LAST</code>.
2065//     *
2066//     * @param option the behavior for handling repeating wall time, either
2067//     * <code>WALLTIME_FIRST</code> or <code>WALLTIME_LAST</code>.
2068//     * @throws IllegalArgumentException when <code>option</code> is neither
2069//     * <code>WALLTIME_FIRST</code> nor <code>WALLTIME_LAST</code>.
2070//     *
2071//     * @see #getRepeatedWallTimeOption()
2072//     * @see #WALLTIME_FIRST
2073//     * @see #WALLTIME_LAST
2074//     *
2075//     * @draft ICU 49
2076//     * @provisional This API might change or be removed in a future release.
2077//     */
2078//    public void setRepeatedWallTimeOption(int option) {
2079//        if (option != WALLTIME_LAST) {
2080//            throw new UnsupportedOperationException("The option not supported by com.ibm.icu.base");
2081//        }
2082//    }
2083
2084    /**
2085     * {@icu}Gets the behavior for handling wall time repeating multiple times
2086     * at negative time zone offset transitions.
2087     *
2088     * @return the behavior for handling repeating wall time, either
2089     * <code>WALLTIME_FIRST</code> or <code>WALLTIME_LAST</code>.
2090     *
2091     * @see #setRepeatedWallTimeOption(int)
2092     * @see #WALLTIME_FIRST
2093     * @see #WALLTIME_LAST
2094     *
2095     * @draft ICU 49
2096     * @provisional This API might change or be removed in a future release.
2097     */
2098    public int getRepeatedWallTimeOption() {
2099        return WALLTIME_LAST;
2100    }
2101
2102//    /**
2103//     * {@icu}Sets the behavior for handling skipped wall time at positive time zone offset
2104//     * transitions. For example, 2:30 AM on March 13, 2011 in US Eastern time (America/New_York)
2105//     * does not exist because the wall time jump from 1:59 AM EST to 3:00 AM EDT. When
2106//     * <code>WALLTIME_FIRST</code> is used, 2:30 AM is interpreted as 30 minutes before 3:00 AM
2107//     * EDT, therefore, it will be resolved as 1:30 AM EST. When <code>WALLTIME_LAST</code>
2108//     * is used, 2:30 AM is interpreted as 31 minutes after 1:59 AM EST, therefore, it will be
2109//     * resolved as 3:30 AM EDT. When <code>WALLTIME_NEXT_VALID</code> is used, 2:30 AM will
2110//     * be resolved as next valid wall time, that is 3:00 AM EDT. The default value is
2111//     * <code>WALLTIME_LAST</code>.
2112//     * <p>
2113//     * <b>Note:</b>This option is effective only when this calendar is {@link #isLenient() lenient}.
2114//     * When the calendar is strict, such non-existing wall time will cause an exception.
2115//     *
2116//     * @param option the behavior for handling skipped wall time at positive time zone
2117//     * offset transitions, one of <code>WALLTIME_FIRST</code>, <code>WALLTIME_LAST</code> and
2118//     * <code>WALLTIME_NEXT_VALID</code>.
2119//     * @throws IllegalArgumentException when <code>option</code> is not any of
2120//     * <code>WALLTIME_FIRST</code>, <code>WALLTIME_LAST</code> and <code>WALLTIME_NEXT_VALID</code>.
2121//     *
2122//     * @see #getSkippedWallTimeOption()
2123//     * @see #WALLTIME_FIRST
2124//     * @see #WALLTIME_LAST
2125//     * @see #WALLTIME_NEXT_VALID
2126//     *
2127//     * @draft ICU 49
2128//     * @provisional This API might change or be removed in a future release.
2129//     */
2130//    public void setSkippedWallTimeOption(int option) {
2131//        if (option != WALLTIME_LAST) {
2132//            throw new UnsupportedOperationException("The option not supported by com.ibm.icu.base");
2133//        }
2134//    }
2135
2136    /**
2137     * {@icu}Gets the behavior for handling skipped wall time at positive time zone offset
2138     * transitions.
2139     *
2140     * @return the behavior for handling skipped wall time, one of
2141     * <code>WALLTIME_FIRST</code>, <code>WALLTIME_LAST</code> and <code>WALLTIME_NEXT_VALID</code>.
2142     *
2143     * @see #setSkippedWallTimeOption(int)
2144     * @see #WALLTIME_FIRST
2145     * @see #WALLTIME_LAST
2146     * @see #WALLTIME_NEXT_VALID
2147     *
2148     * @draft ICU 49
2149     * @provisional This API might change or be removed in a future release.
2150     */
2151    public int getSkippedWallTimeOption() {
2152        return WALLTIME_LAST;
2153    }
2154
2155    /**
2156     * Sets what the first day of the week is; e.g., Sunday in US,
2157     * Monday in France.
2158     * @param value the given first day of the week.
2159     * @stable ICU 2.0
2160     */
2161    public void setFirstDayOfWeek(int value)
2162    {
2163        calendar.setFirstDayOfWeek(value);
2164    }
2165
2166    /**
2167     * Returns what the first day of the week is; e.g., Sunday in US,
2168     * Monday in France.
2169     * @return the first day of the week.
2170     * @stable ICU 2.0
2171     */
2172    public int getFirstDayOfWeek()
2173    {
2174        return calendar.getFirstDayOfWeek();
2175    }
2176
2177    /**
2178     * Sets what the minimal days required in the first week of the year are.
2179     * For example, if the first week is defined as one that contains the first
2180     * day of the first month of a year, call the method with value 1. If it
2181     * must be a full week, use value 7.
2182     * @param value the given minimal days required in the first week
2183     * of the year.
2184     * @stable ICU 2.0
2185     */
2186    public void setMinimalDaysInFirstWeek(int value)
2187    {
2188        calendar.setMinimalDaysInFirstWeek(value);
2189    }
2190
2191    /**
2192     * Returns what the minimal days required in the first week of the year are;
2193     * e.g., if the first week is defined as one that contains the first day
2194     * of the first month of a year, getMinimalDaysInFirstWeek returns 1. If
2195     * the minimal days required must be a full week, getMinimalDaysInFirstWeek
2196     * returns 7.
2197     * @return the minimal days required in the first week of the year.
2198     * @stable ICU 2.0
2199     */
2200    public int getMinimalDaysInFirstWeek()
2201    {
2202        return calendar.getMinimalDaysInFirstWeek();
2203    }
2204
2205    /**
2206     * Returns the minimum value for the given time field.
2207     * e.g., for Gregorian DAY_OF_MONTH, 1.
2208     * @param field the given time field.
2209     * @return the minimum value for the given time field.
2210     * @stable ICU 2.0
2211     */
2212    public final int getMinimum(int field) {
2213        return calendar.getMinimum(getJDKField(field));
2214    }
2215
2216    /**
2217     * Returns the maximum value for the given time field.
2218     * e.g. for Gregorian DAY_OF_MONTH, 31.
2219     * @param field the given time field.
2220     * @return the maximum value for the given time field.
2221     * @stable ICU 2.0
2222     */
2223    public final int getMaximum(int field) {
2224        return calendar.getMaximum(getJDKField(field));
2225    }
2226
2227    /**
2228     * Returns the highest minimum value for the given field if varies.
2229     * Otherwise same as getMinimum(). For Gregorian, no difference.
2230     * @param field the given time field.
2231     * @return the highest minimum value for the given time field.
2232     * @stable ICU 2.0
2233     */
2234    public final int getGreatestMinimum(int field) {
2235        return calendar.getGreatestMinimum(getJDKField(field));
2236    }
2237
2238    /**
2239     * Returns the lowest maximum value for the given field if varies.
2240     * Otherwise same as getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.
2241     * @param field the given time field.
2242     * @return the lowest maximum value for the given time field.
2243     * @stable ICU 2.0
2244     */
2245    public final int getLeastMaximum(int field) {
2246        return calendar.getLeastMaximum(getJDKField(field));
2247    }
2248
2249    //-------------------------------------------------------------------------
2250    // Weekend support -- determining which days of the week are the weekend
2251    // in a given locale
2252    //-------------------------------------------------------------------------
2253
2254    /**
2255     * {@icu} Returns whether the given day of the week is a weekday, a
2256     * weekend day, or a day that transitions from one to the other,
2257     * in this calendar system.  If a transition occurs at midnight,
2258     * then the days before and after the transition will have the
2259     * type WEEKDAY or WEEKEND.  If a transition occurs at a time
2260     * other than midnight, then the day of the transition will have
2261     * the type WEEKEND_ONSET or WEEKEND_CEASE.  In this case, the
2262     * method getWeekendTransition() will return the point of
2263     * transition.
2264     * @param dayOfWeek either SUNDAY, MONDAY, TUESDAY, WEDNESDAY,
2265     * THURSDAY, FRIDAY, or SATURDAY
2266     * @return either WEEKDAY, WEEKEND, WEEKEND_ONSET, or
2267     * WEEKEND_CEASE
2268     * @exception IllegalArgumentException if dayOfWeek is not
2269     * between SUNDAY and SATURDAY, inclusive
2270     * @see #WEEKDAY
2271     * @see #WEEKEND
2272     * @see #WEEKEND_ONSET
2273     * @see #WEEKEND_CEASE
2274     * @see #getWeekendTransition
2275     * @see #isWeekend(Date)
2276     * @see #isWeekend()
2277     * @stable ICU 2.0
2278     */
2279    public int getDayOfWeekType(int dayOfWeek) {
2280        // weekend always full saturday and sunday with com.ibm.icu.base
2281        if (dayOfWeek < SUNDAY || dayOfWeek > 7) {
2282            throw new IllegalArgumentException("illegal day of week: " + dayOfWeek);
2283        } else if (dayOfWeek == SATURDAY || dayOfWeek == SUNDAY) {
2284            return WEEKEND;
2285        }
2286        return WEEKDAY;}
2287
2288//    /**
2289//     * {@icu} Returns the time during the day at which the weekend begins or end in this
2290//     * calendar system.  If getDayOfWeekType(dayOfWeek) == WEEKEND_ONSET return the time
2291//     * at which the weekend begins.  If getDayOfWeekType(dayOfWeek) == WEEKEND_CEASE
2292//     * return the time at which the weekend ends.  If getDayOfWeekType(dayOfWeek) has some
2293//     * other value, then throw an exception.
2294//     * @param dayOfWeek either SUNDAY, MONDAY, TUESDAY, WEDNESDAY,
2295//     * THURSDAY, FRIDAY, or SATURDAY
2296//     * @return the milliseconds after midnight at which the
2297//     * weekend begins or ends
2298//     * @exception IllegalArgumentException if dayOfWeek is not
2299//     * WEEKEND_ONSET or WEEKEND_CEASE
2300//     * @see #getDayOfWeekType
2301//     * @see #isWeekend(Date)
2302//     * @see #isWeekend()
2303//     * @stable ICU 2.0
2304//     */
2305//    public int getWeekendTransition(int dayOfWeek) {
2306//        throw new UnsupportedOperationException("Method not supported by com.ibm.icu.base");
2307//    }
2308
2309    /**
2310     * {@icu} Returns true if the given date and time is in the weekend in this calendar
2311     * system.  Equivalent to calling setTime() followed by isWeekend().  Note: This
2312     * method changes the time this calendar is set to.
2313     * @param date the date and time
2314     * @return true if the given date and time is part of the
2315     * weekend
2316     * @see #getDayOfWeekType
2317     * @see #getWeekendTransition
2318     * @see #isWeekend()
2319     * @stable ICU 2.0
2320     */
2321    public boolean isWeekend(Date date) {
2322        calendar.setTime(date);
2323        return isWeekend();
2324    }
2325
2326    /**
2327     * {@icu} Returns true if this Calendar's current date and time is in the weekend in
2328     * this calendar system.
2329     * @return true if the given date and time is part of the
2330     * weekend
2331     * @see #getDayOfWeekType
2332     * @see #getWeekendTransition
2333     * @see #isWeekend(Date)
2334     * @stable ICU 2.0
2335     */
2336    public boolean isWeekend() {
2337        // weekend always full saturday and sunday with com.ibm.icu.base
2338        int dow = calendar.get(Calendar.DAY_OF_WEEK);
2339        if (dow == SATURDAY || dow == SUNDAY) {
2340            return true;
2341        }
2342        return false;
2343    }
2344
2345    //-------------------------------------------------------------------------
2346    // End of weekend support
2347    //-------------------------------------------------------------------------
2348
2349    /**
2350     * Overrides Cloneable
2351     * @stable ICU 2.0
2352     */
2353    public Object clone()
2354    {
2355        return new Calendar((java.util.Calendar)calendar.clone());
2356    }
2357
2358    /**
2359     * Returns a string representation of this calendar. This method
2360     * is intended to be used only for debugging purposes, and the
2361     * format of the returned string may vary between implementations.
2362     * The returned string may be empty but may not be <code>null</code>.
2363     *
2364     * @return  a string representation of this calendar.
2365     * @stable ICU 2.0
2366     */
2367    public String toString() {
2368        return calendar.toString();
2369    }
2370
2371    /**
2372     * {@icu} Returns the number of fields defined by this calendar.  Valid field
2373     * arguments to <code>set()</code> and <code>get()</code> are
2374     * <code>0..getFieldCount()-1</code>.
2375     * @stable ICU 2.0
2376     */
2377    public final int getFieldCount() {
2378        return FIELD_COUNT;
2379    }
2380
2381    private static final int FIELD_COUNT = /* IS_LEAP_MONTH */ DST_OFFSET + 1;
2382
2383    /**
2384     * {@icu} Returns the current Calendar type.  Note, in 3.0 this function will return
2385     * 'gregorian' in Calendar to emulate legacy behavior
2386     * @return type of calendar (gregorian, etc)
2387     * @stable ICU 3.8
2388     */
2389    public String getType() {
2390        // JDK supports Gregorian, Japanese and Buddhist
2391        String name = calendar.getClass().getSimpleName().toLowerCase(Locale.US);
2392        if (name.contains("japanese")) {
2393            return "japanese";
2394        } else if (name.contains("buddhist")) {
2395            return "buddhist";
2396        }
2397        return "gregorian";
2398    }
2399
2400    // -------- BEGIN ULocale boilerplate --------
2401
2402//    /**
2403//     * {@icu} Returns the locale that was used to create this object, or null.
2404//     * This may may differ from the locale requested at the time of
2405//     * this object's creation.  For example, if an object is created
2406//     * for locale <tt>en_US_CALIFORNIA</tt>, the actual data may be
2407//     * drawn from <tt>en</tt> (the <i>actual</i> locale), and
2408//     * <tt>en_US</tt> may be the most specific locale that exists (the
2409//     * <i>valid</i> locale).
2410//     *
2411//     * <p>Note: This method will be implemented in ICU 3.0; ICU 2.8
2412//     * contains a partial preview implementation.  The * <i>actual</i>
2413//     * locale is returned correctly, but the <i>valid</i> locale is
2414//     * not, in most cases.
2415//     * @param type type of information requested, either {@link
2416//     * com.ibm.icu.util.ULocale#VALID_LOCALE} or {@link
2417//     * com.ibm.icu.util.ULocale#ACTUAL_LOCALE}.
2418//     * @return the information specified by <i>type</i>, or null if
2419//     * this object was not constructed from locale data.
2420//     * @see com.ibm.icu.util.ULocale
2421//     * @see com.ibm.icu.util.ULocale#VALID_LOCALE
2422//     * @see com.ibm.icu.util.ULocale#ACTUAL_LOCALE
2423//     * @draft ICU 2.8 (retain)
2424//     * @provisional This API might change or be removed in a future release.
2425//     */
2426//    public final ULocale getLocale(ULocale.Type type) {
2427//        throw new UnsupportedOperationException("Method not supported by com.ibm.icu.base");
2428//    }
2429
2430    // -------- END ULocale boilerplate --------
2431
2432
2433    private static int getJDKField(int icuField) {
2434        switch (icuField) {
2435        case ERA:
2436            return java.util.Calendar.ERA;
2437        case YEAR:
2438            return java.util.Calendar.YEAR;
2439        case MONTH:
2440            return java.util.Calendar.MONTH;
2441        case WEEK_OF_YEAR:
2442            return java.util.Calendar.WEEK_OF_YEAR;
2443        case WEEK_OF_MONTH:
2444            return java.util.Calendar.WEEK_OF_MONTH;
2445        case DATE:
2446            return java.util.Calendar.DATE;
2447//        case DAY_OF_MONTH:
2448//            return java.util.Calendar.DAY_OF_MONTH;
2449        case DAY_OF_YEAR:
2450            return java.util.Calendar.DAY_OF_YEAR;
2451        case DAY_OF_WEEK:
2452            return java.util.Calendar.DAY_OF_WEEK;
2453        case DAY_OF_WEEK_IN_MONTH:
2454            return java.util.Calendar.DAY_OF_WEEK_IN_MONTH;
2455        case AM_PM:
2456            return java.util.Calendar.AM_PM;
2457        case HOUR:
2458            return java.util.Calendar.HOUR;
2459        case HOUR_OF_DAY:
2460            return java.util.Calendar.HOUR_OF_DAY;
2461        case MINUTE:
2462            return java.util.Calendar.MINUTE;
2463        case SECOND:
2464            return java.util.Calendar.SECOND;
2465        case MILLISECOND:
2466            return java.util.Calendar.MILLISECOND;
2467        case ZONE_OFFSET:
2468            return java.util.Calendar.ZONE_OFFSET;
2469        case DST_OFFSET:
2470            return java.util.Calendar.DST_OFFSET;
2471
2472//        case YEAR_WOY:
2473//        case DOW_LOCAL:
2474//        case EXTENDED_YEAR:
2475//        case JULIAN_DAY:
2476//        case MILLISECONDS_IN_DAY:
2477//            // Unmappable
2478//            throw new UnsupportedOperationException("Calendar field type not supported by com.ibm.icu.base");
2479        default:
2480            // Illegal
2481            throw new ArrayIndexOutOfBoundsException("Specified calendar field is out of range");
2482        }
2483    }
2484}
2485