All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.util.Calendar

java.lang.Object
   |
   +----java.util.Calendar

public abstract class Calendar
extends Object
implements Serializable, Cloneable
Calendar is an abstract base class for converting between a Date object and a set of integer fields such as YEAR, MONTH, DAY, HOUR, and so on. (A Date object represents a specific instant in time with millisecond precision. See java.util.Date for information about the Date class.)

Subclasses of Calendar interpret a Date according to the rules of a specific calendar system. The JDK provides one concrete subclass of Calendar: GregorianCalendar. Future subclasses could represent the various types of lunar calendars in use in many parts of the world.

Like other locale-sensitive classes, Calendar provides a class method, getInstance, for getting a generally useful object of this type. Calendar's getInstance method returns a GregorianCalendar object whose time fields have been initialized with the current date and time:

 Calendar rightNow = Calendar.getInstance();
 

A Calendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).

When computing a Date from time fields, two special circumstances may arise: there may be insufficient information to compute the Date (such as only year and month but no day in the month), or there may be inconsistent information (such as "Tuesday, July 15, 1996" -- July 15, 1996 is actually a Monday).

Insufficient information. The calendar will use default information to specify the missing fields. This may vary by calendar; for the Gregorian calendar, the default for a field is the same as that of the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc.

Inconsistent information. If fields conflict, the calendar will give preference to fields set more recently. For example, when determining the day, the calendar will look for one of the following combinations of fields. The most recent combination, as determined by the most recently set single field, will be used.

 MONTH + DAY_OF_MONTH
 MONTH + WEEK_OF_MONTH + DAY_OF_WEEK
 MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK
 DAY_OF_YEAR
 DAY_OF_WEEK + WEEK_OF_YEAR
 
For the time of day:
 HOUR_OF_DAY
 AM_PM + HOUR
 

Note: for some non-Gregorian calendars, different fields may be necessary for complete disambiguation. For example, a full specification of the historial Arabic astronomical calendar requires year, month, day-of-month and day-of-week in some cases.

Note: There are certain possible ambiguities in interpretation of certain singular times, which are resolved in the following ways:

  1. 24:00:00 "belongs" to the following day. That is, 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
  2. Although historically not precise, midnight also belongs to "am", and noon belongs to "pm", so on the same day, 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm

The date or time format strings are not part of the definition of a calendar, as those must be modifiable or overridable by the user at runtime. Use java.text.DateFormat to format dates.

Calendar provides an API for field "rolling", where fields can be incremented or decremented, but wrap around. For example, rolling the month up in the date "September 12, 1996" results in "October 12, 1996".

Calendar also provides a date arithmetic function for adding the specified (signed) amount of time to a particular time field. For example, subtracting 5 days from the date "September 12, 1996" results in "September 7, 1996".

See Also:
Date, GregorianCalendar, TimeZone, DateFormat

Variable Index

 o AM
Useful constant for hour in 12-hour clock.
 o AM_PM
Useful constant for date and time.
 o APRIL
Useful constant for month.
 o areFieldsSet
True if the fields are in sync with the currently set time of this Calendar.
 o AUGUST
Useful constant for month.
 o DATE
Useful constant for date and time.
 o DAY_OF_MONTH
Useful constant for date and time.
 o DAY_OF_WEEK
Useful constant for date and time.
 o DAY_OF_WEEK_IN_MONTH
Useful constant for date and time.
 o DAY_OF_YEAR
Useful constant for date and time.
 o DECEMBER
Useful constant for month.
 o DST_OFFSET
Useful constant for date and time.
 o ERA
Useful constant for date and time.
 o FEBRUARY
Useful constant for month.
 o FIELD_COUNT
Useful constant for date and time.
 o fields
The time fields containing values into which the millis is computed.
 o FRIDAY
Useful constant for days of week.
 o HOUR
Useful constant for date and time.
 o HOUR_OF_DAY
Useful constant for date and time.
 o isSet
The flags which tell if a specified time field for the calendar is set.
 o isTimeSet
