Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.util
Class Calendar

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

All Implemented Interfaces:
  Cloneable, Serializable

Direct Known Subclasses:
  GregorianCalendar

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 `Date` for information about the `Date` class.)

Subclasses of `Calendar` interpret a `Date` according to the rules of a specific calendar system. The platform 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 `Calendar` 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). `Calendar` defines the range of values returned by certain fields, as well as their meaning. For example, the first month of the year has value `MONTH` == `JANUARY` for all calendars. Other values are defined by the concrete subclass, such as `ERA` and `YEAR`. See individual field documentation and subclass documentation for details.

When a `Calendar` is lenient, it accepts a wider range of field values than it produces. For example, a lenient `GregorianCalendar` interprets `MONTH` == `JANUARY`, `DAY_OF_MONTH` == 32 as February 1. A non-lenient `GregorianCalendar` throws an exception when given out-of-range field settings. When calendars recompute field values for return by `get()`, they normalize them. For example, a `GregorianCalendar` always produces `DAY_OF_MONTH` values between 1 and the length of the month.

`Calendar` defines a locale-specific seven day week using two parameters: the first day of the week and the minimal days in first week (from 1 to 7). These numbers are taken from the locale resource data when a `Calendar` is constructed. They may also be specified explicitly through the API.

When setting or getting the `WEEK_OF_MONTH` or `WEEK_OF_YEAR` fields, `Calendar` must determine the first week of the month or year as a reference point. The first week of a month or year is defined as the earliest seven day period beginning on `getFirstDayOfWeek()` and containing at least `getMinimalDaysInFirstWeek()` days of that month or year. Weeks numbered ..., -1, 0 precede the first week; weeks numbered 2, 3,... follow it. Note that the normalized numbering returned by `get()` may be different. For example, a specific `Calendar` subclass may designate the week before week 1 of a year as week n of the previous year.

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 historical 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. 23:59 is the last minute of the day and 00:00 is the first minute of the next day. Thus, 23:59 on Dec 31, 1999 < 00:00 on Jan 1, 2000 < 00:01 on Jan 1, 2000.
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 `DateFormat` to format dates.

Field manipulation methods

`Calendar` fields can be changed using three methods: `set()`, `add()`, and `roll()`.

`set(f, value)` changes field `f` to `value`. In addition, it sets an internal member variable to indicate that field `f` has been changed. Although field `f` is changed immediately, the calendar's milliseconds is not recomputed until the next call to `get()`, `getTime()`, or `getTimeInMillis()` is made. Thus, multiple calls to `set()` do not trigger multiple, unnecessary computations. As a result of changing a field using `set()`, other fields may also change, depending on the field, the field value, and the calendar system. In addition, `get(f)` will not necessarily return `value` after the fields have been recomputed. The specifics are determined by the concrete calendar class.

Example: Consider a `GregorianCalendar` originally set to August 31, 1999. Calling `set(Calendar.MONTH, Calendar.SEPTEMBER)` sets the calendar to September 31, 1999. This is a temporary internal representation that resolves to October 1, 1999 if `getTime()`is then called. However, a call to `set(Calendar.DAY_OF_MONTH, 30)` before the call to `getTime()` sets the calendar to September 30, 1999, since no recomputation occurs after `set()` itself.

`add(f, delta)` adds `delta` to field `f`. This is equivalent to calling `set(f, get(f) + delta)` with two adjustments:

> Add rule 1. The value of field `f` after the call minus the value of field `f` before the call is `delta`, modulo any overflow that has occurred in field `f`. Overflow occurs when a field value exceeds its range and, as a result, the next larger field is incremented or decremented and the field value is adjusted back into its range.

> Add rule 2. If a smaller field is expected to be invariant, but it is impossible for it to be equal to its prior value because of changes in its minimum or maximum after field `f` is changed, then its value is adjusted to be as close as possible to its expected value. A smaller field represents a smaller unit of time. `HOUR` is a smaller field than `DAY_OF_MONTH`. No adjustment is made to smaller fields that are not expected to be invariant. The calendar system determines what fields are expected to be invariant.

