public abstract class

Calendar

extends Object
java.lang.Object
   ↳ java.util.Calendar

Class Overview

Calendar is an abstract class for getting and setting dates using a set of integer fields such as YEAR, MONTH, DAY, 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.

Like other locale-sensitive classes, Calendar provides a class method, getInstance, for getting a generally useful object of this type. 

 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, there may be insufficient information to compute the Date (such as only year and month but no day in the month).

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. In the J2SE calendar, it is possible to set fields inconsistently. However, in this subset, the DAY_OF_WEEK field cannot be set, and only a subset of the other J2SE Calendar fields are included. So it is not possible to set inconsistent data.

Note: The ambiguity in interpretation of what day midnight belongs to, is resolved as so: midnight "belongs" to the following day.
23:59 on Dec 31, 1969 < 00:00 on Jan 1, 1970.
12:00 PM is midday, and 12:00 AM is midnight.
11:59 PM on Jan 1 < 12:00 AM on Jan 2 < 12:01 AM on Jan 2.
11:59 AM on Mar 10 < 12:00 PM on Mar 10 < 12:01 PM on Mar 10.
24:00 or greater are invalid. Hours greater than 12 are invalid in AM/PM mode. Setting the time will never change the date.

If equivalent times are entered in AM/PM or 24 hour mode, equality will be determined by the actual time rather than the entered time.

This class is a subset for J2ME of the J2SE Calendar class. Many methods and variables have been pruned, and other methods simplified, in an effort to reduce the size of this class.

See Also

Summary

Constants
int AM Value of the AM_PM field indicating the period of the day from midnight to just before noon.
int AM_PM Field number for get and set indicating whether the HOUR is before or after noon.
int APRIL Value of the MONTH field indicating the fourth month of the year.
int AUGUST Value of the MONTH field indicating the eighth month of the year.
int DATE Field number for get and set indicating the day of the month.
int DAY_OF_MONTH Field number for get and set indicating the day of the month.
int DAY_OF_WEEK Field number for get and set indicating the day of the week.
int DECEMBER Value of the MONTH field indicating the twelfth month of the year.
int FEBRUARY Value of the MONTH field indicating the second month of the year.
int FRIDAY Value of the DAY_OF_WEEK field indicating Friday.
int HOUR Field number for get and set indicating the hour of the morning or afternoon.
int HOUR_OF_DAY Field number for get and set indicating the hour of the day.
int JANUARY Value of the MONTH field indicating the first month of the year.
int JULY Value of the MONTH field indicating the seventh month of the year.
int JUNE Value of the MONTH field indicating the sixth month of the year.
int MARCH Value of the MONTH field indicating the third month of the year.
int MAY Value of the MONTH field indicating the fifth month of the year.
int MILLISECOND Field number for get and set indicating the millisecond within the second.
int MINUTE Field number for get and set indicating the minute within the hour.
int MONDAY Value of the DAY_OF_WEEK field indicating Monday.
int MONTH Field number for get and set indicating the month.
int NOVEMBER Value of the MONTH field indicating the eleventh month of the year.
int OCTOBER Value of the MONTH field indicating the tenth month of the year.
int PM Value of the AM_PM field indicating the period of the day from noon to just before midnight.
int SATURDAY Value of the DAY_OF_WEEK field indicating Saturday.
int SECOND Field number for get and set indicating the second within the minute.
int SEPTEMBER Value of the MONTH field indicating the ninth month of the year.
int SUNDAY Value of the DAY_OF_WEEK field indicating Sunday.
int THURSDAY Value of the DAY_OF_WEEK field indicating Thursday.
int TUESDAY Value of the DAY_OF_WEEK field indicating Tuesday.
int WEDNESDAY Value of the DAY_OF_WEEK field indicating Wednesday.
int WEEK_OF_YEAR Field number for get and set indicating the week number within the current year.
int YEAR Field number for get and set indicating the year.
Protected Constructors
Calendar()
Constructs a Calendar with the default time zone and default locale.
Public Methods
boolean after(Object when)
Compares the time field records.
boolean before(Object when)
Compares the time field records.
boolean equals(Object obj)
Compares this calendar to the specified object.
final int get(int field)
Gets the value for a given time field.
int getFirstDayOfWeek()
Gets what the first day of the week is; e.g., SUNDAY in the U.S., MONDAY in France.
synchronized static Calendar getInstance()
Gets a calendar using the default time zone and default locale.
synchronized static Calendar getInstance(TimeZone zone)
Gets a calendar using the specified time zone and default locale.
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, this method returns 1.
final Date getTime()
Gets this Calendar's current time.
TimeZone getTimeZone()
Gets the time zone.
final void set(int field, int value)
Sets the time field with the given value.
void setFirstDayOfWeek(int value)
Sets what the first day of the week is; e.g., SUNDAY in the U.S., MONDAY in France.
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 this method with value 1.
final void setTime(Date date)
Sets this Calendar's current time with the given Date.
void setTimeZone(TimeZone value)
Sets the time zone with the given time zone value.
Protected Methods
long getTimeInMillis()
Gets this Calendar's current time as a long expressed in milliseconds after January 1, 1970, 0:00:00 GMT (the epoch).
void setTimeInMillis(long millis)
Sets this Calendar's current time from the given long value.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int AM

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

