GregorianCalendar

Class Overview

GregorianCalendar is a concrete subclass of Calendar and provides the standard calendar used by most of the world.

The standard (Gregorian) calendar has 2 eras, BC and AD.

This implementation handles a single discontinuity, which corresponds by default to the date the Gregorian calendar was instituted (October 15, 1582 in some countries, later in others). The cutover date may be changed by the caller by calling setGregorianChange().

Historically, in those countries which adopted the Gregorian calendar first, October 4, 1582 was thus followed by October 15, 1582. This calendar models this correctly. Before the Gregorian cutover, GregorianCalendar implements the Julian calendar. The only difference between the Gregorian and the Julian calendar is the leap year rule. The Julian calendar specifies leap years every four years, whereas the Gregorian calendar omits century years which are not divisible by 400.

GregorianCalendar implements proleptic Gregorian and Julian calendars. That is, dates are computed by extrapolating the current rules indefinitely far backward and forward in time. As a result, GregorianCalendar may be used for all years to generate meaningful and consistent results. However, dates obtained using GregorianCalendar are historically accurate only from March 1, 4 AD onward, when modern Julian calendar rules were adopted. Before this date, leap year rules were applied irregularly, and before 45 BC the Julian calendar did not even exist.

Prior to the institution of the Gregorian calendar, New Year's Day was March 25. To avoid confusion, this calendar always uses January 1. A manual adjustment may be made if desired for dates that are prior to the Gregorian changeover and which fall between January 1 and March 24.

Values calculated for the WEEK_OF_YEAR field range from 1 to 53. Week 1 for a year is the earliest seven day period starting on getFirstDayOfWeek() that contains at least getMinimalDaysInFirstWeek() days from that year. It thus depends on the values of getMinimalDaysInFirstWeek(), getFirstDayOfWeek(), and the day of the week of January 1. Weeks between week 1 of one year and week 1 of the following year are numbered sequentially from 2 to 52 or 53 (as needed).

For example, January 1, 1998 was a Thursday. If getFirstDayOfWeek() is MONDAY and getMinimalDaysInFirstWeek() is 4 (these are the values reflecting ISO 8601 and many national standards), then week 1 of 1998 starts on December 29, 1997, and ends on January 4, 1998. If, however, getFirstDayOfWeek() is SUNDAY, then week 1 of 1998 starts on January 4, 1998, and ends on January 10, 1998; the first three days of 1998 then are part of week 53 of 1997.

Values calculated for the WEEK_OF_MONTH field range from 0 or 1 to 4 or 5. Week 1 of a month (the days with WEEK_OF_MONTH = 1) is the earliest set of at least getMinimalDaysInFirstWeek() contiguous days in that month, ending on the day before getFirstDayOfWeek(). Unlike week 1 of a year, week 1 of a month may be shorter than 7 days, need not start on getFirstDayOfWeek(), and will not include days of the previous month. Days of a month before week 1 have a WEEK_OF_MONTH of 0.

For example, if getFirstDayOfWeek() is SUNDAY and getMinimalDaysInFirstWeek() is 4, then the first week of January 1998 is Sunday, January 4 through Saturday, January 10. These days have a WEEK_OF_MONTH of 1. Thursday, January 1 through Saturday, January 3 have a WEEK_OF_MONTH of 0. If getMinimalDaysInFirstWeek() is changed to 3, then January 1 through January 3 have a WEEK_OF_MONTH of 1.