In addition, unlike `set()`, `add()` forces an immediate recomputation of the calendar's milliseconds and all fields.

Example: Consider a `GregorianCalendar` originally set to August 31, 1999. Calling `add(Calendar.MONTH, 13)` sets the calendar to September 30, 2000. Add rule 1 sets the `MONTH` field to September, since adding 13 months to August gives September of the next year. Since `DAY_OF_MONTH` cannot be 31 in September in a `GregorianCalendar`, add rule 2 sets the `DAY_OF_MONTH` to 30, the closest possible value. Although it is a smaller field, `DAY_OF_WEEK` is not adjusted by rule 2, since it is expected to change when the month changes in a `GregorianCalendar`.

`roll(f, delta)` adds `delta` to field `f` without changing larger fields. This is equivalent to calling `add(f, delta)` with the following adjustment:

> Roll rule. Larger fields are unchanged after the call. A larger field represents a larger unit of time. `DAY_OF_MONTH` is a larger field than `HOUR`.

Example: See `GregorianCalendar.roll(int, int)`.

Usage model. To motivate the behavior of `add()` and `roll()`, consider a user interface component with increment and decrement buttons for the month, day, and year, and an underlying `GregorianCalendar`. If the interface reads January 31, 1999 and the user presses the month increment button, what should it read? If the underlying implementation uses `set()`, it might read March 3, 1999. A better result would be February 28, 1999. Furthermore, if the user presses the month increment button again, it should read March 31, 1999, not March 28, 1999. By saving the original date and using either `add()` or `roll()`, depending on whether larger fields should be affected, the user interface can behave as most users will intuitively expect.

Since:
  JDK1.1
See Also:
  `Date`, `GregorianCalendar`, `TimeZone`, `DateFormat`, Serialized Form