Constant Value: 0 (0x00000000)

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
Constant Value: 9 (0x00000009)

public static final int APRIL

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

Constant Value: 3 (0x00000003)

public static final int AUGUST

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

Constant Value: 7 (0x00000007)

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.

See Also
Constant Value: 5 (0x00000005)

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.

See Also
Constant Value: 5 (0x00000005)

public static final int DAY_OF_WEEK

Field number for get and set indicating the day of the week.

Constant Value: 7 (0x00000007)

public static final int DECEMBER

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

Constant Value: 11 (0x0000000b)

public static final int FEBRUARY

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

Constant Value: 1 (0x00000001)

public static final int FRIDAY

Value of the DAY_OF_WEEK field indicating Friday.

Constant Value: 6 (0x00000006)

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
Constant Value: 10 (0x0000000a)

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.

Constant Value: 11 (0x0000000b)

public static final int JANUARY

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

Constant Value: 0 (0x00000000)

public static final int JULY

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

Constant Value: 6 (0x00000006)

public static final int JUNE

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

Constant Value: 5 (0x00000005)

public static final int MARCH

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

Constant Value: 2 (0x00000002)

public static final int MAY

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

Constant Value: 4 (0x00000004)

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.

Constant Value: 14 (0x0000000e)

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.

Constant Value: 12 (0x0000000c)

public static final int MONDAY

Value of the DAY_OF_WEEK field indicating Monday.

Constant Value: 2 (0x00000002)

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.

Constant Value: 2 (0x00000002)

public static final int NOVEMBER

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

Constant Value: 10 (0x0000000a)

public static final int OCTOBER

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

Constant Value: 9 (0x00000009)

public static final int PM

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

Constant Value: 1 (0x00000001)

public static final int SATURDAY

Value of the DAY_OF_WEEK field indicating Saturday.

Constant Value: 7 (0x00000007)

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.

Constant Value: 13 (0x0000000d)

public static final int SEPTEMBER

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

Constant Value: 8 (0x00000008)

public static final int SUNDAY

Value of the DAY_OF_WEEK field indicating Sunday.

Constant Value: 1 (0x00000001)

public static final int THURSDAY

Value of the DAY_OF_WEEK field indicating Thursday.

Constant Value: 5 (0x00000005)

public static final int TUESDAY

Value of the DAY_OF_WEEK field indicating Tuesday.

Constant Value: 3 (0x00000003)

public static final int WEDNESDAY

Value of the DAY_OF_WEEK field indicating Wednesday.

Constant Value: 4 (0x00000004)

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.

Constant Value: 3 (0x00000003)

public static final int YEAR

Field number for get and set indicating the year. This is a calendar-specific value.

Constant Value: 1 (0x00000001)

Protected Constructors

protected Calendar ()

Constructs a Calendar with the default time zone and default locale.

See Also

Public Methods

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.

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.

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.

Parameters
obj the object to compare with.
Returns
  • true if the objects are the same; false otherwise.

public final int get (int field)

Gets the value for a given time field.

Parameters
field the given time field (either YEAR, MONTH, DATE, DAY_OF_WEEK, HOUR_OF_DAY, HOUR, AM_PM, MINUTE, SECOND, or MILLISECOND
Returns
  • the value for the given time field.
Throws
ArrayIndexOutOfBoundsException if the parameter is not one of the above.

public int getFirstDayOfWeek ()

Gets what the first day of the week is; e.g., SUNDAY in the U.S., MONDAY in France.

Returns
  • the first day of the week.

public static synchronized Calendar getInstance ()

Gets a calendar using the default time zone and default locale.

Returns
  • a Calendar.

public static synchronized Calendar getInstance (TimeZone zone)

Gets a calendar using the specified time zone and default locale.

Parameters
zone the time zone to use
Returns
  • a Calendar.

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, this method returns 1. If the minimal days required must be a full week, this method returns 7.

Returns
  • the minimal days required in the first week of the year.

public final Date getTime ()

Gets this Calendar's current time.

Returns
  • the current time.
See Also

public TimeZone getTimeZone ()

Gets the time zone.

Returns
  • the time zone object associated with this calendar.
See Also

public final void set (int field, int value)

Sets the time field with the given value.

Parameters
field the given time field. Note that the DAY_OF_WEEK field cannot be set.
value the value to be set for the given time field.
Throws
ArrayIndexOutOfBoundsException if an illegal field parameter is received.

public void setFirstDayOfWeek (int value)

Sets what the first day of the week is; e.g., SUNDAY in the U.S., MONDAY in France.

Parameters
value the given first day of the week.

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

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

public void setTimeZone (TimeZone value)

Sets the time zone with the given time zone value.

Parameters
value the given time zone.
See Also

Protected Methods

protected long getTimeInMillis ()

Gets this Calendar's current time as a long expressed in milliseconds after January 1, 1970, 0:00:00 GMT (the epoch).

Returns
  • the current time as UTC milliseconds from the epoch.
See Also

protected 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