Example:

 // get the supported ids for GMT-08:00 (Pacific Standard Time)
 String[] ids = TimeZone.getAvailableIDs(-8 * 60 * 60 * 1000);
 // if no ids were returned, something is wrong. get out.
 if (ids.length == 0)
     System.exit(0);

  // begin output
 System.out.println("Current Time");

 // create a Pacific Standard Time time zone
 SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);

 // set up rules for daylight savings time
 pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
 pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);

 // create a GregorianCalendar with the Pacific Daylight time zone
 // and the current date and time
 Calendar calendar = new GregorianCalendar(pdt);
 Date trialTime = new Date();
 calendar.setTime(trialTime);

 // print out a bunch of interesting things
 System.out.println("ERA: " + calendar.get(Calendar.ERA));
 System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 System.out.println("DATE: " + calendar.get(Calendar.DATE));
 System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 System.out.println("DAY_OF_WEEK_IN_MONTH: "
                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 System.out.println("ZONE_OFFSET: "
                    + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000)));
 System.out.println("DST_OFFSET: "
                    + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000)));

 System.out.println("Current Time, with hour reset to 3");
 calendar.clear(Calendar.HOUR_OF_DAY); // so doesn't override
 calendar.set(Calendar.HOUR, 3);
 System.out.println("ERA: " + calendar.get(Calendar.ERA));
 System.out.println("YEAR: " + calendar.get(Calendar.YEAR));
 System.out.println("MONTH: " + calendar.get(Calendar.MONTH));
 System.out.println("WEEK_OF_YEAR: " + calendar.get(Calendar.WEEK_OF_YEAR));
 System.out.println("WEEK_OF_MONTH: " + calendar.get(Calendar.WEEK_OF_MONTH));
 System.out.println("DATE: " + calendar.get(Calendar.DATE));
 System.out.println("DAY_OF_MONTH: " + calendar.get(Calendar.DAY_OF_MONTH));
 System.out.println("DAY_OF_YEAR: " + calendar.get(Calendar.DAY_OF_YEAR));
 System.out.println("DAY_OF_WEEK: " + calendar.get(Calendar.DAY_OF_WEEK));
 System.out.println("DAY_OF_WEEK_IN_MONTH: "
                    + calendar.get(Calendar.DAY_OF_WEEK_IN_MONTH));
 System.out.println("AM_PM: " + calendar.get(Calendar.AM_PM));
 System.out.println("HOUR: " + calendar.get(Calendar.HOUR));
 System.out.println("HOUR_OF_DAY: " + calendar.get(Calendar.HOUR_OF_DAY));
 System.out.println("MINUTE: " + calendar.get(Calendar.MINUTE));
 System.out.println("SECOND: " + calendar.get(Calendar.SECOND));
 System.out.println("MILLISECOND: " + calendar.get(Calendar.MILLISECOND));
 System.out.println("ZONE_OFFSET: "
        + (calendar.get(Calendar.ZONE_OFFSET)/(60*60*1000))); // in hours
 System.out.println("DST_OFFSET: "
        + (calendar.get(Calendar.DST_OFFSET)/(60*60*1000))); // in hours
 

Summary

[Expand] Inherited Constants

From class java.util.Calendar int ALL_STYLES Requests both SHORT and LONG styles in the map returned by getDisplayNames(int, int, Locale). int AM Value of the AM_PM field indicating the period of the day from midnight to just before noon. int AM_PM Field number for get and set indicating whether the HOUR is before or after noon. int APRIL Value of the MONTH field indicating the fourth month of the year. int AUGUST Value of the MONTH field indicating the eighth month of the year. int DATE Field number for get and set indicating the day of the month. int DAY_OF_MONTH Field number for get and set indicating the day of the month. int DAY_OF_WEEK Field number for get and set indicating the day of the week. int DAY_OF_WEEK_IN_MONTH Field number for get and set indicating the ordinal number of the day of the week within the current month. int DAY_OF_YEAR Field number for get and set indicating the day number within the current year. int DECEMBER Value of the MONTH field indicating the twelfth month of the year. int DST_OFFSET Field number for get and set indicating the daylight savings offset in milliseconds. int ERA Field number for get and set indicating the era, e.g., AD or BC in the Julian calendar. int FEBRUARY Value of the MONTH field indicating the second month of the year. int FIELD_COUNT This is the total number of fields in this calendar. int FRIDAY Value of the DAY_OF_WEEK field indicating Friday. int HOUR Field number for get and set indicating the hour of the morning or afternoon. int HOUR_OF_DAY Field number for get and set indicating the hour of the day. int JANUARY Value of the MONTH field indicating the first month of the year. int JULY Value of the MONTH field indicating the seventh month of the year. int JUNE Value of the MONTH field indicating the sixth month of the year. int LONG Requests long names (such as "January") from getDisplayName(int, int, Locale) or getDisplayNames(int, int, Locale). int MARCH Value of the MONTH field indicating the third month of the year. int MAY Value of the MONTH field indicating the fifth month of the year. int MILLISECOND Field number for get and set indicating the millisecond within the second. int MINUTE Field number for get and set indicating the minute within the hour. int MONDAY Value of the DAY_OF_WEEK field indicating Monday. int MONTH Field number for get and set indicating the month. int NOVEMBER Value of the MONTH field indicating the eleventh month of the year. int OCTOBER Value of the MONTH field indicating the tenth month of the year. int PM Value of the AM_PM field indicating the period of the day from noon to just before midnight. int SATURDAY Value of the DAY_OF_WEEK field indicating Saturday. int SECOND Field number for get and set indicating the second within the minute. int SEPTEMBER Value of the MONTH field indicating the ninth month of the year. int SHORT Requests short names (such as "Jan") from getDisplayName(int, int, Locale) or getDisplayNames(int, int, Locale). int SUNDAY Value of the DAY_OF_WEEK field indicating Sunday. int THURSDAY Value of the DAY_OF_WEEK field indicating Thursday. int TUESDAY Value of the DAY_OF_WEEK field indicating Tuesday. int UNDECIMBER Value of the MONTH field indicating the thirteenth month of the year. int WEDNESDAY Value of the DAY_OF_WEEK field indicating Wednesday. int WEEK_OF_MONTH Field number for get and set indicating the week number within the current month. int WEEK_OF_YEAR Field number for get and set indicating the week number within the current year. int YEAR Field number for get and set indicating the year. int ZONE_OFFSET Field number for get and set indicating the raw offset from GMT in milliseconds.

