All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.util.Calendar

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

public class Calendar
extends Object
implements Serializable, Cloneable

Calendar is an abstract base class for converting between a Date 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.

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

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

When computing a Date from time fields, two special circumstances may arise: there might 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. The calendar will give preference to the combinations of fields in the following order (and disregard other inconsistent information).

 month + day-of-month
 month + week-of-month + day-of-week
 month + day-of-week-of-month + day-of-week
 day-of-year
 day-of-week + week-of-year
 hour-of-day
 ampm + hour-of-ampm

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:

a. 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

b. 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.

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

AM: Useful constant for hour in 12-hour clock.
AMPM: Useful constant for date and time.
APRIL: Useful constant for month.
areFieldsSet: The flag which tells if the time fields are set for the calendar.
AUGUST: Useful constant for month.
DATE: Useful constant for date and time.
DAYOFMONTH: Useful constant for date and time.
DAYOFWEEK: Useful constant for date and time.
DAYOFWEEKINMONTH: Useful constant for date and time.
DAYOFYEAR: Useful constant for date and time.
DECEMBER: Useful constant for month.
DSTOFFSET: Useful constant for date and time.
ERA: Useful constant for date and time.
FEBRUARY: Useful constant for month.
FIELDCOUNT: Useful constant for date and time.
fields: The time fields containing values into which the millis is computed.
FRIDAY: Useful constant for days of week.
HOUR: Useful constant for date and time.
HOUROFDAY: Useful constant for date and time.
isSet: The flags which tell if a specified time field for the calendar is set.
isTimeSet: The flag which indicates if the current time is set for the calendar.
JANUARY: Useful constant for month.
JULY: Useful constant for month.
JUNE: Useful constant for month.
MARCH: Useful constant for month.
MAY: Useful constant for month.
MILLISECOND: Useful constant for date and time.
MINUTE: Useful constant for date and time.
MONDAY: Useful constant for days of week.
MONTH: Useful constant for date and time.
NOVEMBER: Useful constant for month.
OCTOBER: Useful constant for month.
PM: Useful constant for hour in 12-hour clock.
SATURDAY: Useful constant for days of week.
SECOND: Useful constant for date and time.
SEPTEMBER: Useful constant for month.
SUNDAY: Useful constant for days of week.
THURSDAY: Useful constant for days of week.
time: The current time set for the calendar.
TUESDAY: Useful constant for days of week.
UNDECIMBER: Useful constant for month.
WEDNESDAY: Useful constant for days of week.
WEEKOFMONTH: Useful constant for date and time.
WEEKOFYEAR: Useful constant for date and time.
YEAR: Useful constant for date and time.
ZONEOFFSET: Useful constant for date and time.

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

add(byte, int): Date Arithmetic function.
after(Object): Compares the time field records.
before(Object): Compares the time field records.
clear(): Clears the values of all the time fields.
clear(byte): Clears the value in the given time field.
clone(): Overrides Cloneable
complete(): Fills in any unset fields in the time field list.
computeFields(): Converts UTC as milliseconds to time field values.
computeTime(): Converts Calendar's time field values to UTC as milliseconds.
equals(Object): Compares the time field records.
get(byte): Gets the value for a given time field.
getAvailableLocales(): Gets the set of locales for which Calendars are installed.
getDefault(): Gets a Calendar using the default timezone and locale.
getDefault(Locale): Gets a Calendar using the default timezone and given locale.
getDefault(TimeZone): Gets a Calendar using the given timezone and default locale.
getDefault(TimeZone, Locale): Gets a Calendar using the given timezone and given locale.
getFirstDayOfWeek(): Gets what the first day of the week is; e.g., Sunday in US, Monday in France.
getGreatestMinimum(byte): Gets the highest minimum value for the given field if varies.
getLeastMaximum(byte): Gets the lowest maximum value for the given field if varies.
getMaximum(byte): Gets the maximum value for the given time field.
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.
getMinimum(byte): Gets the minimum value for the given time field.
getTime(): Gets this Calendar's current time.
getTimeInMillis(): Gets this Calendar's current time as a long.
getTimeZone(): Gets the time zone.
getValidationMode(): Gets the validation mode.
internalGet(int): Gets the value for a given time field.
isSet(int): Determines if the given time field has a value set.
roll(byte, boolean): Time Field Rolling function.
set(byte, int): Sets the time field with the given value.
set(int, int, int): Sets the values for the fields year, month, and date.
set(int, int, int, int, int): Sets the values for the fields year, month, date, hour, and minute.
set(int, int, int, int, int, int): Sets the values for the fields year, month, date, hour, minute, and second.
setFirstDayOfWeek(byte): Sets what the first day of the week is; e.g., Sunday in US, Monday in France.
setMinimalDaysInFirstWeek(byte): 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.
setTime(Date): Sets this Calendar's current time with the given Date.
setTimeInMillis(long): Sets this Calendar's current time from the given long value.
setTimeZone(TimeZone): Sets the time zone with the given time zone value.
setValidationMode(boolean): Sets the validation mode which controls the behavior of the object that uses Calendar.