Field Summary
`static int` | `AM` Value of the `AM_PM` field indicating the period of the day from midnight to just before noon.
`static int` | `AM_PM` Field number for `get` and `set` indicating whether the `HOUR` is before or after noon.
`static int` | `APRIL` Value of the `MONTH` field indicating the fourth month of the year.
`protected boolean` | `areFieldsSet` True if `fields[]` are in sync with the currently set time.
`static int` | `AUGUST` Value of the `MONTH` field indicating the eighth month of the year.
`static int` | `DATE` Field number for `get` and `set` indicating the day of the month.
`static int` | `DAY_OF_MONTH` Field number for `get` and `set` indicating the day of the month.
`static int` | `DAY_OF_WEEK` Field number for `get` and `set` indicating the day of the week.
`static 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.
`static int` | `DAY_OF_YEAR` Field number for `get` and `set` indicating the day number within the current year.
`static int` | `DECEMBER` Value of the `MONTH` field indicating the twelfth month of the year.
`static int` | `DST_OFFSET` Field number for `get` and `set` indicating the daylight savings offset in milliseconds.
`static int` | `ERA` Field number for `get` and `set` indicating the era, e.g., AD or BC in the Julian calendar.
`static int` | `FEBRUARY` Value of the `MONTH` field indicating the second month of the year.
`static int` | `FIELD_COUNT` The number of distinct fields recognized by `get` and `set`.
`protected int[]` | `fields` The field values for the currently set time for this calendar.
`static int` | `FRIDAY` Value of the `DAY_OF_WEEK` field indicating Friday.
`static int` | `HOUR` Field number for `get` and `set` indicating the hour of the morning or afternoon.
`static int` | `HOUR_OF_DAY` Field number for `get` and `set` indicating the hour of the day.
`protected boolean[]` | `isSet` The flags which tell if a specified time field for the calendar is set.
`protected boolean` | `isTimeSet` True if then the value of `time` is valid.
`static int` | `JANUARY` Value of the `MONTH` field indicating the first month of the year.
`static int` | `JULY` Value of the `MONTH` field indicating the seventh month of the year.
`static int` | `JUNE` Value of the `MONTH` field indicating the sixth month of the year.
`static int` | `MARCH` Value of the `MONTH` field indicating the third month of the year.
`static int` | `MAY` Value of the `MONTH` field indicating the fifth month of the year.
`static int` | `MILLISECOND` Field number for `get` and `set` indicating the millisecond within the second.
`static int` | `MINUTE` Field number for `get` and `set` indicating the minute within the hour.
`static int` | `MONDAY` Value of the `DAY_OF_WEEK` field indicating Monday.
`static int` | `MONTH` Field number for `get` and `set` indicating the month.
`static int` | `NOVEMBER` Value of the `MONTH` field indicating the eleventh month of the year.
`static int` | `OCTOBER` Value of the `MONTH` field indicating the tenth month of the year.
`static int` | `PM` Value of the `AM_PM` field indicating the period of the day from noon to just before midnight.
`static int` | `SATURDAY` Value of the `DAY_OF_WEEK` field indicating Saturday.
`static int` | `SECOND` Field number for `get` and `set` indicating the second within the minute.
`static int` | `SEPTEMBER` Value of the `MONTH` field indicating the ninth month of the year.
`static int` | `SUNDAY` Value of the `DAY_OF_WEEK` field indicating Sunday.
`static int` | `THURSDAY` Value of the `DAY_OF_WEEK` field indicating Thursday.
`protected long` | `time` The currently set time for this calendar, expressed in milliseconds after January 1, 1970, 0:00:00 GMT.
`static int` | `TUESDAY` Value of the `DAY_OF_WEEK` field indicating Tuesday.
`static int` | `UNDECIMBER` Value of the `MONTH` field indicating the thirteenth month of the year.
`static int` | `WEDNESDAY` Value of the `DAY_OF_WEEK` field indicating Wednesday.
`static int` | `WEEK_OF_MONTH` Field number for `get` and `set` indicating the week number within the current month.
`static int` | `WEEK_OF_YEAR` Field number for `get` and `set` indicating the week number within the current year.
`static int` | `YEAR` Field number for `get` and `set` indicating the year.
`static int` | `ZONE_OFFSET` Field number for `get` and `set` indicating the raw offset from GMT in milliseconds.

Constructor Summary
`protected` | `Calendar()` Constructs a Calendar with the default time zone and locale.
`protected` | `Calendar(TimeZone zone, Locale aLocale)` Constructs a calendar with the specified time zone and locale.

Method Summary
`abstract void` | `add(int field, int amount)` Date Arithmetic function.
`boolean` | `after(Object when)` Compares the time field records.
`boolean` | `before(Object when)` Compares the time field records.
`void` | `clear()` Clears the values of all the time fields.
`void` | `clear(int field)` Clears the value in the given time field.
`Object` | `clone()` Overrides Cloneable
`protected void` | `complete()` Fills in any unset fields in the time field list.
`protected abstract void` | `computeFields()` Converts the current millisecond time value `time` to field values in `fields[]`.
`protected abstract void` | `computeTime()` Converts the current field values in `fields[]` to the millisecond time value `time`.
`boolean` | `equals(Object obj)` Compares this calendar to the specified object.
`int` | `get(int field)` Gets the value for a given time field.
`int` | `getActualMaximum(int field)` Return the maximum value that this field could have, given the current date.
`int` | `getActualMinimum(int field)` Return the minimum value that this field could have, given the current date.
`static Locale[]` | `getAvailableLocales()` Gets the list of locales for which Calendars are installed.
`int` | `getFirstDayOfWeek()` Gets what the first day of the week is; e.g., Sunday in US, Monday in France.
`abstract int` | `getGreatestMinimum(int field)` Gets the highest minimum value for the given field if varies.
`static Calendar` | `getInstance()` Gets a calendar using the default time zone and locale.
`static Calendar` | `getInstance(Locale aLocale)` Gets a calendar using the default time zone and specified locale.
`static Calendar` | `getInstance(TimeZone zone)` Gets a calendar using the specified time zone and default locale.
`static Calendar` | `getInstance(TimeZone zone, Locale aLocale)` Gets a calendar with the specified time zone and locale.
`abstract int` | `getLeastMaximum(int field)` Gets the lowest maximum value for the given field if varies.
`abstract int` | `getMaximum(int field)` Gets the maximum value for the given time field.
`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.
`abstract int` | `getMinimum(int field)` Gets the minimum value for the given time field.
`Date` | `getTime()` Gets this Calendar's current time.
`long` | `getTimeInMillis()` Gets this Calendar's current time as a long.
`TimeZone` | `getTimeZone()` Gets the time zone.
`int` | `hashCode()` Returns a hash code for this calendar.
`protected int` | `internalGet(int field)` Gets the value for a given time field.
`boolean` | `isLenient()` Tell whether date/time interpretation is to be lenient.
`boolean` | `isSet(int field)` Determines if the given time field has a value set.
`abstract void` | `roll(int field, boolean up)` Time Field Rolling function.
`void` | `roll(int field, int amount)` Time Field Rolling function.
`void` | `set(int field, int value)` Sets the time field with the given value.
`void` | `set(int year, int month, int date)` Sets the values for the fields year, month, and date.
`void` | `set(int year, int month, int date, int hour, int minute)` Sets the values for the fields year, month, date, hour, and minute.
`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.
`void` | `setFirstDayOfWeek(int value)` Sets what the first day of the week is; e.g., Sunday in US, Monday in France.
`void` | `setLenient(boolean lenient)` Specify whether or not date/time interpretation is to be lenient.
`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.
`void` | `setTime(Date date)` Sets this Calendar's current time with the given Date.
`void` | `setTimeInMillis(long millis)` Sets this Calendar's current time from the given long value.
`void` | `setTimeZone(TimeZone value)` Sets the time zone with the given time zone value.
`String` | `toString()` Return a string representation of this calendar.

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### ERA

    public static final int ERA

  Field number for `get` and `set` indicating the era, e.g., AD or BC in the Julian calendar. This is a calendar-specific value; see subclass documentation.

  See Also:
    `GregorianCalendar.AD`, `GregorianCalendar.BC`, Constant Field Values