[Expand] Inherited Fields

From class java.util.Calendar protected boolean areFieldsSet True iff the values in fields[] correspond to time. protected int[] fields Contains broken-down field values for the current value of time if areFieldsSet is true, or stale data corresponding to some previous value otherwise. protected boolean[] isSet Whether the corresponding element in field[] has been set. protected boolean isTimeSet Whether time corresponds to the values in fields[]. protected long time A time in milliseconds since January 1, 1970.

[Expand] Inherited Methods
From class java.util.Calendar abstract void add(int field, int value) Adds the specified amount to a Calendar field. boolean after(Object calendar) Returns whether the Date specified by this Calendar instance is after the Date specified by the parameter. boolean before(Object calendar) Returns whether the Date specified by this Calendar instance is before the Date specified by the parameter. final void clear(int field) Clears the specified field to zero and sets the isSet flag to false. final void clear() Clears all of the fields of this Calendar. Object clone() Returns a new Calendar with the same properties. int compareTo(Calendar anotherCalendar) Compares the times of the two Calendar, which represent the milliseconds from the January 1, 1970 00:00:00.000 GMT (Gregorian). void complete() Computes the time from the fields if the time has not already been set. abstract void computeFields() Computes the Calendar fields from time. abstract void computeTime() Computes time from the Calendar fields. boolean equals(Object object) Compares the specified object to this Calendar and returns whether they are equal. int get(int field) Gets the value of the specified field after computing the field values by calling complete() first. int getActualMaximum(int field) Gets the maximum value of the specified field for the current date. int getActualMinimum(int field) Gets the minimum value of the specified field for the current date. synchronized static Locale[] getAvailableLocales() Returns an array of locales for which custom Calendar instances are available. String getDisplayName(int field, int style, Locale locale) Returns a human-readable string for the value of field using the given style and locale. Map<String, Integer> getDisplayNames(int field, int style, Locale locale) Returns a map of human-readable strings to corresponding values, for the given field, style, and locale. int getFirstDayOfWeek() Gets the first day of the week for this Calendar. abstract int getGreatestMinimum(int field) Gets the greatest minimum value of the specified field. synchronized static Calendar getInstance(Locale locale) Constructs a new instance of the Calendar subclass appropriate for the specified Locale. synchronized static Calendar getInstance(TimeZone timezone, Locale locale) Constructs a new instance of the Calendar subclass appropriate for the specified Locale. synchronized static Calendar getInstance(TimeZone timezone) Constructs a new instance of the Calendar subclass appropriate for the default Locale, using the specified TimeZone. synchronized static Calendar getInstance() Constructs a new instance of the Calendar subclass appropriate for the default Locale. abstract int getLeastMaximum(int field) Gets the smallest maximum value of the specified field. abstract int getMaximum(int field) Gets the greatest maximum value of the specified field. int getMinimalDaysInFirstWeek() Gets the minimal days in the first week of the year. abstract int getMinimum(int field) Gets the smallest minimum value of the specified field. final Date getTime() Gets the time of this Calendar as a Date object. long getTimeInMillis() Computes the time from the fields if required and returns the time. TimeZone getTimeZone() Gets the timezone of this Calendar. int hashCode() Returns an integer hash code for the receiver. final int internalGet(int field) Gets the value of the specified field without recomputing. boolean isLenient() Returns if this Calendar accepts field values which are outside the valid range for the field. final boolean isSet(int field) Returns whether the specified field is set. void roll(int field, int value) Adds the specified amount to the specified field and wraps the value of the field when it goes beyond the maximum or minimum value for the current date. abstract void roll(int field, boolean increment) Increment or decrement the specified field and wrap the value of the field when it goes beyond the maximum or minimum value for the current date. void set(int field, int value) Sets a field to the specified value. final void set(int year, int month, int day, int hourOfDay, int minute, int second) Sets the year, month, day of the month, hour of day, minute and second fields. final void set(int year, int month, int day) Sets the year, month and day of the month fields. final void set(int year, int month, int day, int hourOfDay, int minute) Sets the year, month, day of the month, hour of day and minute fields. void setFirstDayOfWeek(int value) Sets the first day of the week for this Calendar. void setLenient(boolean value) Sets this Calendar to accept field values which are outside the valid range for the field. void setMinimalDaysInFirstWeek(int value) Sets the minimal days in the first week of the year. final void setTime(Date date) Sets the time of this Calendar. void setTimeInMillis(long milliseconds) Sets the time of this Calendar. void setTimeZone(TimeZone timezone) Sets the TimeZone used by this Calendar. String toString() Returns the string representation of this Calendar.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
From interface java.lang.Comparable abstract int compareTo(T another) Compares this object to the specified object to determine their relative order.