The flag which indicates if the current time is set for the calendar.
 o JANUARY
Useful constant for month.
 o JULY
Useful constant for month.
 o JUNE
Useful constant for month.
 o MARCH
Useful constant for month.
 o MAY
Useful constant for month.
 o MILLISECOND
Useful constant for date and time.
 o MINUTE
Useful constant for date and time.
 o MONDAY
Useful constant for days of week.
 o MONTH
Useful constant for date and time.
 o NOVEMBER
Useful constant for month.
 o OCTOBER
Useful constant for month.
 o PM
Useful constant for hour in 12-hour clock.
 o SATURDAY
Useful constant for days of week.
 o SECOND
Useful constant for date and time.
 o SEPTEMBER
Useful constant for month.
 o SUNDAY
Useful constant for days of week.
 o THURSDAY
Useful constant for days of week.
 o time
The current time set for the calendar.
 o TUESDAY
Useful constant for days of week.
 o UNDECIMBER
Useful constant for month.
 o WEDNESDAY
Useful constant for days of week.
 o WEEK_OF_MONTH
Useful constant for date and time.
 o WEEK_OF_YEAR
Useful constant for date and time.
 o YEAR
Useful constant for date and time.
 o ZONE_OFFSET
Useful constant for date and time.

Constructor Index

 o Calendar()
Constructs a Calendar with the default time zone as returned by TimeZone.getDefault(), and the default locale.
 o Calendar(TimeZone, Locale)
Constructs a Calendar with the given time zone and locale.

Method Index

 o add(int, int)
Date Arithmetic function.
 o after(Object)
Compares the time field records.
 o before(Object)
Compares the time field records.
 o clear()
Clears the values of all the time fields.
 o clear(int)
Clears the value in the given time field.
 o clone()
Overrides Cloneable
 o complete()
Fills in any unset fields in the time field list.
 o computeFields()
Converts UTC as milliseconds to time field values.
 o computeTime()
Converts Calendar's time field values to UTC as milliseconds.
 o equals(Object)
Compares this calendar to the specified object.
 o get(int)
Gets the value for a given time field.
 o getAvailableLocales()
Gets the set of locales for which Calendars are installed.
 o getFirstDayOfWeek()
Gets what the first day of the week is; e.g., Sunday in US, Monday in France.
 o getGreatestMinimum(int)
Gets the highest minimum value for the given field if varies.
 o getInstance()
Gets a Calendar using the default timezone and locale.
 o getInstance(Locale)
Gets a Calendar using the default timezone and given locale.
 o getInstance(TimeZone)
Gets a Calendar using the given timezone and default locale.
 o getInstance(TimeZone, Locale)
Gets a Calendar using the given timezone and given locale.
 o getLeastMaximum(int)
Gets the lowest maximum value for the given field if varies.
 o getMaximum(int)
Gets the maximum value for the given time field.
 o getMinimalDaysInFirstWeek()
Gets what the minimal days required in the first week of the year are; e.g., if the first week is defined as one that contains the first day of the first month of a year, getMinimalDaysInFirstWeek returns 1.
 o getMinimum(int)
Gets the minimum value for the given time field.
 o getTime()
Gets this Calendar's current time.
 o getTimeInMillis()
Gets this Calendar's current time as a long.
 o getTimeZone()
Gets the time zone.
 o internalGet(int)
Gets the value for a given time field.
 o isLenient()
Tell whether date/time interpretation is to be lenient.
 o isSet(int)
Determines if the given time field has a value set.
 o roll(int, boolean)
Time Field Rolling function.
 o set(int, int)
Sets the time field with the given value.
 o set(int, int, int)
Sets the values for the fields year, month, and date.
 o set(int, int, int, int, int)
Sets the values for the fields year, month, date, hour, and minute.
 o set(int, int, int, int, int, int)
Sets the values for the fields year, month, date, hour, minute, and second.
 o setFirstDayOfWeek(int)