### YEAR

    public static final int YEAR

  Field number for `get` and `set` indicating the year. This is a calendar-specific value; see subclass documentation.

  See Also:
    Constant Field Values

### MONTH

    public static final int MONTH

  Field number for `get` and `set` indicating the month. This is a calendar-specific value. The first month of the year is `JANUARY` which is 0; the last depends on the number of months in a year.

  See Also:
    `JANUARY`, `FEBRUARY`, `MARCH`, `APRIL`, `MAY`, `JUNE`, `JULY`, `AUGUST`, `SEPTEMBER`, `OCTOBER`, `NOVEMBER`, `DECEMBER`, `UNDECIMBER`, Constant Field Values

### WEEK_OF_YEAR

    public static final int WEEK_OF_YEAR

  Field number for `get` and `set` indicating the week number within the current year. The first week of the year, as defined by `getFirstDayOfWeek()` and `getMinimalDaysInFirstWeek()`, has value 1. Subclasses define the value of `WEEK_OF_YEAR` for days before the first week of the year.

  See Also:
    `getFirstDayOfWeek()`, `getMinimalDaysInFirstWeek()`, Constant Field Values

### WEEK_OF_MONTH

    public static final int WEEK_OF_MONTH

  Field number for `get` and `set` indicating the week number within the current month. The first week of the month, as defined by `getFirstDayOfWeek()` and `getMinimalDaysInFirstWeek()`, has value 1. Subclasses define the value of `WEEK_OF_MONTH` for days before the first week of the month.

  See Also:
    `getFirstDayOfWeek()`, `getMinimalDaysInFirstWeek()`, Constant Field Values

