001 /* Calendar.java --
002 Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004, 2005, 2006,
003 Free Software Foundation, Inc.
004
005 This file is part of GNU Classpath.
006
007 GNU Classpath is free software; you can redistribute it and/or modify
008 it under the terms of the GNU General Public License as published by
009 the Free Software Foundation; either version 2, or (at your option)
010 any later version.
011
012 GNU Classpath is distributed in the hope that it will be useful, but
013 WITHOUT ANY WARRANTY; without even the implied warranty of
014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 General Public License for more details.
016
017 You should have received a copy of the GNU General Public License
018 along with GNU Classpath; see the file COPYING. If not, write to the
019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020 02110-1301 USA.
021
022 Linking this library statically or dynamically with other modules is
023 making a combined work based on this library. Thus, the terms and
024 conditions of the GNU General Public License cover the whole
025 combination.
026
027 As a special exception, the copyright holders of this library give you
028 permission to link this library with independent modules to produce an
029 executable, regardless of the license terms of these independent
030 modules, and to copy and distribute the resulting executable under
031 terms of your choice, provided that you also meet, for each linked
032 independent module, the terms and conditions of the license of that
033 module. An independent module is a module which is not derived from
034 or based on this library. If you modify this library, you may extend
035 this exception to your version of the library, but you are not
036 obligated to do so. If you do not wish to do so, delete this
037 exception statement from your version. */
038
039
040 package java.util;
041
042 import gnu.java.lang.CPStringBuilder;
043
044 import java.io.IOException;
045 import java.io.ObjectInputStream;
046 import java.io.ObjectOutputStream;
047 import java.io.Serializable;
048
049 import java.lang.reflect.Constructor;
050 import java.lang.reflect.InvocationTargetException;
051
052 import 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
089 month + week_of_month + day_of_week
090 month + day_of_week_of_month + day_of_week
091 day_of_year
092 day_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 */
126 public 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 }