Sets what the first day of the week is; e.g., Sunday in US, Monday in France.
 o setLenient(boolean)
Specify whether or not date/time interpretation is to be lenient.
 o setMinimalDaysInFirstWeek(int)
Sets what the minimal days required in the first week of the year are; For example, if the first week is defined as one that contains the first day of the first month of a year, call the method with value 1.
 o setTime(Date)
Sets this Calendar's current time with the given Date.
 o setTimeInMillis(long)
Sets this Calendar's current time from the given long value.
 o setTimeZone(TimeZone)
Sets the time zone with the given time zone value.
 o toString()
Return a string representation of this calendar.

Variables

 o ERA
 public static final int ERA
Useful constant for date and time. Used in time fields. ERA is calendar specific.

 o YEAR
 public static final int YEAR
Useful constant for date and time. Used in time fields.

 o MONTH
 public static final int MONTH
Useful constant for date and time. Used in time fields.

 o WEEK_OF_YEAR
 public static final int WEEK_OF_YEAR
Useful constant for date and time. Used in time fields.

 o WEEK_OF_MONTH
 public static final int WEEK_OF_MONTH
Useful constant for date and time. Used in time fields.

 o DATE
 public static final int DATE
Useful constant for date and time. Used in time fields. This is a synonym for DAY_OF_MONTH.

 o DAY_OF_MONTH
 public static final int DAY_OF_MONTH
Useful constant for date and time. Used in time fields. This is a synonym for DATE.

 o DAY_OF_YEAR
 public static final int DAY_OF_YEAR
Useful constant for date and time. Used in time fields.

 o DAY_OF_WEEK
 public static final int DAY_OF_WEEK
Useful constant for date and time. Used in time fields.

 o DAY_OF_WEEK_IN_MONTH
 public static final int DAY_OF_WEEK_IN_MONTH
Useful constant for date and time. Used in time fields.

 o AM_PM
 public static final int AM_PM
Useful constant for date and time. Used in time fields.

 o HOUR
 public static final int HOUR
Useful constant for date and time. Used in time fields. HOUR is used for the 12-hour clock.

 o HOUR_OF_DAY
 public static final int HOUR_OF_DAY
Useful constant for date and time. Used in time fields. HOUR_OF_DAY is used for the 24-hour clock.

 o MINUTE
 public static final int MINUTE
Useful constant for date and time. Used in time fields.

 o SECOND
 public static final int SECOND
Useful constant for date and time. Used in time fields.

 o MILLISECOND
 public static final int MILLISECOND
Useful constant for date and time. Used in time fields.

 o ZONE_OFFSET
 public static final int ZONE_OFFSET
Useful constant for date and time. Used in time fields.

 o DST_OFFSET
 public static final int DST_OFFSET
Useful constant for date and time. Used in time fields.

 o FIELD_COUNT
 public static final int FIELD_COUNT
Useful constant for date and time. FIELD_COUNT is used for the time field array creation.

 o SUNDAY
 public static final int SUNDAY
Useful constant for days of week. Used in GregorianCalendar.

 o MONDAY
 public static final int MONDAY
Useful constant for days of week. Used in GregorianCalendar.

 o TUESDAY
 public static final int TUESDAY
Useful constant for days of week. Used in GregorianCalendar.

 o WEDNESDAY
 public static final int WEDNESDAY
Useful constant for days of week. Used in GregorianCalendar.

 o THURSDAY
 public static final int THURSDAY
Useful constant for days of week. Used in GregorianCalendar.

 o FRIDAY
 public static final int FRIDAY
Useful constant for days of week. Used in GregorianCalendar.

 o SATURDAY
 public static final int SATURDAY
Useful constant for days of week. Used in GregorianCalendar.

 o JANUARY
 public static final int JANUARY
Useful constant for month. Used in GregorianCalendar. Note: Calendar month is now 0-based.

 o FEBRUARY
 public static final int FEBRUARY
Useful constant for month. Used in GregorianCalendar.

 o MARCH
 public static final int MARCH