### DATE

    public static final int DATE

  Field number for `get` and `set` indicating the day of the month. This is a synonym for `DAY_OF_MONTH`. The first day of the month has value 1.

  See Also:
    `DAY_OF_MONTH`, Constant Field Values

### DAY_OF_MONTH

    public static final int DAY_OF_MONTH

  Field number for `get` and `set` indicating the day of the month. This is a synonym for `DATE`. The first day of the month has value 1.

  See Also:
    `DATE`, Constant Field Values

### DAY_OF_YEAR

    public static final int DAY_OF_YEAR

  Field number for `get` and `set` indicating the day number within the current year. The first day of the year has value 1.

  See Also:
    Constant Field Values

### DAY_OF_WEEK

    public static final int DAY_OF_WEEK

  Field number for `get` and `set` indicating the day of the week. This field takes values `SUNDAY`, `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, and `SATURDAY`.

  See Also:
    `SUNDAY`, `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, Constant Field Values

### DAY_OF_WEEK_IN_MONTH

    public static final 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. Together with the `DAY_OF_WEEK` field, this uniquely specifies a day within a month. Unlike `WEEK_OF_MONTH` and `WEEK_OF_YEAR`, this field's value does not depend on `getFirstDayOfWeek()` or `getMinimalDaysInFirstWeek()`. `DAY_OF_MONTH 1` through `7` always correspond to `DAY_OF_WEEK_IN_MONTH 1`; `8` through `14` correspond to `DAY_OF_WEEK_IN_MONTH 2`, and so on. `DAY_OF_WEEK_IN_MONTH 0` indicates the week before `DAY_OF_WEEK_IN_MONTH 1`. Negative values count back from the end of the month, so the last Sunday of a month is specified as `DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1`. Because negative values count backward they will usually be aligned differently within the month than positive values. For example, if a month has 31 days, `DAY_OF_WEEK_IN_MONTH -1` will overlap `DAY_OF_WEEK_IN_MONTH 5` and the end of `4`.

  See Also:
    `DAY_OF_WEEK`, `WEEK_OF_MONTH`, Constant Field Values

### AM_PM

    public static final int AM_PM

  Field number for `get` and `set` indicating whether the `HOUR` is before or after noon. E.g., at 10:04:15.250 PM the `AM_PM` is `PM`.

  See Also:
    `AM`, `PM`, `HOUR`, Constant Field Values

### HOUR

    public static final int HOUR

  Field number for `get` and `set` indicating the hour of the morning or afternoon. `HOUR` is used for the 12-hour clock. E.g., at 10:04:15.250 PM the `HOUR` is 10.

  See Also:
    `AM_PM`, `HOUR_OF_DAY`, Constant Field Values

### HOUR_OF_DAY

    public static final int HOUR_OF_DAY

  Field number for `get` and `set` indicating the hour of the day. `HOUR_OF_DAY` is used for the 24-hour clock. E.g., at 10:04:15.250 PM the `HOUR_OF_DAY` is 22.

  See Also:
    `HOUR`, Constant Field Values

### MINUTE

    public static final int MINUTE

  Field number for `get` and `set` indicating the minute within the hour. E.g., at 10:04:15.250 PM the `MINUTE` is 4.

  See Also:
    Constant Field Values

### SECOND

    public static final int SECOND

  Field number for `get` and `set` indicating the second within the minute. E.g., at 10:04:15.250 PM the `SECOND` is 15.

  See Also:
    Constant Field Values

### MILLISECOND

    public static final int MILLISECOND

  Field number for `get` and `set` indicating the millisecond within the second. E.g., at 10:04:15.250 PM the `MILLISECOND` is 250.

  See Also:
    Constant Field Values