ERA

  public final static byte ERA

Useful constant for date and time. Used in time fields. ERA is calendar specific.

YEAR

  public final static byte YEAR

Useful constant for date and time. Used in time fields.

MONTH

  public final static byte MONTH

Useful constant for date and time. Used in time fields.

WEEKOFYEAR

  public final static byte WEEKOFYEAR

Useful constant for date and time. Used in time fields.

WEEKOFMONTH

  public final static byte WEEKOFMONTH

Useful constant for date and time. Used in time fields.

DATE

  public final static byte DATE

Useful constant for date and time. Used in time fields. DATE is the time field name for day-of-month.

DAYOFMONTH

  public final static byte DAYOFMONTH

Useful constant for date and time. Used in time fields. This is a synonym for DATE.

DAYOFYEAR

  public final static byte DAYOFYEAR

Useful constant for date and time. Used in time fields.

DAYOFWEEK

  public final static byte DAYOFWEEK

Useful constant for date and time. Used in time fields.

DAYOFWEEKINMONTH

  public final static byte DAYOFWEEKINMONTH

Useful constant for date and time. Used in time fields.

AMPM

  public final static byte AMPM

Useful constant for date and time. Used in time fields.

HOUR

  public final static byte HOUR

Useful constant for date and time. Used in time fields. HOUR is used for the 12-hour clock.

HOUROFDAY

  public final static byte HOUROFDAY

Useful constant for date and time. Used in time fields. HOUROFDAY is used for the 24-hour clock.

MINUTE

  public final static byte MINUTE

Useful constant for date and time. Used in time fields.

SECOND

  public final static byte SECOND

Useful constant for date and time. Used in time fields.

MILLISECOND

  public final static byte MILLISECOND

Useful constant for date and time. Used in time fields.

ZONEOFFSET

  public final static byte ZONEOFFSET

Useful constant for date and time. Used in time fields.

DSTOFFSET

  public final static byte DSTOFFSET

Useful constant for date and time. Used in time fields.

FIELDCOUNT

  public final static byte FIELDCOUNT

Useful constant for date and time. FIELDCOUNT is used for the time field array creation.

SUNDAY

  public final static int SUNDAY

Useful constant for days of week. Used in GregorianCalendar.

MONDAY

  public final static int MONDAY

Useful constant for days of week. Used in GregorianCalendar.

TUESDAY

  public final static int TUESDAY

Useful constant for days of week. Used in GregorianCalendar.

WEDNESDAY

  public final static int WEDNESDAY

Useful constant for days of week. Used in GregorianCalendar.

THURSDAY

  public final static int THURSDAY

Useful constant for days of week. Used in GregorianCalendar.

FRIDAY

  public final static int FRIDAY

Useful constant for days of week. Used in GregorianCalendar.

SATURDAY

  public final static int SATURDAY

Useful constant for days of week. Used in GregorianCalendar.

JANUARY

  public final static int JANUARY

Useful constant for month. Used in GregorianCalendar. Note: Calendar month is now 0-based.

FEBRUARY

  public final static int FEBRUARY

Useful constant for month. Used in GregorianCalendar.

MARCH

  public final static int MARCH

Useful constant for month. Used in GregorianCalendar.

APRIL

  public final static int APRIL

Useful constant for month. Used in GregorianCalendar.

MAY

  public final static int MAY

Useful constant for month. Used in GregorianCalendar.

JUNE

  public final static int JUNE

Useful constant for month. Used in GregorianCalendar.

JULY

  public final static int JULY

Useful constant for month. Used in GregorianCalendar.

AUGUST

  public final static int AUGUST

Useful constant for month. Used in GregorianCalendar.

SEPTEMBER

  public final static int SEPTEMBER

Useful constant for month. Used in GregorianCalendar.

OCTOBER

  public final static int OCTOBER

Useful constant for month. Used in GregorianCalendar.

NOVEMBER

  public final static int NOVEMBER

Useful constant for month. Used in GregorianCalendar.

DECEMBER

  public final static int DECEMBER

Useful constant for month. Used in GregorianCalendar.

UNDECIMBER

  public final static int UNDECIMBER

Useful constant for month. Used in GregorianCalendar. UNDECIMBER is an artifical name. This 13th month is for lunar calendars.

  public final static int AM

Useful constant for hour in 12-hour clock. Used in GregorianCalendar.

  public final static int PM

Useful constant for hour in 12-hour clock. Used in GregorianCalendar.

fields

  protected int fields[]

The time fields containing values into which the millis is computed.

isSet

  protected boolean isSet[]

The flags which tell if a specified time field for the calendar is set.

time

  protected long time

The current time set for the calendar.

isTimeSet

  protected boolean isTimeSet

The flag which indicates if the current time is set for the calendar.

areFieldsSet

  protected boolean areFieldsSet

The flag which tells if the time fields are set for the calendar.

Calendar

  protected Calendar()

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