Useful constant for month. Used in GregorianCalendar.

 o APRIL
 public static final int APRIL
Useful constant for month. Used in GregorianCalendar.

 o MAY
 public static final int MAY
Useful constant for month. Used in GregorianCalendar.

 o JUNE
 public static final int JUNE
Useful constant for month. Used in GregorianCalendar.

 o JULY
 public static final int JULY
Useful constant for month. Used in GregorianCalendar.

 o AUGUST
 public static final int AUGUST
Useful constant for month. Used in GregorianCalendar.

 o SEPTEMBER
 public static final int SEPTEMBER
Useful constant for month. Used in GregorianCalendar.

 o OCTOBER
 public static final int OCTOBER
Useful constant for month. Used in GregorianCalendar.

 o NOVEMBER
 public static final int NOVEMBER
Useful constant for month. Used in GregorianCalendar.

 o DECEMBER
 public static final int DECEMBER
Useful constant for month. Used in GregorianCalendar.

 o UNDECIMBER
 public static final int UNDECIMBER
Useful constant for month. Used in GregorianCalendar. UNDECIMBER is an artifical name. This 13th month is for lunar calendars.

 o AM
 public static final int AM
Useful constant for hour in 12-hour clock. Used in GregorianCalendar.

 o PM
 public static final int PM
Useful constant for hour in 12-hour clock. Used in GregorianCalendar.

 o fields
 protected int fields[]
The time fields containing values into which the millis is computed.

 o isSet
 protected boolean isSet[]
The flags which tell if a specified time field for the calendar is set. A new object has no fields set. After the first call to a method which generates the fields, they all remain set after that.

 o time
 protected long time
The current time set for the calendar.

 o isTimeSet
 protected boolean isTimeSet
The flag which indicates if the current time is set for the calendar. The time is made invalid by the user setting an individual field.

 o areFieldsSet
 protected boolean areFieldsSet
True if the fields are in sync with the currently set time of this Calendar. If false, then the next attempt to get the value of a field will force a recomputation of all fields from the current value of the time field. This should really be named areFieldsInSync, but the old name is retained for backward compatibility.

Constructors

 o Calendar
 protected Calendar()
Constructs a Calendar with the default time zone as returned by TimeZone.getDefault(), and the default locale.

See Also:
getDefault
 o Calendar
 protected Calendar(TimeZone zone,
                    Locale aLocale)
Constructs a Calendar with the given time zone and locale.

Parameters:
zone - the given time zone.

Methods

 o getInstance
 public static synchronized Calendar getInstance()
Gets a Calendar using the default timezone and locale.

Returns:
a Calendar.
 o getInstance
 public static synchronized Calendar getInstance(TimeZone zone)
Gets a Calendar using the given timezone and default locale.

Parameters:
zone - the given timezone.
Returns:
a Calendar.
 o getInstance
 public static synchronized Calendar getInstance(Locale aLocale)
Gets a Calendar using the default timezone and given locale.

Parameters:
aLocale - the given locale.
Returns:
a Calendar.
 o getInstance
 public static synchronized Calendar getInstance(TimeZone zone,
                                                 Locale aLocale)
Gets a Calendar using the given timezone and given locale.

Parameters:
zone - the given timezone.
aLocale - the given locale.
Returns:
a Calendar.
 o getAvailableLocales
 public static synchronized Locale[] getAvailableLocales()
Gets the set of locales for which Calendars are installed.

Returns:
the set of locales for which Calendars are installed.
 o computeTime
 protected abstract void computeTime()
Converts Calendar's time field values to UTC as milliseconds.

 o computeFields
 protected abstract void computeFields()
Converts UTC as milliseconds to time field values. This allows you to sync up the time field values with a new time that is set for the calendar. The time is not recomputed first; to recompute the time, then the fields, call the complete method.

See Also:
complete
 o getTime
 public final Date getTime()
Gets this Calendar's current time.

Returns:
the current time.
 o setTime
 public final void setTime(Date date)