### ZONE_OFFSET

    public static final int ZONE_OFFSET

  Field number for `get` and `set` indicating the raw offset from GMT in milliseconds.

  This field reflects the correct GMT offset value of the time zone of this `Calendar` if the `TimeZone` implementation subclass supports historical GMT offset changes.

  See Also:
    Constant Field Values

### DST_OFFSET

    public static final int DST_OFFSET

  Field number for `get` and `set` indicating the daylight savings offset in milliseconds.

  This field reflects the correct daylight saving offset value of the time zone of this `Calendar` if the `TimeZone` implementation subclass supports historical Daylight Saving Time schedule changes.

  See Also:
    Constant Field Values

### FIELD_COUNT

    public static final int FIELD_COUNT

  The number of distinct fields recognized by `get` and `set`. Field numbers range from `0..FIELD_COUNT-1`.

  See Also:
    Constant Field Values

### SUNDAY

    public static final int SUNDAY

  Value of the `DAY_OF_WEEK` field indicating Sunday.

  See Also:
    Constant Field Values

### MONDAY

    public static final int MONDAY

  Value of the `DAY_OF_WEEK` field indicating Monday.

  See Also:
    Constant Field Values

### TUESDAY

    public static final int TUESDAY

  Value of the `DAY_OF_WEEK` field indicating Tuesday.

  See Also:
    Constant Field Values

### WEDNESDAY

    public static final int WEDNESDAY

  Value of the `DAY_OF_WEEK` field indicating Wednesday.

  See Also:
    Constant Field Values

### THURSDAY

    public static final int THURSDAY

  Value of the `DAY_OF_WEEK` field indicating Thursday.

  See Also:
    Constant Field Values

### FRIDAY

    public static final int FRIDAY

  Value of the `DAY_OF_WEEK` field indicating Friday.

  See Also:
    Constant Field Values

### SATURDAY

    public static final int SATURDAY

  Value of the `DAY_OF_WEEK` field indicating Saturday.

  See Also:
    Constant Field Values

### JANUARY

    public static final int JANUARY

  Value of the `MONTH` field indicating the first month of the year.

  See Also:
    Constant Field Values

### FEBRUARY

    public static final int FEBRUARY

  Value of the `MONTH` field indicating the second month of the year.

  See Also:
    Constant Field Values

### MARCH

    public static final int MARCH

  Value of the `MONTH` field indicating the third month of the year.

  See Also:
    Constant Field Values

### APRIL

    public static final int APRIL

  Value of the `MONTH` field indicating the fourth month of the year.

  See Also:
    Constant Field Values

### MAY

    public static final int MAY

  Value of the `MONTH` field indicating the fifth month of the year.

  See Also:
    Constant Field Values

### JUNE

    public static final int JUNE

  Value of the `MONTH` field indicating the sixth month of the year.

  See Also:
    Constant Field Values

### JULY

    public static final int JULY

  Value of the `MONTH` field indicating the seventh month of the year.

  See Also:
    Constant Field Values

### AUGUST

    public static final int AUGUST

  Value of the `MONTH` field indicating the eighth month of the year.

  See Also:
    Constant Field Values

### SEPTEMBER

    public static final int SEPTEMBER

  Value of the `MONTH` field indicating the ninth month of the year.

  See Also:
    Constant Field Values

### OCTOBER

    public static final int OCTOBER

  Value of the `MONTH` field indicating the tenth month of the year.

  See Also:
    Constant Field Values

### NOVEMBER

    public static final int NOVEMBER

  Value of the `MONTH` field indicating the eleventh month of the year.

  See Also:
    Constant Field Values

### DECEMBER

    public static final int DECEMBER

  Value of the `MONTH` field indicating the twelfth month of the year.

  See Also:
    Constant Field Values

### UNDECIMBER

    public static final int UNDECIMBER

  Value of the `MONTH` field indicating the thirteenth month of the year. Although `GregorianCalendar` does not use this value, lunar calendars do.

  See Also:
    Constant Field Values

### AM

    public static final int AM

  Value of the `AM_PM` field indicating the period of the day from midnight to just before noon.

  See Also:
    Constant Field Values