See Also:: getDefault

Calendar

  protected Calendar(TimeZone zone,
                     Locale aLocale)

Constructs a Calendar with the given time zone and locale.

Parameters:: zone - the given time zone.

getDefault

  public static synchronized Calendar getDefault()

Gets a Calendar using the default timezone and locale.

Returns:: a Calendar.

getDefault

  public static synchronized Calendar getDefault(TimeZone zone)

Gets a Calendar using the given timezone and default locale.

Parameters:: zone - the given timezone.
Returns:: a Calendar.

getDefault

  public static synchronized Calendar getDefault(Locale aLocale)

Gets a Calendar using the default timezone and given locale.

Parameters:: aLocale - the given locale.
Returns:: a Calendar.

getDefault

  public static synchronized Calendar getDefault(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.

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.

computeTime

  protected abstract void computeTime()

Converts Calendar's time field values to UTC as milliseconds.

computeFields

  public 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.

getTime

  public final Date getTime()

Gets this Calendar's current time.

Returns:: the current time.

setTime

  public final void setTime(Date date)

Sets this Calendar's current time with the given Date.

Parameters:: date - the given Date.

getTimeInMillis

  protected long getTimeInMillis()

Gets this Calendar's current time as a long.

Returns:: the current time as milliseconds from the epoch.

setTimeInMillis

  protected void setTimeInMillis(long millis)

Sets this Calendar's current time from the given long value.

Parameters:: date - the new time in milliseconds from the epoch.

get

  public final int get(byte field) throws IllegalArgumentException

Gets the value for a given time field.

Parameters:: field - the given time field.
Returns:: the value for the given time field.

internalGet

  protected final int internalGet(int field) throws IllegalArgumentException

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.

set

  public final void set(byte field,
                        int value) throws IllegalArgumentException

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.

set

  public final void set(int year,
                        int month,
                        int date)

Sets the values for the fields year, month, and date.

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.

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.

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 HOUROFDAY time field.; minute - the value used to set the MINUTE time field.

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.

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 HOUROFDAY time field.; minute - the value used to set the MINUTE time field.; second - the value used to set the SECOND time field.

clear

  public final void clear()

Clears the values of all the time fields.

clear

  public final void clear(byte field) throws IllegalArgumentException

Clears the value in the given time field.

Parameters:: field - the time field to be cleared.

isSet

  public final boolean isSet(int field) throws IllegalArgumentException

Determines if the given time field has a value set.

Returns:: true if the given time field has a value set; false otherwise.

complete

  public void complete() throws IllegalArgumentException

Fills in any unset fields in the time field list.

equals

  public abstract boolean equals(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 equal to the time of Calendar when; false otherwise.
Overrides:: equals in class Object

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.

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.

add

  public abstract void add(byte field,
                           int amount) throws IllegalArgumentException

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.

roll

  public abstract void roll(byte field,
                            boolean up) throws IllegalArgumentException

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.HOUROFDAY 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.

setTimeZone

  public void setTimeZone(TimeZone value)

Sets the time zone with the given time zone value.

Parameters:: value - the given time zone.

getTimeZone

  public TimeZone getTimeZone()

Gets the time zone.

Returns:: the time zone object associated with this calendar.

setValidationMode

  public void setValidationMode(boolean mode)

Sets the validation mode which controls the behavior of the object that uses Calendar.

Parameters:: mode - the validation mode. For example, in DateFormat, the validation mode is set to control its parsing behavior. When the mode is true, the parse will throw an exception if the given time text to be parsed isn't an acceptable date. For example, the date "February 942, 1996" would cause an exception.
When the mode is false, the parse will return the best result it can. In that case, "February 942, 1996" will return the 941st day after February 1, 1996.

getValidationMode

  public boolean getValidationMode()

Gets the validation mode.

Returns:: the state of the validation mode.
See Also:: setValidationMode

setFirstDayOfWeek

  public void setFirstDayOfWeek(byte 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.

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.

setMinimalDaysInFirstWeek

  public void setMinimalDaysInFirstWeek(byte 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.

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.

getMinimum

  public abstract int getMinimum(byte field)

Gets the minimum value for the given time field. e.g., for Gregorian DAYOFMONTH, 1.

Parameters:: field - the given time field.
Returns:: the minimum value for the given time field.

getMaximum

  public abstract int getMaximum(byte field)

Gets the maximum value for the given time field. e.g. for Gregorian DAYOFMONTH, 31.

Parameters:: field - the given time field.
Returns:: the maximum value for the given time field.

getGreatestMinimum

  public abstract int getGreatestMinimum(byte 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.

getLeastMaximum

  public abstract int getLeastMaximum(byte field)

Gets the lowest maximum value for the given field if varies. Otherwise same as getMaximum(). e.g., for Gregorian DAYOFMONTH, 28.

Parameters:: field - the given time field.
Returns:: the lowest maximum value for the given time field.

clone

  public Object clone()

Overrides Cloneable

Overrides:: clone in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index