Sets this Calendar's current time with the given Date.

Parameters:
date - the given Date.
 o getTimeInMillis
 protected long getTimeInMillis()
Gets this Calendar's current time as a long.

Returns:
the current time as UTC milliseconds from the epoch.
 o setTimeInMillis
 protected void setTimeInMillis(long millis)
Sets this Calendar's current time from the given long value.

Parameters:
date - the new time in UTC milliseconds from the epoch.
 o get
 public final int get(int field)
Gets the value for a given time field.

Parameters:
field - the given time field.
Returns:
the value for the given time field.
 o internalGet
 protected final int internalGet(int field)
Gets the value for a given time field. This is an internal fast time field value getter for the subclasses.

Parameters:
field - the given time field.
Returns:
the value for the given time field.
 o set
 public final void set(int field,
                       int value)
Sets the time field with the given value.

Parameters:
field - the given time field.
value - the value to be set for the given time field.
 o set
 public final void set(int year,
                       int month,
                       int date)
Sets the values for the fields year, month, and date. Previous values of other fields are retained. If this is not desired, call clear first.

Parameters:
year - the value used to set the YEAR time field.
month - the value used to set the MONTH time field. Month value is 0-based. e.g., 0 for January.
date - the value used to set the DATE time field.
 o set
 public final void set(int year,
                       int month,
                       int date,
                       int hour,
                       int minute)
Sets the values for the fields year, month, date, hour, and minute. Previous values of other fields are retained. If this is not desired, call clear first.

Parameters:
year - the value used to set the YEAR time field.
month - the value used to set the MONTH time field. Month value is 0-based. e.g., 0 for January.
date - the value used to set the DATE time field.
hour - the value used to set the HOUR_OF_DAY time field.
minute - the value used to set the MINUTE time field.
 o set
 public final void set(int year,
                       int month,
                       int date,
                       int hour,
                       int minute,
                       int second)
Sets the values for the fields year, month, date, hour, minute, and second. Previous values of other fields are retained. If this is not desired, call clear first.

Parameters:
year - the value used to set the YEAR time field.
month - the value used to set the MONTH time field. Month value is 0-based. e.g., 0 for January.
date - the value used to set the DATE time field.
hour - the value used to set the HOUR_OF_DAY time field.
minute - the value used to set the MINUTE time field.
second - the value used to set the SECOND time field.
 o clear
 public final void clear()
Clears the values of all the time fields.

 o clear
 public final void clear(int field)
Clears the value in the given time field.

Parameters:
field - the time field to be cleared.
 o isSet
 public final boolean isSet(int field)
Determines if the given time field has a value set.

Returns:
true if the given time field has a value set; false otherwise.
 o complete
 protected void complete()
Fills in any unset fields in the time field list.

 o equals
 public abstract boolean equals(Object obj)
Compares this calendar to the specified object. The result is true if and only if the argument is not null and is a Calendar object that represents the same calendar as this object.

Parameters:
obj - the object to compare with.
Returns:
true if the objects are the same; false otherwise.
Overrides:
equals in class Object
 o before
 public abstract boolean before(Object when)
Compares the time field records. Equivalent to comparing result of conversion to UTC.

Parameters:
when - the Calendar to be compared with this Calendar.
Returns:
true if the current time of this Calendar is before the time of Calendar when; false otherwise.
 o after
 public abstract boolean after(Object when)
Compares the time field records. Equivalent to comparing result of conversion to UTC.

Parameters:
when - the Calendar to be compared with this Calendar.
Returns:
true if the current time of this Calendar is after the time of Calendar when; false otherwise.
 o add
 public abstract void add(int field,
                          int amount)
Date Arithmetic function. Adds the specified (signed) amount of time to the given time field, based on the calendar's rules. For example, to subtract 5 days from the current time of the calendar, you can achieve it by calling:

add(Calendar.DATE, -5).

Parameters:
field - the time field.
amount - the amount of date or time to be added to the field.
 o roll
 public abstract void roll(int field,
                           boolean up)