### PM

    public static final int PM

  Value of the `AM_PM` field indicating the period of the day from noon to just before midnight.

  See Also:
    Constant Field Values

### fields

    protected int[] fields

  The field values for the currently set time for this calendar. This is an array of `FIELD_COUNT` integers, with index values `ERA` through `DST_OFFSET`.

### 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. This is an array of `FIELD_COUNT` booleans, with index values `ERA` through `DST_OFFSET`.

### time

    protected long time

  The currently set time for this calendar, expressed in milliseconds after January 1, 1970, 0:00:00 GMT.

  See Also:
    `isTimeSet`

### isTimeSet

    protected boolean isTimeSet

  True if then the value of `time` is valid. The time is made invalid by a change to an item of `field[]`.

  See Also:
    `time`

### areFieldsSet

    protected boolean areFieldsSet

  True if `fields[]` are in sync with the currently set time. 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 `time`.

Constructor Detail

### Calendar

    protected Calendar()

  Constructs a Calendar with the default time zone and locale.

See Also:
  `TimeZone.getDefault()`

### Calendar

    protected Calendar(TimeZone zone,
                       Locale aLocale)

  Constructs a calendar with the specified time zone and locale.

Parameters:
  `zone` - the time zone to use
  `aLocale` - the locale for the week data

Method Detail

### getInstance

    public static Calendar getInstance()

  Gets a calendar using the default time zone and locale. The `Calendar` returned is based on the current time in the default time zone with the default locale.

  Returns:
    a Calendar.

### getInstance

    public static Calendar getInstance(TimeZone zone)

  Gets a calendar using the specified time zone and default locale. The `Calendar` returned is based on the current time in the given time zone with the default locale.

  Parameters:
    `zone` - the time zone to use
  Returns:
    a Calendar.

### getInstance

    public static Calendar getInstance(Locale aLocale)

  Gets a calendar using the default time zone and specified locale. The `Calendar` returned is based on the current time in the default time zone with the given locale.

  Parameters:
    `aLocale` - the locale for the week data
  Returns:
    a Calendar.

### getInstance

    public static Calendar getInstance(TimeZone zone,
                                       Locale aLocale)

  Gets a calendar with the specified time zone and locale. The `Calendar` returned is based on the current time in the given time zone with the given locale.

  Parameters:
    `zone` - the time zone to use
    `aLocale` - the locale for the week data
  Returns:
    a Calendar.

### getAvailableLocales

    public static Locale[] getAvailableLocales()

  Gets the list of locales for which Calendars are installed.

  Returns:
    the list of locales for which Calendars are installed.

### computeTime

    protected abstract void computeTime()

  Converts the current field values in `fields[]` to the millisecond time value `time`.

