001/* Calendar.java --
002   Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004, 2005, 2006,  
003   Free Software Foundation, Inc.
004
005This file is part of GNU Classpath.
006
007GNU Classpath is free software; you can redistribute it and/or modify
008it under the terms of the GNU General Public License as published by
009the Free Software Foundation; either version 2, or (at your option)
010any later version.
011
012GNU Classpath is distributed in the hope that it will be useful, but
013WITHOUT ANY WARRANTY; without even the implied warranty of
014MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015General Public License for more details.
016
017You should have received a copy of the GNU General Public License
018along with GNU Classpath; see the file COPYING.  If not, write to the
019Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02002110-1301 USA.
021
022Linking this library statically or dynamically with other modules is
023making a combined work based on this library.  Thus, the terms and
024conditions of the GNU General Public License cover the whole
025combination.
026
027As a special exception, the copyright holders of this library give you
028permission to link this library with independent modules to produce an
029executable, regardless of the license terms of these independent
030modules, and to copy and distribute the resulting executable under
031terms of your choice, provided that you also meet, for each linked
032independent module, the terms and conditions of the license of that
033module.  An independent module is a module which is not derived from
034or based on this library.  If you modify this library, you may extend
035this exception to your version of the library, but you are not
036obligated to do so.  If you do not wish to do so, delete this
037exception statement from your version. */
038
039
040package java.util;
041
042import gnu.java.lang.CPStringBuilder;
043
044import java.io.IOException;
045import java.io.ObjectInputStream;
046import java.io.ObjectOutputStream;
047import java.io.Serializable;
048
049import java.lang.reflect.Constructor;
050import java.lang.reflect.InvocationTargetException;
051
052import java.text.DateFormatSymbols;
053
054/**
055 * This class is an abstract base class for Calendars, which can be
056 * used to convert between <code>Date</code> objects and a set of
057 * integer fields which represent <code>YEAR</code>,
058 * <code>MONTH</code>, <code>DAY</code>, etc.  The <code>Date</code>
059 * object represents a time in milliseconds since the Epoch. <br>
060 *
061 * This class is locale sensitive.  To get the Object matching the
062 * current locale you can use <code>getInstance</code>.  You can even provide
063 * a locale or a timezone.  <code>getInstance</code> returns currently
064 * a <code>GregorianCalendar</code> for the current date. <br>
065 *
066 * If you want to convert a date from the Year, Month, Day, DayOfWeek,
067 * etc.  Representation to a <code>Date</code>-Object, you can create
068 * a new Calendar with <code>getInstance()</code>,
069 * <code>clear()</code> all fields, <code>set(int,int)</code> the
070 * fields you need and convert it with <code>getTime()</code>. <br>
071 *
072 * If you want to convert a <code>Date</code>-object to the Calendar
073 * representation, create a new Calendar, assign the
074 * <code>Date</code>-Object with <code>setTime()</code>, and read the
075 * fields with <code>get(int)</code>. <br>
076 *
077 * When computing the date from time fields, it may happen, that there
078 * are either two few fields set, or some fields are inconsistent.  This
079 * cases will handled in a calendar specific way.  Missing fields are
080 * replaced by the fields of the epoch: 1970 January 1 00:00. <br>
081 *
082 * To understand, how the day of year is computed out of the fields
083 * look at the following table.  It is traversed from top to bottom,
084 * and for the first line all fields are set, that line is used to
085 * compute the day. <br>
086 *
087 *
088<pre>month + day_of_month
089month + week_of_month + day_of_week
090month + day_of_week_of_month + day_of_week
091day_of_year
092day_of_week + week_of_year</pre>
093 *
094 * The hour_of_day-field takes precedence over the ampm and
095 * hour_of_ampm fields. <br>
096 *
097 * <STRONG>Note:</STRONG> This can differ for non-Gregorian calendar. <br>
098 *
099 * To convert a calendar to a human readable form and vice versa,  use
100 * the <code>java.text.DateFormat</code> class. <br>
101 *
102 * Other useful things you can do with an calendar, is
103 * <code>roll</code>ing fields (that means increase/decrease a
104 * specific field by one, propagating overflows), or
105 * <code>add</code>ing/substracting a fixed amount to a field.
106 *
107 * @author Aaron M. Renn (arenn@urbanophile.com)
108 * @author Jochen Hoenicke (Jochen.Hoenicke@Informatik.Uni-Oldenburg.de)
109 * @author Warren Levy (warrenl@cygnus.com)
110 * @author Jeff Sturm (jsturm@one-point.com)
111 * @author Tom Tromey (tromey@redhat.com)
112 * @author Bryce McKinlay (mckinlay@redhat.com)
113 * @author Ingo Proetel (proetel@aicas.com)
114 * @author Jerry Quinn (jlquinn@optonline.net)
115 * @author Jeroen Frijters (jeroen@frijters.net)
116 * @author Noa Resare (noa@resare.com)
117 * @author Sven de Marothy (sven@physto.se)
118 * @author David Gilbert (david.gilbert@object-refinery.com)
119 * @author Olivier Jolly (olivier.jolly@pcedev.com)
120 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
121 * @see Date
122 * @see GregorianCalendar
123 * @see TimeZone
124 * @see java.text.DateFormat
125 */
126public abstract class Calendar
127  implements Serializable, Cloneable, Comparable<Calendar>
128{
129  /**
130   * Constant representing the era time field.
131   */
132  public static final int ERA = 0;
133
134  /**
135   * Constant representing the year time field.
136   */
137  public static final int YEAR = 1;
138
139  /**
140   * Constant representing the month time field.  This field
141   * should contain one of the JANUARY,...,DECEMBER constants below.
142   */
143  public static final int MONTH = 2;
144
145  /**
146   * Constant representing the week of the year field.
147   * @see #setFirstDayOfWeek(int)
148   */
149  public static final int WEEK_OF_YEAR = 3;
150
151  /**
152   * Constant representing the week of the month time field.
153   * @see #setFirstDayOfWeek(int)
154   */
155  public static final int WEEK_OF_MONTH = 4;
156
157  /**
158   * Constant representing the day time field, synonym for DAY_OF_MONTH.
159   */
160  public static final int DATE = 5;
161
162  /**
163   * Constant representing the day time field.
164   */
165  public static final int DAY_OF_MONTH = 5;
166
167  /**
168   * Constant representing the day of year time field.  This is
169   * 1 for the first day in month.
170   */
171  public static final int DAY_OF_YEAR = 6;
172
173  /**
174   * Constant representing the day of week time field.  This field
175   * should contain one of the SUNDAY,...,SATURDAY constants below.
176   */
177  public static final int DAY_OF_WEEK = 7;
178
179  /**
180   * Constant representing the day-of-week-in-month field.  For
181   * instance this field contains 2 for the second thursday in a
182   * month.  If you give a negative number here, the day will count
183   * from the end of the month.
184   */
185  public static final int DAY_OF_WEEK_IN_MONTH = 8;
186
187  /**
188   * Constant representing the part of the day for 12-hour clock.  This
189   * should be one of AM or PM.
190   */
191  public static final int AM_PM = 9;
192
193  /**
194   * Constant representing the hour time field for 12-hour clock.
195   */
196  public static final int HOUR = 10;
197
198  /**
199   * Constant representing the hour of day time field for 24-hour clock.
200   */
201  public static final int HOUR_OF_DAY = 11;
202
203  /**
204   * Constant representing the minute of hour time field.
205   */
206  public static final int MINUTE = 12;
207
208  /**
209   * Constant representing the second time field.
210   */
211  public static final int SECOND = 13;
212
213  /**
214   * Constant representing the millisecond time field.
215   */
216  public static final int MILLISECOND = 14;
217
218  /**
219   * Constant representing the time zone offset time field for the
220   * time given in the other fields.  It is measured in
221   * milliseconds.  The default is the offset of the time zone.
222   */
223  public static final int ZONE_OFFSET = 15;
224
225  /**
226   * Constant representing the daylight saving time offset in
227   * milliseconds.  The default is the value given by the time zone.
228   */
229  public static final int DST_OFFSET = 16;
230
231  /**
232   * Number of time fields.
233   */
234  public static final int FIELD_COUNT = 17;
235
236  /**
237   * Constant representing Sunday.
238   */
239  public static final int SUNDAY = 1;
240
241  /**
242   * Constant representing Monday.
243   */
244  public static final int MONDAY = 2;
245
246  /**
247   * Constant representing Tuesday.
248   */
249  public static final int TUESDAY = 3;
250
251  /**
252   * Constant representing Wednesday.
253   */
254  public static final int WEDNESDAY = 4;
255
256  /**
257   * Constant representing Thursday.
258   */
259  public static final int THURSDAY = 5;
260
261  /**
262   * Constant representing Friday.
263   */
264  public static final int FRIDAY = 6;
265
266  /**
267   * Constant representing Saturday.
268   */
269  public static final int SATURDAY = 7;
270
271  /**
272   * Constant representing January.
273   */
274  public static final int JANUARY = 0;
275
276  /**
277   * Constant representing February.
278   */
279  public static final int FEBRUARY = 1;
280
281  /**
282   * Constant representing March.
283   */
284  public static final int MARCH = 2;
285
286  /**
287   * Constant representing April.
288   */
289  public static final int APRIL = 3;
290
291  /**
292   * Constant representing May.
293   */
294  public static final int MAY = 4;
295
296  /**
297   * Constant representing June.
298   */
299  public static final int JUNE = 5;
300
301  /**
302   * Constant representing July.
303   */
304  public static final int JULY = 6;
305
306  /**
307   * Constant representing August.
308   */
309  public static final int AUGUST = 7;
310
311  /**
312   * Constant representing September.
313   */
314  public static final int SEPTEMBER = 8;
315
316  /**
317   * Constant representing October.
318   */
319  public static final int OCTOBER = 9;
320
321  /**
322   * Constant representing November.
323   */
324  public static final int NOVEMBER = 10;
325
326  /**
327   * Constant representing December.
328   */
329  public static final int DECEMBER = 11;
330
331  /**
332   * Constant representing Undecimber. This is an artificial name useful
333   * for lunar calendars.
334   */
335  public static final int UNDECIMBER = 12;
336
337  /**
338   * Useful constant for 12-hour clock.
339   */
340  public static final int AM = 0;
341
342  /**
343   * Useful constant for 12-hour clock.
344   */
345  public static final int PM = 1;
346
347  /**
348   * A style specifier for {@link #getDisplayNames(int,int,Locale)}
349   * stating that names should be returned in both long and short variants.
350   *
351   * @since 1.6
352   * @see #SHORT
353   * @see #LONG
354   */
355  public static final int ALL_STYLES = 0;
356
357  /**
358   * A style specifier for {@link #getDisplayName(int,int,Locale)}
359   * and {@link #getDisplayNames(int,int,Locale)} stating that names
360   * should be returned in their short variant if applicable.
361   *
362   * @since 1.6
363   */
364  public static final int SHORT = 1;
365
366  /**
367   * A style specifier for {@link #getDisplayName(int,int,Locale)}
368   * and {@link #getDisplayNames(int,int,Locale)} stating that names
369   * should be returned in their long variant if applicable.
370   *
371   * @since 1.6
372   */
373  public static final int LONG = 2;
374
375  /**
376   * The time fields.  The array is indexed by the constants YEAR to
377   * DST_OFFSET.
378   * @serial
379   */
380  protected int[] fields = new int[FIELD_COUNT];
381
382  /**
383   * The flags which tell if the fields above have a value.
384   * @serial
385   */
386  protected boolean[] isSet = new boolean[FIELD_COUNT];
387
388  /**
389   * The time in milliseconds since the epoch.
390   * @serial
391   */
392  protected long time;
393
394  /**
395   * Tells if the above field has a valid value.
396   * @serial
397   */
398  protected boolean isTimeSet;
399
400  /**
401   * Tells if the fields have a valid value.  This superseeds the isSet
402   * array.
403   * @serial
404   */
405  protected boolean areFieldsSet;
406
407  /**
408   * The time zone of this calendar.  Used by sub classes to do UTC / local
409   * time conversion.  Sub classes can access this field with getTimeZone().
410   * @serial
411   */
412  private TimeZone zone;
413
414  /**
415   * This is the default calendar class, that is returned on
416   * java.util.Calendar.getInstance().
417   * XXX - this isn't localized anywhere, is it?
418   * @see java.util.Calendar#getInstance()
419   */
420  private static final String calendarClassName = "java.util.GregorianCalendar";
421
422  /**
423   * Specifies if the date/time interpretation should be lenient.
424   * If the flag is set, a date such as "February 30, 1996" will be
425   * treated as the 29th day after the February 1.  If this flag
426   * is false, such dates will cause an exception.
427   * @serial
428   */
429  private boolean lenient;
430
431  /**
432   * Sets what the first day of week is.  This is used for
433   * WEEK_OF_MONTH and WEEK_OF_YEAR fields.
434   * @serial
435   */
436  private int firstDayOfWeek;
437
438  /**
439   * Sets how many days are required in the first week of the year.
440   * If the first day of the year should be the first week you should
441   * set this value to 1.  If the first week must be a full week, set
442   * it to 7.
443   * @serial
444   */
445  private int minimalDaysInFirstWeek;
446
447  /**
448   * Is set to true if DST_OFFSET is explicitly set. In that case
449   * it's value overrides the value computed from the current
450   * time and the timezone.
451   */
452  private boolean explicitDSTOffset = false;
453
454  /**
455   * The version of the serialized data on the stream.
456   * <dl><dt>0 or not present</dt>
457   * <dd> JDK 1.1.5 or later.</dd>
458   * <dt>1</dt>
459   * <dd>JDK 1.1.6 or later.  This always writes a correct `time' value
460   * on the stream, as well as the other fields, to be compatible with
461   * earlier versions</dd></dl>
462   * @since JDK1.1.6
463   * @serial
464   */
465  private int serialVersionOnStream = 1;
466
467  /**
468   * XXX - I have not checked the compatibility.  The documentation of
469   * the serialized-form is quite hairy...
470   */
471  static final long serialVersionUID = -1807547505821590642L;
472
473  /**
474   * The name of the resource bundle. Used only by getBundle()
475   */
476  private static final String bundleName = "gnu.java.locale.LocaleInformation";
477
478  /**
479   * get resource bundle:
480   * The resources should be loaded via this method only. Iff an application
481   * uses this method, the resourcebundle is required.
482   */
483  private static ResourceBundle getBundle(Locale locale)
484  {
485    return ResourceBundle.getBundle(bundleName, locale,
486                                    ClassLoader.getSystemClassLoader());
487  }
488
489  /**
490   * The set of properties for obtaining the minimum number of days in 
491   * the first week.
492   */
493  private static transient final Properties properties;
494
495  /**
496   * Reads in the properties.
497   */
498  static
499  {
500    properties = new Properties();
501    try 
502      {
503        properties.load(Calendar.class.getResourceAsStream("weeks.properties"));
504      }
505    catch (IOException exception)
506      {
507        System.out.println("Failed to load weeks resource: " + exception);
508      }
509  }
510
511  /**
512   * Constructs a new Calendar with the default time zone and the default
513   * locale.
514   */
515  protected Calendar()
516  {
517    this(TimeZone.getDefault(), Locale.getDefault());
518  }
519
520  /**
521   * Constructs a new Calendar with the given time zone and the given
522   * locale.
523   * @param zone a time zone.
524   * @param locale a locale.
525   */
526  protected Calendar(TimeZone zone, Locale locale)
527  {
528    this.zone = zone;
529    lenient = true;
530    String[] days = { "", "sun", "mon", "tue", "wed", "thu", "fri", "sat" };
531
532    String country = locale.getCountry();
533    String min = properties.getProperty("minDays." + country);
534    if (min == null)
535      min = properties.getProperty("minDays.DEFAULT");
536    String first = properties.getProperty("firstDay." + country);
537    if (first == null)
538      first = properties.getProperty("firstDay.DEFAULT");
539    try
540      {
541        if (min != null)
542          minimalDaysInFirstWeek = Integer.parseInt(min);
543      }
544    catch (NumberFormatException ex)
545      {
546        minimalDaysInFirstWeek = 1;
547      }
548
549    firstDayOfWeek = 1;
550    if (first != null)
551      for (int i = 0; i < 8; i++)
552        if (days[i].equals(first))
553          firstDayOfWeek = i;
554
555    clear();
556  }
557
558  /**
559   * Creates a calendar representing the actual time, using the default
560   * time zone and locale.
561   * 
562   * @return The new calendar.
563   */
564  public static synchronized Calendar getInstance()
565  {
566    return getInstance(TimeZone.getDefault(), Locale.getDefault());
567  }
568
569  /**
570   * Creates a calendar representing the actual time, using the given
571   * time zone and the default locale.
572   * 
573   * @param zone a time zone (<code>null</code> not permitted).
574   * 
575   * @return The new calendar.
576   * 
577   * @throws NullPointerException if <code>zone</code> is <code>null</code>.
578   */
579  public static synchronized Calendar getInstance(TimeZone zone)
580  {
581    return getInstance(zone, Locale.getDefault());
582  }
583
584  /**
585   * Creates a calendar representing the actual time, using the default
586   * time zone and the given locale.
587   * 
588   * @param locale a locale (<code>null</code> not permitted).
589   * 
590   * @return The new calendar.
591   * 
592   * @throws NullPointerException if <code>locale</code> is <code>null</code>.
593   */
594  public static synchronized Calendar getInstance(Locale locale)
595  {
596    return getInstance(TimeZone.getDefault(), locale);
597  }
598
599  /**
600   * Cache of locale->calendar-class mappings. This avoids having to do a ResourceBundle
601   * lookup for every getInstance call.
602   */
603  private static final HashMap<Locale,Class> cache = new HashMap<Locale,Class>();
604
605  /** Preset argument types for calendar-class constructor lookup.  */
606  private static Class[] ctorArgTypes = new Class[]
607                                        {
608                                          TimeZone.class, Locale.class
609                                        };
610
611  /**
612   * Creates a calendar representing the actual time, using the given
613   * time zone and locale.
614   * 
615   * @param zone a time zone (<code>null</code> not permitted).
616   * @param locale a locale (<code>null</code> not permitted).
617   * 
618   * @return The new calendar.
619   * 
620   * @throws NullPointerException if <code>zone</code> or <code>locale</code>
621   *     is <code>null</code>.
622   */
623  public static synchronized Calendar getInstance(TimeZone zone, Locale locale)
624  {
625    Class calendarClass = cache.get(locale);
626    Throwable exception = null;
627
628    try
629      {
630        if (calendarClass == null)
631          {
632            calendarClass = Class.forName(calendarClassName);
633            if (Calendar.class.isAssignableFrom(calendarClass))
634              cache.put(locale, calendarClass);
635          }
636
637        // GregorianCalendar is by far the most common case. Optimize by 
638        // avoiding reflection.
639        if (calendarClass == GregorianCalendar.class)
640          return new GregorianCalendar(zone, locale);
641
642        if (Calendar.class.isAssignableFrom(calendarClass))
643          {
644            Constructor ctor = calendarClass.getConstructor(ctorArgTypes);
645            return (Calendar) ctor.newInstance(new Object[] { zone, locale });
646          }
647      }
648    catch (ClassNotFoundException ex)
649      {
650        exception = ex;
651      }
652    catch (IllegalAccessException ex)
653      {
654        exception = ex;
655      }
656    catch (NoSuchMethodException ex)
657      {
658        exception = ex;
659      }
660    catch (InstantiationException ex)
661      {
662        exception = ex;
663      }
664    catch (InvocationTargetException ex)
665      {
666        exception = ex;
667      }
668
669    throw new RuntimeException("Error instantiating calendar for locale "
670                               + locale, exception);
671  }
672
673  /**
674   * Gets the set of locales for which a Calendar is available.
675   * @exception MissingResourceException if locale data couldn't be found.
676   * @return the set of locales.
677   */
678  public static synchronized Locale[] getAvailableLocales()
679  {
680    ResourceBundle rb = getBundle(new Locale("", ""));
681    return (Locale[]) rb.getObject("availableLocales");
682  }
683
684  /**
685   * Converts the time field values (<code>fields</code>) to
686   * milliseconds since the epoch UTC (<code>time</code>).  Override
687   * this method if you write your own Calendar.  */
688  protected abstract void computeTime();
689
690  /**
691   * Converts the milliseconds since the epoch UTC
692   * (<code>time</code>) to time fields
693   * (<code>fields</code>). Override this method if you write your
694   * own Calendar.
695   */
696  protected abstract void computeFields();
697
698  /**
699   * Converts the time represented by this object to a
700   * <code>Date</code>-Object.
701   * @return the Date.
702   */
703  public final Date getTime()
704  {
705    if (! isTimeSet)
706      computeTime();
707    return new Date(time);
708  }
709
710  /**
711   * Sets this Calendar's time to the given Date.  All time fields
712   * are invalidated by this method.
713   * 
714   * @param date  the date (<code>null</code> not permitted).
715   * 
716   * @throws NullPointerException if <code>date</code> is <code>null</code>.
717   */
718  public final void setTime(Date date)
719  {
720    setTimeInMillis(date.getTime());
721  }
722
723  /**
724   * Returns the time represented by this Calendar.
725   * @return the time in milliseconds since the epoch.
726   * @specnote This was made public in 1.4.
727   */
728  public long getTimeInMillis()
729  {
730    if (! isTimeSet)
731      computeTime();
732    return time;
733  }
734
735  /**
736   * Sets this Calendar's time to the given Time.  All time fields
737   * are invalidated by this method.
738   * @param time the time in milliseconds since the epoch
739   * @specnote This was made public in 1.4.
740   */
741  public void setTimeInMillis(long time)
742  {
743    clear();
744    this.time = time;
745    isTimeSet = true;
746    computeFields();
747  }
748
749  /**
750   * Gets the value of the specified field.  They are recomputed
751   * if they are invalid.
752   * @param field the time field. One of the time field constants.
753   * @return the value of the specified field
754   * @throws ArrayIndexOutOfBoundsException if the field is outside
755   *         the valid range.  The value of field must be >= 0 and
756   *         <= <code>FIELD_COUNT</code>.
757   * @specnote Not final since JDK 1.4
758   */
759  public int get(int field)
760  {
761    // If the requested field is invalid, force all fields to be recomputed.
762    if (! isSet[field])
763      areFieldsSet = false;
764    complete();
765    return fields[field];
766  }
767
768  /**
769   * Gets the value of the specified field. This method doesn't
770   * recompute the fields, if they are invalid.
771   * @param field the time field. One of the time field constants.
772   * @return the value of the specified field, undefined if
773   * <code>areFieldsSet</code> or <code>isSet[field]</code> is false.
774   * @throws ArrayIndexOutOfBoundsException if the field is outside
775   *         the valid range.  The value of field must be >= 0 and
776   *         <= <code>FIELD_COUNT</code>.
777   */
778  protected final int internalGet(int field)
779  {
780    return fields[field];
781  }
782
783  /**
784   * Sets the time field with the given value.  This does invalidate
785   * the time in milliseconds.
786   * @param field the time field. One of the time field constants
787   * @param value the value to be set.
788   * @throws ArrayIndexOutOfBoundsException if field is outside
789   *         the valid range.  The value of field must be >= 0 and
790   *         <= <code>FIELD_COUNT</code>.
791   * @specnote Not final since JDK 1.4
792   */
793  public void set(int field, int value)
794  {
795    if (isTimeSet)
796      for (int i = 0; i < FIELD_COUNT; i++)
797        isSet[i] = false;
798    isTimeSet = false;
799    fields[field] = value;
800    isSet[field] = true;
801
802    // The five valid date patterns, in order of priority
803    // 1  YEAR + MONTH + DAY_OF_MONTH
804    // 2  YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
805    // 3  YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
806    // 4  YEAR + DAY_OF_YEAR
807    // 5  YEAR + DAY_OF_WEEK + WEEK_OF_YEAR
808    switch (field)
809      {
810      case MONTH: // pattern 1,2 or 3
811        isSet[DAY_OF_YEAR] = false;
812        isSet[WEEK_OF_YEAR] = false;
813        break;
814      case DAY_OF_MONTH: // pattern 1
815        isSet[YEAR] = true;
816        isSet[MONTH] = true;
817        isSet[WEEK_OF_MONTH] = true;
818        isSet[DAY_OF_WEEK] = false;
819        isSet[DAY_OF_WEEK_IN_MONTH] = false;
820        isSet[DAY_OF_YEAR] = false;
821        isSet[WEEK_OF_YEAR] = false;
822        break;
823      case WEEK_OF_MONTH: // pattern 2
824        if (! isSet[DAY_OF_WEEK])
825          fields[DAY_OF_WEEK] = getFirstDayOfWeek();
826        isSet[YEAR] = true;
827        isSet[MONTH] = true;
828        isSet[DAY_OF_WEEK] = true;
829        isSet[DAY_OF_MONTH] = false;
830        isSet[DAY_OF_WEEK_IN_MONTH] = false;
831        isSet[DAY_OF_YEAR] = false;
832        isSet[WEEK_OF_YEAR] = false;
833        break;
834      case DAY_OF_WEEK_IN_MONTH: // pattern 3
835        if (! isSet[DAY_OF_WEEK])
836          fields[DAY_OF_WEEK] = getFirstDayOfWeek();
837        isSet[YEAR] = true;
838        isSet[MONTH] = true;
839        isSet[DAY_OF_WEEK] = true;
840        isSet[DAY_OF_YEAR] = false;
841        isSet[DAY_OF_MONTH] = false;
842        isSet[WEEK_OF_MONTH] = false;
843        isSet[WEEK_OF_YEAR] = false;
844        break;
845      case DAY_OF_YEAR: // pattern 4
846        isSet[YEAR] = true;
847        isSet[MONTH] = false;
848        isSet[WEEK_OF_MONTH] = false;
849        isSet[DAY_OF_MONTH] = false;
850        isSet[DAY_OF_WEEK] = false;
851        isSet[WEEK_OF_YEAR] = false;
852        isSet[DAY_OF_WEEK_IN_MONTH] = false;
853        break;
854      case WEEK_OF_YEAR: // pattern 5
855        if (! isSet[DAY_OF_WEEK])
856          fields[DAY_OF_WEEK] = getFirstDayOfWeek();
857        isSet[YEAR] = true;
858        isSet[DAY_OF_WEEK] = true;
859        isSet[MONTH] = false;
860        isSet[DAY_OF_MONTH] = false;
861        isSet[WEEK_OF_MONTH] = false;
862        isSet[DAY_OF_YEAR] = false;
863        isSet[DAY_OF_WEEK_IN_MONTH] = false;
864        break;
865      case AM_PM:
866        isSet[HOUR] = true;
867        isSet[HOUR_OF_DAY] = false;
868        break;
869      case HOUR_OF_DAY:
870        isSet[AM_PM] = false;
871        isSet[HOUR] = false;
872        break;
873      case HOUR:
874        isSet[AM_PM] = true;
875        isSet[HOUR_OF_DAY] = false;
876        break;
877      case DST_OFFSET:
878        explicitDSTOffset = true;
879      }
880
881    // May have crossed over a DST boundary.
882    if (! explicitDSTOffset && (field != DST_OFFSET && field != ZONE_OFFSET))
883      isSet[DST_OFFSET] = false;
884  }
885
886  /**
887   * Sets the fields for year, month, and date
888   * @param year the year.
889   * @param month the month, one of the constants JANUARY..UNDICEMBER.
890   * @param date the day of the month
891   */
892  public final void set(int year, int month, int date)
893  {
894    isTimeSet = false;
895    fields[YEAR] = year;
896    fields[MONTH] = month;
897    fields[DATE] = date;
898    isSet[YEAR] = isSet[MONTH] = isSet[DATE] = true;
899    isSet[WEEK_OF_YEAR] = false;
900    isSet[DAY_OF_YEAR] = false;
901    isSet[WEEK_OF_MONTH] = false;
902    isSet[DAY_OF_WEEK] = false;
903    isSet[DAY_OF_WEEK_IN_MONTH] = false;
904    isSet[ERA] = false;
905
906    if (! explicitDSTOffset)
907      isSet[DST_OFFSET] = false; // May have crossed a DST boundary.
908  }
909
910  /**
911   * Sets the fields for year, month, date, hour, and minute
912   * @param year the year.
913   * @param month the month, one of the constants JANUARY..UNDICEMBER.
914   * @param date the day of the month
915   * @param hour the hour of day.
916   * @param minute the minute.
917   */
918  public final void set(int year, int month, int date, int hour, int minute)
919  {
920    set(year, month, date);
921    fields[HOUR_OF_DAY] = hour;
922    fields[MINUTE] = minute;
923    isSet[HOUR_OF_DAY] = isSet[MINUTE] = true;
924    isSet[AM_PM] = false;
925    isSet[HOUR] = false;
926  }
927
928  /**
929   * Sets the fields for year, month, date, hour, and minute
930   * @param year the year.
931   * @param month the month, one of the constants JANUARY..UNDICEMBER.
932   * @param date the day of the month
933   * @param hour the hour of day.
934   * @param minute the minute.
935   * @param second the second.
936   */
937  public final void set(int year, int month, int date, int hour, int minute,
938                        int second)
939  {
940    set(year, month, date, hour, minute);
941    fields[SECOND] = second;
942    isSet[SECOND] = true;
943  }
944
945  /**
946   * Clears the values of all the time fields.
947   */
948  public final void clear()
949  {
950    isTimeSet = false;
951    areFieldsSet = false;
952    int zoneOffs = zone.getRawOffset();
953    int[] tempFields = 
954                       {
955                         1, 1970, JANUARY, 1, 1, 1, 1, THURSDAY, 1, AM, 0, 0, 0,
956                         0, 0, zoneOffs, 0
957                       };
958    fields = tempFields;
959    for (int i = 0; i < FIELD_COUNT; i++)
960      isSet[i] = false;
961  }
962
963  /**
964   * Clears the values of the specified time field.
965   * @param field the time field. One of the time field constants.
966   * @throws ArrayIndexOutOfBoundsException if field is outside
967   *         the valid range.  The value of field must be >= 0 and
968   *         <= <code>FIELD_COUNT</code>.
969   */
970  public final void clear(int field)
971  {
972    int[] tempFields = 
973                       {
974                         1, 1970, JANUARY, 1, 1, 1, 1, THURSDAY, 1, AM, 0, 0, 0,
975                         0, 0, zone.getRawOffset(), 0
976                       };
977    complete();
978    isTimeSet = false;
979    areFieldsSet = false;
980    isSet[field] = false;
981    fields[field] = tempFields[field];
982  }
983
984  /**
985   * Determines if the specified field has a valid value.
986   * @return true if the specified field has a value.
987   * @throws ArrayIndexOutOfBoundsException if the field is outside
988   *         the valid range.  The value of field must be >= 0 and
989   *         <= <code>FIELD_COUNT</code>.
990   */
991  public final boolean isSet(int field)
992  {
993    return isSet[field];
994  }
995
996  /**
997   * Fills any unset fields in the time field list
998   */
999  protected void complete()
1000  {
1001    if (! isTimeSet)
1002      computeTime();
1003    if (! areFieldsSet)
1004      computeFields();
1005  }
1006
1007  /**
1008   * Compares the given calendar with this.
1009   * @param o the object to that we should compare.
1010   * @return true, if the given object is a calendar, that represents
1011   * the same time (but doesn't necessary have the same fields).
1012   */
1013  public boolean equals(Object o)
1014  {
1015    if (! (o instanceof Calendar))
1016      return false;
1017    Calendar cal = (Calendar) o;
1018    if (getTimeInMillis() == ((Calendar) o).getTimeInMillis()
1019        && cal.getFirstDayOfWeek() == getFirstDayOfWeek()
1020        && cal.isLenient() == isLenient()
1021        && cal.getMinimalDaysInFirstWeek() == getMinimalDaysInFirstWeek())
1022      {
1023        TimeZone self = getTimeZone();
1024        TimeZone oth = cal.getTimeZone();
1025        return self == null ? oth == null : self.equals(oth);
1026      }
1027    return false;
1028  }
1029
1030  /**
1031   * Returns a hash code for this calendar.
1032   * @return a hash code, which fullfits the general contract of
1033   * <code>hashCode()</code>
1034   */
1035  public int hashCode()
1036  {
1037    long time = getTimeInMillis();
1038    int val = (int) ((time & 0xffffffffL) ^ (time >> 32));
1039    val += (getFirstDayOfWeek() + (isLenient() ? 1230 : 1237)
1040            + getMinimalDaysInFirstWeek());
1041    TimeZone self = getTimeZone();
1042    if (self != null)
1043      val ^= self.hashCode();
1044    return val;
1045  }
1046
1047  /**
1048   * Compares the given calendar with this.
1049   * @param o the object to that we should compare.
1050   * @return true, if the given object is a calendar, and this calendar
1051   * represents a smaller time than the calendar o.
1052   * @exception ClassCastException if o is not an calendar.
1053   * @since JDK1.2 you don't need to override this method
1054   */
1055  public boolean before(Object o)
1056  {
1057    return getTimeInMillis() < ((Calendar) o).getTimeInMillis();
1058  }
1059
1060  /**
1061   * Compares the given calendar with this.
1062   * @param o the object to that we should compare.
1063   * @return true, if the given object is a calendar, and this calendar
1064   * represents a bigger time than the calendar o.
1065   * @exception ClassCastException if o is not an calendar.
1066   * @since JDK1.2 you don't need to override this method
1067   */
1068  public boolean after(Object o)
1069  {
1070    return getTimeInMillis() > ((Calendar) o).getTimeInMillis();
1071  }
1072
1073  /**
1074   * Adds the specified amount of time to the given time field.  The
1075   * amount may be negative to subtract the time.  If the field overflows
1076   * it does what you expect: Jan, 25 + 10 Days is Feb, 4.
1077   * @param field the time field. One of the time field constants.
1078   * @param amount the amount of time.
1079   * @throws ArrayIndexOutOfBoundsException if the field is outside
1080   *         the valid range.  The value of field must be >= 0 and
1081   *         <= <code>FIELD_COUNT</code>.
1082   */
1083  public abstract void add(int field, int amount);
1084
1085  /**
1086   * Rolls the specified time field up or down.  This means add one
1087   * to the specified field, but don't change the other fields.  If
1088   * the maximum for this field is reached, start over with the
1089   * minimum value.  <br>
1090   *
1091   * <strong>Note:</strong> There may be situation, where the other
1092   * fields must be changed, e.g rolling the month on May, 31.
1093   * The date June, 31 is automatically converted to July, 1.
1094   * @param field the time field. One of the time field constants.
1095   * @param up the direction, true for up, false for down.
1096   * @throws ArrayIndexOutOfBoundsException if the field is outside
1097   *         the valid range.  The value of field must be >= 0 and
1098   *         <= <code>FIELD_COUNT</code>.
1099   */
1100  public abstract void roll(int field, boolean up);
1101
1102  /**
1103   * Rolls up or down the specified time field by the given amount.
1104   * A negative amount rolls down.  The default implementation is
1105   * call <code>roll(int, boolean)</code> for the specified amount.
1106   *
1107   * Subclasses should override this method to do more intuitiv things.
1108   *
1109   * @param field the time field. One of the time field constants.
1110   * @param amount the amount to roll by, positive for rolling up,
1111   * negative for rolling down.
1112   * @throws ArrayIndexOutOfBoundsException if the field is outside
1113   *         the valid range.  The value of field must be >= 0 and
1114   *         <= <code>FIELD_COUNT</code>.
1115   * @since JDK1.2
1116   */
1117  public void roll(int field, int amount)
1118  {
1119    while (amount > 0)
1120      {
1121        roll(field, true);
1122        amount--;
1123      }
1124    while (amount < 0)
1125      {
1126        roll(field, false);
1127        amount++;
1128      }
1129  }
1130
1131  /**
1132   * Sets the time zone to the specified value.
1133   * @param zone the new time zone
1134   */
1135  public void setTimeZone(TimeZone zone)
1136  {
1137    this.zone = zone;
1138    computeTime();
1139    computeFields();
1140  }
1141
1142  /**
1143   * Gets the time zone of this calendar
1144   * @return the current time zone.
1145   */
1146  public TimeZone getTimeZone()
1147  {
1148    return zone;
1149  }
1150
1151  /**
1152   * Specifies if the date/time interpretation should be lenient.
1153   * If the flag is set, a date such as "February 30, 1996" will be
1154   * treated as the 29th day after the February 1.  If this flag
1155   * is false, such dates will cause an exception.
1156   * @param lenient true, if the date should be interpreted linient,
1157   * false if it should be interpreted strict.
1158   */
1159  public void setLenient(boolean lenient)
1160  {
1161    this.lenient = lenient;
1162  }
1163
1164  /**
1165   * Tells if the date/time interpretation is lenient.
1166   * @return true, if the date should be interpreted linient,
1167   * false if it should be interpreted strict.
1168   */
1169  public boolean isLenient()
1170  {
1171    return lenient;
1172  }
1173
1174  /**
1175   * Sets what the first day of week is.  This is used for
1176   * WEEK_OF_MONTH and WEEK_OF_YEAR fields.
1177   * @param value the first day of week.  One of SUNDAY to SATURDAY.
1178   */
1179  public void setFirstDayOfWeek(int value)
1180  {
1181    firstDayOfWeek = value;
1182  }
1183
1184  /**
1185   * Gets what the first day of week is.  This is used for
1186   * WEEK_OF_MONTH and WEEK_OF_YEAR fields.
1187   * @return the first day of week.  One of SUNDAY to SATURDAY.
1188   */
1189  public int getFirstDayOfWeek()
1190  {
1191    return firstDayOfWeek;
1192  }
1193
1194  /**
1195   * Sets how many days are required in the first week of the year.
1196   * If the first day of the year should be the first week you should
1197   * set this value to 1.  If the first week must be a full week, set
1198   * it to 7.
1199   * @param value the minimal days required in the first week.
1200   */
1201  public void setMinimalDaysInFirstWeek(int value)
1202  {
1203    minimalDaysInFirstWeek = value;
1204  }
1205
1206  /**
1207   * Gets how many days are required in the first week of the year.
1208   * @return the minimal days required in the first week.
1209   * @see #setMinimalDaysInFirstWeek
1210   */
1211  public int getMinimalDaysInFirstWeek()
1212  {
1213    return minimalDaysInFirstWeek;
1214  }
1215
1216  /**
1217   * Gets the smallest value that is allowed for the specified field.
1218   * @param field the time field. One of the time field constants.
1219   * @return the smallest value.
1220   */
1221  public abstract int getMinimum(int field);
1222
1223  /**
1224   * Gets the biggest value that is allowed for the specified field.
1225   * @param field the time field. One of the time field constants.
1226   * @return the biggest value.
1227   */
1228  public abstract int getMaximum(int field);
1229
1230  /**
1231   * Gets the greatest minimum value that is allowed for the specified field.
1232   * @param field the time field. One of the time field constants.
1233   * @return the greatest minimum value.
1234   */
1235  public abstract int getGreatestMinimum(int field);
1236
1237  /**
1238   * Gets the smallest maximum value that is allowed for the
1239   * specified field.  For example this is 28 for DAY_OF_MONTH.
1240   * @param field the time field. One of the time field constants.
1241   * @return the least maximum value.
1242   */
1243  public abstract int getLeastMaximum(int field);
1244
1245  /**
1246   * Gets the actual minimum value that is allowed for the specified field.
1247   * This value is dependent on the values of the other fields.
1248   * @param field the time field. One of the time field constants.
1249   * @return the actual minimum value.
1250   * @throws ArrayIndexOutOfBoundsException if the field is outside
1251   *         the valid range.  The value of field must be >= 0 and
1252   *         <= <code>FIELD_COUNT</code>.
1253   * @since jdk1.2
1254   */
1255  public int getActualMinimum(int field)
1256  {
1257    Calendar tmp = (Calendar) clone(); // To avoid restoring state
1258    int min = tmp.getGreatestMinimum(field);
1259    int end = tmp.getMinimum(field);
1260    tmp.set(field, min);
1261    for (; min > end; min--)
1262      {
1263        tmp.add(field, -1); // Try to get smaller
1264        if (tmp.get(field) != min - 1)
1265          break; // Done if not successful
1266      }
1267    return min;
1268  }
1269
1270  /**
1271   * Gets the actual maximum value that is allowed for the specified field.
1272   * This value is dependent on the values of the other fields.
1273   * @param field the time field. One of the time field constants.
1274   * @return the actual maximum value.
1275   * @throws ArrayIndexOutOfBoundsException if the field is outside
1276   *         the valid range.  The value of field must be >= 0 and
1277   *         <= <code>FIELD_COUNT</code>.
1278   * @since jdk1.2
1279   */
1280  public int getActualMaximum(int field)
1281  {
1282    Calendar tmp = (Calendar) clone(); // To avoid restoring state
1283    int max = tmp.getLeastMaximum(field);
1284    int end = tmp.getMaximum(field);
1285    tmp.set(field, max);
1286    for (; max < end; max++)
1287      {
1288        tmp.add(field, 1);
1289        if (tmp.get(field) != max + 1)
1290          break;
1291      }
1292    return max;
1293  }
1294
1295  /**
1296   * Compares the time of two calendar instances.
1297   * @param cal the calendar to which the time should be compared.
1298   * @return 0 if the two calendars are set to the same time, 
1299   * less than 0 if the time of this calendar is before that of 
1300   * <code>cal</code>, or more than 0 if the time of this calendar is after
1301   * that of <code>cal</code>.
1302   *
1303   * @param cal the calendar to compare this instance with.
1304   * @throws NullPointerException if <code>cal</code> is null.
1305   * @throws IllegalArgumentException if either calendar has fields set to 
1306   * invalid values.
1307   * @since 1.5
1308   */
1309  public int compareTo(Calendar cal)
1310  {
1311    long t1 = getTimeInMillis();
1312    long t2 = cal.getTimeInMillis();
1313    if(t1 == t2)
1314      return 0;
1315    if(t1 > t2)
1316      return 1;
1317    return -1;
1318  }
1319
1320  /**
1321   * Return a clone of this object.
1322   */
1323  public Object clone()
1324  {
1325    try
1326      {
1327        Calendar cal = (Calendar) super.clone();
1328        cal.fields = (int[]) fields.clone();
1329        cal.isSet = (boolean[]) isSet.clone();
1330        return cal;
1331      }
1332    catch (CloneNotSupportedException ex)
1333      {
1334        return null;
1335      }
1336  }
1337
1338  private static final String[] fieldNames = 
1339                                             {
1340                                               ",ERA=", ",YEAR=", ",MONTH=",
1341                                               ",WEEK_OF_YEAR=",
1342                                               ",WEEK_OF_MONTH=",
1343                                               ",DAY_OF_MONTH=",
1344                                               ",DAY_OF_YEAR=", ",DAY_OF_WEEK=",
1345                                               ",DAY_OF_WEEK_IN_MONTH=",
1346                                               ",AM_PM=", ",HOUR=",
1347                                               ",HOUR_OF_DAY=", ",MINUTE=",
1348                                               ",SECOND=", ",MILLISECOND=",
1349                                               ",ZONE_OFFSET=", ",DST_OFFSET="
1350                                             };
1351
1352  /**
1353   * Returns a string representation of this object.  It is mainly
1354   * for debugging purposes and its content is implementation
1355   * specific.
1356   */
1357  public String toString()
1358  {
1359    CPStringBuilder sb = new CPStringBuilder(getClass().getName());
1360    sb.append('[');
1361    sb.append("time=");
1362    if (isTimeSet)
1363      sb.append(time);
1364    else
1365      sb.append("?");
1366    sb.append(",zone=" + zone);
1367    sb.append(",areFieldsSet=" + areFieldsSet);
1368    for (int i = 0; i < FIELD_COUNT; i++)
1369      {
1370        sb.append(fieldNames[i]);
1371        if (isSet[i])
1372          sb.append(fields[i]);
1373        else
1374          sb.append("?");
1375      }
1376    sb.append(",lenient=").append(lenient);
1377    sb.append(",firstDayOfWeek=").append(firstDayOfWeek);
1378    sb.append(",minimalDaysInFirstWeek=").append(minimalDaysInFirstWeek);
1379    sb.append("]");
1380    return sb.toString();
1381  }
1382
1383  /**
1384   * Saves the state of the object to the stream.  Ideally we would
1385   * only write the time field, but we need to be compatible with
1386   * earlier versions. <br>
1387   *
1388   * This doesn't write the JDK1.1 field nextStamp to the stream, as
1389   * I don't know what it is good for, and because the documentation
1390   * says, that it could be omitted.  */
1391  private void writeObject(ObjectOutputStream stream) throws IOException
1392  {
1393    if (! isTimeSet)
1394      computeTime();
1395    stream.defaultWriteObject();
1396  }
1397
1398  /**
1399   * Reads the object back from stream (deserialization).
1400   */
1401  private void readObject(ObjectInputStream stream)
1402    throws IOException, ClassNotFoundException
1403  {
1404    stream.defaultReadObject();
1405    if (! isTimeSet)
1406      computeTime();
1407
1408    if (serialVersionOnStream > 1)
1409      {
1410        // This is my interpretation of the serial number:
1411        // Sun wants to remove all fields from the stream someday
1412        // and will then increase the serialVersion number again.
1413        // We prepare to be compatible.
1414        fields = new int[FIELD_COUNT];
1415        isSet = new boolean[FIELD_COUNT];
1416        areFieldsSet = false;
1417      }
1418  }
1419
1420  /**
1421   * Returns a localised textual representation of the current value
1422   * of the given field using the specified style.  If there is no
1423   * applicable textual representation (e.g. the field has a numeric
1424   * value), then <code>null</code> is returned.  If one does exist,
1425   * then the value is obtained from {@link #get(int)} and converted
1426   * appropriately.  For example, if the <code>MONTH</code> field is
1427   * requested, then <code>get(MONTH)</code> is called.  This is then
1428   * converted to a textual representation based on its value and
1429   * the style requested; if the <code>LONG</code> style is requested
1430   * and the returned value is <code>11</code> from a
1431   * {@link GregorianCalendar} implementation, then <code>"December"</code>
1432   * is returned.  By default, a textual representation is available
1433   * for all fields which have an applicable value obtainable from
1434   * {@link java.text.DateFormatSymbols}.
1435   *
1436   * @param field the calendar field whose textual representation should
1437   *              be obtained.
1438   * @param style the style to use; either {@link #LONG} or {@link #SHORT}.
1439   * @param locale the locale to use for translation.
1440   * @return the textual representation of the given field in the specified
1441   *         style, or <code>null</code> if none is applicable.
1442   * @throws IllegalArgumentException if <code>field</code> or <code>style</code>
1443   *                                  or invalid, or the calendar is non-lenient
1444   *                                  and has invalid values.
1445   * @throws NullPointerException if <code>locale</code> is <code>null</code>.
1446   * @since 1.6
1447   */
1448  public String getDisplayName(int field, int style, Locale locale)
1449  {
1450    if (field < 0 || field >= FIELD_COUNT)
1451      throw new IllegalArgumentException("The field value, " + field +
1452                                         ", is invalid.");
1453    if (style != SHORT && style != LONG)
1454      throw new IllegalArgumentException("The style must be either " +
1455                                         "short or long.");
1456    if (field == YEAR || field == WEEK_OF_YEAR ||
1457        field == WEEK_OF_MONTH || field == DAY_OF_MONTH ||
1458        field == DAY_OF_YEAR || field == DAY_OF_WEEK_IN_MONTH ||
1459        field == HOUR || field == HOUR_OF_DAY || field == MINUTE ||
1460        field == SECOND || field == MILLISECOND)
1461      return null;
1462
1463    int value = get(field);
1464    DateFormatSymbols syms = DateFormatSymbols.getInstance(locale);
1465    if (field == ERA)
1466      return syms.getEras()[value];
1467    if (field == MONTH)
1468      if (style == LONG)
1469        return syms.getMonths()[value];
1470      else 
1471        return syms.getShortMonths()[value];
1472    if (field == DAY_OF_WEEK)
1473      if (style == LONG)
1474        return syms.getWeekdays()[value];
1475      else
1476        return syms.getShortWeekdays()[value];
1477    if (field == AM_PM)
1478      return syms.getAmPmStrings()[value];
1479    if (field == ZONE_OFFSET)
1480      if (style == LONG)
1481        return syms.getZoneStrings()[value][1];
1482      else
1483        return syms.getZoneStrings()[value][2];
1484    if (field == DST_OFFSET)
1485      if (style == LONG)
1486        return syms.getZoneStrings()[value][3];
1487      else
1488        return syms.getZoneStrings()[value][4];
1489
1490    throw new InternalError("Failed to resolve field " + field +
1491                            " with style " + style + " for locale " +
1492                            locale);
1493  }
1494
1495  /**
1496   * Returns a map linking all specified textual representations
1497   * of the given field to their numerical values.  The textual
1498   * representations included are determined by the specified
1499   * style and locale.  For example, if the style <code>LONG</code>
1500   * is specified and the German locale, then the map will
1501   * contain "Montag" to {@link #MONDAY}, "Dienstag" to
1502   * {@link #TUESDAY}, "Mittwoch" to {@link #WEDNESDAY} and
1503   * so on.  The default implementation uses the values returned
1504   * by {@link DateFormatSymbols} so, for example, the style
1505   * {@link #ALL_STYLES} and the field {@link #MONTH} will return
1506   * a map filled with the values returned from
1507   * {@link DateFormatSymbols#getMonths()} and
1508   * {@link DateFormatSymbols#getShortMonths()}.  If there are
1509   * no textual representations for a given field (usually because
1510   * it is purely numeric, such as the year in the
1511   * {@link GregorianCalendar}), <code>null</code> is returned.
1512   *
1513   * @param field the calendar field whose textual representation should
1514   *              be obtained.
1515   * @param style the style to use; either {@link #LONG}, {@link #SHORT}
1516   *              or {@link ALL_STYLES}.
1517   * @param locale the locale to use for translation.
1518   * @return a map of the textual representations of the given field in the
1519   *         specified style to their numeric values, or <code>null</code>
1520   *         if none is applicable.
1521   * @throws IllegalArgumentException if <code>field</code> or <code>style</code>
1522   *                                  or invalid, or the calendar is non-lenient
1523   *                                  and has invalid values.
1524   * @throws NullPointerException if <code>locale</code> is <code>null</code>.
1525   * @since 1.6
1526   */
1527  public Map<String,Integer> getDisplayNames(int field, int style, Locale locale)
1528  {
1529    if (field < 0 || field >= FIELD_COUNT)
1530      throw new IllegalArgumentException("The field value, " + field +
1531                                         ", is invalid.");
1532    if (style != SHORT && style != LONG && style != ALL_STYLES)
1533      throw new IllegalArgumentException("The style must be either " +
1534                                         "short, long or all styles.");
1535    if (field == YEAR || field == WEEK_OF_YEAR ||
1536        field == WEEK_OF_MONTH || field == DAY_OF_MONTH ||
1537        field == DAY_OF_YEAR || field == DAY_OF_WEEK_IN_MONTH ||
1538        field == HOUR || field == HOUR_OF_DAY || field == MINUTE ||
1539        field == SECOND || field == MILLISECOND)
1540      return null;
1541
1542    DateFormatSymbols syms = DateFormatSymbols.getInstance(locale);
1543    Map<String,Integer> map = new HashMap<String,Integer>();
1544    if (field == ERA)
1545      {
1546        String[] eras = syms.getEras();
1547        for (int a = 0; a < eras.length; ++a)
1548          map.put(eras[a], a);
1549        return map;
1550      }
1551    if (field == MONTH)
1552      {
1553        if (style == LONG || style == ALL_STYLES)
1554          {
1555            String[] months = syms.getMonths();
1556            for (int a = 0; a < months.length; ++a)
1557              map.put(months[a], a);
1558          }
1559        if (style == SHORT || style == ALL_STYLES)
1560          {
1561            String[] months = syms.getShortMonths();
1562            for (int a = 0; a < months.length; ++a)
1563              map.put(months[a], a);
1564          }
1565        return map;
1566      }
1567    if (field == DAY_OF_WEEK)
1568      {
1569        if (style == LONG || style == ALL_STYLES)
1570          {
1571            String[] weekdays = syms.getWeekdays();
1572            for (int a = SUNDAY; a < weekdays.length; ++a)
1573              map.put(weekdays[a], a);
1574          }
1575        if (style == SHORT || style == ALL_STYLES)
1576          {
1577            String[] weekdays = syms.getShortWeekdays();
1578            for (int a = SUNDAY; a < weekdays.length; ++a)
1579              map.put(weekdays[a], a);
1580          }
1581        return map;
1582      }
1583    if (field == AM_PM)
1584      {
1585        String[] ampms = syms.getAmPmStrings();
1586        for (int a = 0; a < ampms.length; ++a)
1587          map.put(ampms[a], a);
1588        return map;
1589      }
1590    if (field == ZONE_OFFSET)
1591      {
1592        String[][] zones = syms.getZoneStrings();
1593        for (int a = 0; a < zones.length; ++a)
1594          {
1595            if (style == LONG || style == ALL_STYLES) 
1596              map.put(zones[a][1], a);
1597            if (style == SHORT || style == ALL_STYLES)
1598              map.put(zones[a][2], a);
1599          }
1600        return map;
1601      }
1602    if (field == DST_OFFSET)
1603      {
1604        String[][] zones = syms.getZoneStrings();
1605        for (int a = 0; a < zones.length; ++a)
1606          {
1607            if (style == LONG || style == ALL_STYLES) 
1608              map.put(zones[a][3], a);
1609            if (style == SHORT || style == ALL_STYLES)
1610              map.put(zones[a][4], a);
1611          }
1612        return map;
1613      }
1614    
1615    throw new InternalError("Failed to resolve field " + field +
1616                            " with style " + style + " for locale " +
1617                            locale);
1618  }
1619
1620}