Time Field Rolling function. Rolls (up/down) a single unit of time on the given time field. For example, to roll the current date up by one day, you can achieve it by calling:

roll(Calendar.DATE, true). When rolling on the year or Calendar.YEAR field, it will roll the year value in the range between 1 and the value returned by calling getMaximum(Calendar.YEAR). When rolling on the month or Calendar.MONTH field, other fields like date might conflict and, need to be changed. For instance, rolling the month on the date 01/31/96 will result in 03/02/96. When rolling on the hour-in-day or Calendar.HOUR_OF_DAY field, it will roll the hour value in the range between 0 and 23, which is zero-based.

Parameters:
field - the time field.
up - indicates if the value of the specified time field is to be rolled up or rolled down. Use true if rolling up, false otherwise.
 o setTimeZone
 public void setTimeZone(TimeZone value)
Sets the time zone with the given time zone value.

Parameters:
value - the given time zone.
 o getTimeZone
 public TimeZone getTimeZone()
Gets the time zone.

Returns:
the time zone object associated with this calendar.
 o setLenient
 public void setLenient(boolean lenient)
Specify whether or not date/time interpretation is to be lenient. With lenient interpretation, a date such as "February 942, 1996" will be treated as being equivalent to the 941st day after February 1, 1996. With strict interpretation, such dates will cause an exception to be thrown.

See Also:
setLenient
 o isLenient
 public boolean isLenient()
Tell whether date/time interpretation is to be lenient.

 o setFirstDayOfWeek
 public void setFirstDayOfWeek(int value)
Sets what the first day of the week is; e.g., Sunday in US, Monday in France.

Parameters:
value - the given first day of the week.
 o getFirstDayOfWeek
 public int getFirstDayOfWeek()
Gets what the first day of the week is; e.g., Sunday in US, Monday in France.

Returns:
the first day of the week.
 o setMinimalDaysInFirstWeek
 public void setMinimalDaysInFirstWeek(int value)
Sets what the minimal days required in the first week of the year are; For example, if the first week is defined as one that contains the first day of the first month of a year, call the method with value 1. If it must be a full week, use value 7.

Parameters:
value - the given minimal days required in the first week of the year.
 o getMinimalDaysInFirstWeek
 public int getMinimalDaysInFirstWeek()
Gets what the minimal days required in the first week of the year are; e.g., if the first week is defined as one that contains the first day of the first month of a year, getMinimalDaysInFirstWeek returns 1. If the minimal days required must be a full week, getMinimalDaysInFirstWeek returns 7.

Returns:
the minimal days required in the first week of the year.
 o getMinimum
 public abstract int getMinimum(int field)
Gets the minimum value for the given time field. e.g., for Gregorian DAY_OF_MONTH, 1.

Parameters:
field - the given time field.
Returns:
the minimum value for the given time field.
 o getMaximum
 public abstract int getMaximum(int field)
Gets the maximum value for the given time field. e.g. for Gregorian DAY_OF_MONTH, 31.

Parameters:
field - the given time field.
Returns:
the maximum value for the given time field.
 o getGreatestMinimum
 public abstract int getGreatestMinimum(int field)
Gets the highest minimum value for the given field if varies. Otherwise same as getMinimum(). For Gregorian, no difference.

Parameters:
field - the given time field.
Returns:
the highest minimum value for the given time field.
 o getLeastMaximum
 public abstract int getLeastMaximum(int field)
Gets the lowest maximum value for the given field if varies. Otherwise same as getMaximum(). e.g., for Gregorian DAY_OF_MONTH, 28.

Parameters:
field - the given time field.
Returns:
the lowest maximum value for the given time field.
 o clone
 public Object clone()
Overrides Cloneable

Overrides:
clone in class Object
 o toString
 public String toString()
Return a string representation of this calendar.

Returns:
a string representation of this calendar.
Overrides:
toString in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Submit a bug or feature - Version 1.1.8 of Java Platform API Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1995-1999 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.