### computeFields

    protected abstract void computeFields()

  Converts the current millisecond time value `time` to field values in `fields[]`. 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()`

### getTime

    public final Date getTime()

  Gets this Calendar's current time.

  Returns:
    the current time.
  See Also:
    `setTime(java.util.Date)`, `getTimeInMillis()`

### setTime

    public final void setTime(Date date)

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

  Note: Calling `setTime()` with `Date(Long.MAX_VALUE)` or `Date(Long.MIN_VALUE)` may yield incorrect field values from `get()`.

  Parameters:
    `date` - the given Date.
  See Also:
    `getTime()`, `setTimeInMillis(long)`

### getTimeInMillis

    public long getTimeInMillis()

  Gets this Calendar's current time as a long.

  Returns:
    the current time as UTC milliseconds from the epoch.
  See Also:
    `getTime()`, `setTimeInMillis(long)`

### setTimeInMillis

    public void setTimeInMillis(long millis)

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

  Parameters:
    `millis` - the new time in UTC milliseconds from the epoch.
  See Also:
    `setTime(java.util.Date)`, `getTimeInMillis()`

### get

    public 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.
  Throws:
    `ArrayIndexOutOfBoundsException` - if specified field is out of range (`field < 0 || field >= FIELD_COUNT`).

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

### set

    public 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.
  Throws:
    `ArrayIndexOutOfBoundsException` - if specified field is out of range (`field < 0 || field >= FIELD_COUNT`).

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

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

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

### clear

    public final void clear()

  Clears the values of all the time fields.

### clear

    public final void clear(int field)

  Clears the value in the given time field.

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

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

### complete

    protected void complete()

  Fills in any unset fields in the time field list.

### equals

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

  Overrides:
    `equals` in class `Object`
  Parameters:
    `obj` - the object to compare with.
  Returns:
    `true` if the objects are the same; `false` otherwise.
  See Also:
    `Object.hashCode()`, `Hashtable`

### hashCode

    public int hashCode()

  Returns a hash code for this calendar.

  Overrides:
    `hashCode` in class `Object`
  Returns:
    a hash code value for this object.
  Since:
    1.2
  See Also:
    `Object.equals(java.lang.Object)`, `Hashtable`

### before

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

### roll

    public abstract void roll(int field,
                              boolean up)

  Time Field Rolling function. Adds or subtracts (up/down) a single unit of time on the given time field without changing larger fields. 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 02/29/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.
  See Also:
    `add(int, int)`, `set(int, int)`

### roll

    public void roll(int field,
                     int amount)

  Time Field Rolling function. Add to field a signed amount without changing larger fields. A negative roll amount means to roll down. [NOTE: This default implementation on Calendar just repeatedly calls the version of roll() that takes a boolean and rolls by one unit. This may not always do the right thing. For example, if the DAY_OF_MONTH field is 31, rolling through February will leave it set to 28. The GregorianCalendar version of this function takes care of this problem. Other subclasses should also provide overrides of this function that do the right thing.

  Parameters:
    `field` - the time field.
    `amount` - the signed amount to add to `field`.
  Since:
    1.2
  See Also:
    `add(int, int)`, `set(int, int)`

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

### 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:
    `DateFormat.setLenient(boolean)`

### isLenient

    public boolean isLenient()

  Tell whether date/time interpretation is to be lenient.

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

### 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(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.

### 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(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.

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

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

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

### getActualMinimum

    public int getActualMinimum(int field)

  Return the minimum value that this field could have, given the current date. For the Gregorian calendar, this is the same as getMinimum() and getGreatestMinimum(). The version of this function on Calendar uses an iterative algorithm to determine the actual minimum value for the field. There is almost always a more efficient way to accomplish this (in most cases, you can simply return getMinimum()). GregorianCalendar overrides this function with a more efficient implementation.

  Parameters:
    `field` - the field to determine the minimum of
  Returns:
    the minimum of the given field for the current date of this Calendar
  Since:
    1.2

### getActualMaximum

    public int getActualMaximum(int field)

  Return the maximum value that this field could have, given the current date. For example, with the date "Feb 3, 1997" and the DAY_OF_MONTH field, the actual maximum would be 28; for "Feb 3, 1996" it s 29. Similarly for a Hebrew calendar, for some years the actual maximum for MONTH is 12, and for others 13. The version of this function on Calendar uses an iterative algorithm to determine the actual maximum value for the field. There is almost always a more efficient way to accomplish this (in most cases, you can simply return getMaximum()). GregorianCalendar overrides this function with a more efficient implementation.

  Parameters:
    `field` - the field to determine the maximum of
  Returns:
    the maximum of the given field for the current date of this Calendar
  Since:
    1.2

### clone

    public Object clone()

  Overrides Cloneable

  Overrides:
    `clone` in class `Object`
  Returns:
    a clone of this instance.
  See Also:
    `Cloneable`

### toString

    public String toString()

  Return a string representation of this calendar. This method is intended to be used only for debugging purposes, and the format of the returned string may vary between implementations. The returned string may be empty but may not be `null`.

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.