All Packages Class Hierarchy This Package Previous Next Index
java.lang.Object | +----java.util.Calendar
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.
For the time of day: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
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:
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.
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
fafter the call minus the value of fieldfbefore the call isdelta, modulo any overflow that has occurred in fieldf. 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
fis 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.HOURis a smaller field thanDAY_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, up/down) adds
+1/-1 to field f without changing larger
fields. This is equivalent to calling add(f, +1/-1) with
the following adjustment:
Roll rule. Larger fields are unchanged after the call. A larger field represents a larger unit of time.
DAY_OF_MONTHis a larger field thanHOUR.
Example: Consider a GregorianCalendar originally
set to October 31, 1999. Calling roll(Calendar.MONTH, true)
sets the calendar to Novermber 30, 1999. Add
rule 1 sets the MONTH field to November. Using a
GregorianCalendar, the DAY_OF_MONTH cannot
be 31 in the month November. Add rule 2 sets it to the closest possible
value, 30. Calling roll(Calendar.MONTH, true) two more 
times sets the calendar further to Jaunary 30, 1999. When 
rolling from December to January, the roll rule maintains 
the YEAR field value of 1999.
Example: Consider a GregorianCalendar
originally set to Sunday June 6, 1999. Calling
roll(Calendar.WEEK_OF_MONTH, false) sets the calendar to
Tuesday June 1, 1999, whereas calling
add(Calendar.WEEK_OF_MONTH, -1) sets the calendar to
Sunday May 30, 1999. This is because the roll rule imposes an
additional constraint: The MONTH must not change when the
WEEK_OF_MONTH is rolled. Taken together with add rule 1,
the resultant date must be between Tuesday June 1 and Saturday June
5. According to add rule 2, the DAY_OF_WEEK, an invariant
when changing the WEEK_OF_MONTH, is set to Tuesday, the
closest possible value to Sunday (where Sunday is the first day of the
week).
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.  If the underlying
implementation uses add(Calendar.MONTH, 1),
it will read 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
add(Calendar.MONTH, 2), after the user presses the month
increment button twice, it will read March 31, 1999 as most users
will intuitively expect.  In contrast, since roll() can
only go up or down by one, calling roll(Calendar.MONTH, true)
twice will result in March 28, 1999.  In addition, roll() 
does not change the YEAR field.
 
 AM
	AM
   AM_PM
	AM_PM
   APRIL
	APRIL
   areFieldsSet
	areFieldsSet
   AUGUST
	AUGUST
   DATE
	DATE
   DAY_OF_MONTH
	DAY_OF_MONTH
   DAY_OF_WEEK
	DAY_OF_WEEK
   DAY_OF_WEEK_IN_MONTH
	DAY_OF_WEEK_IN_MONTH
   DAY_OF_YEAR
	DAY_OF_YEAR
   DECEMBER
	DECEMBER
   DST_OFFSET
	DST_OFFSET
   ERA
	ERA
   FEBRUARY
	FEBRUARY
   FIELD_COUNT
	FIELD_COUNT
   fields
	fields
   FRIDAY
	FRIDAY
   HOUR
	HOUR
   HOUR_OF_DAY
	HOUR_OF_DAY
   isSet
	isSet
   isTimeSet
	isTimeSet
   JANUARY
	JANUARY
   JULY
	JULY
   JUNE
	JUNE
   MARCH
	MARCH
   MAY
	MAY
   MILLISECOND
	MILLISECOND
   MINUTE
	MINUTE
   MONDAY
	MONDAY
   MONTH
	MONTH
   NOVEMBER
	NOVEMBER
   OCTOBER
	OCTOBER
   PM
	PM
   SATURDAY
	SATURDAY
   SECOND
	SECOND
   SEPTEMBER
	SEPTEMBER
   SUNDAY
	SUNDAY
   THURSDAY
	THURSDAY
   time
	time
   TUESDAY
	TUESDAY
   UNDECIMBER
	UNDECIMBER
   WEDNESDAY
	WEDNESDAY
   WEEK_OF_MONTH
	WEEK_OF_MONTH
   WEEK_OF_YEAR
	WEEK_OF_YEAR
   YEAR
	YEAR
   ZONE_OFFSET
	ZONE_OFFSET
   
 Calendar()
	Calendar()
   Calendar(TimeZone, Locale)
	Calendar(TimeZone, Locale)
   
 add(int, int)
	add(int, int)
   after(Object)
	after(Object)
   before(Object)
	before(Object)
   clear()
	clear()
   clear(int)
	clear(int)
   clone()
	clone()
   complete()
	complete()
   computeFields()
	computeFields()
   computeTime()
	computeTime()
   equals(Object)
	equals(Object)
   get(int)
	get(int)
   getAvailableLocales()
	getAvailableLocales()
   getFirstDayOfWeek()
	getFirstDayOfWeek()
   getGreatestMinimum(int)
	getGreatestMinimum(int)
   getInstance()
	getInstance()
   getInstance(Locale)
	getInstance(Locale)
   getInstance(TimeZone)
	getInstance(TimeZone)
   getInstance(TimeZone, Locale)
	getInstance(TimeZone, Locale)
   getLeastMaximum(int)
	getLeastMaximum(int)
   getMaximum(int)
	getMaximum(int)
   getMinimalDaysInFirstWeek()
	getMinimalDaysInFirstWeek()
   getMinimum(int)
	getMinimum(int)
   getTime()
	getTime()
   getTimeInMillis()
	getTimeInMillis()
   getTimeZone()
	getTimeZone()
   internalGet(int)
	internalGet(int)
   isLenient()
	isLenient()
   isSet(int)
	isSet(int)
   roll(int, boolean)
	roll(int, boolean)
   set(int, int)
	set(int, int)
   set(int, int, int)
	set(int, int, int)
   set(int, int, int, int, int)
	set(int, int, int, int, int)
   set(int, int, int, int, int, int)
	set(int, int, int, int, int, int)
   setFirstDayOfWeek(int)
	setFirstDayOfWeek(int)
   setLenient(boolean)
	setLenient(boolean)
   setMinimalDaysInFirstWeek(int)
	setMinimalDaysInFirstWeek(int)
   setTime(Date)
	setTime(Date)
   setTimeInMillis(long)
	setTimeInMillis(long)
   setTimeZone(TimeZone)
	setTimeZone(TimeZone)
   toString()
	toString()
   
 ERA
ERA
public static final int ERA
 YEAR
YEAR
public static final int YEAR
 MONTH
MONTH
public static final int MONTH
 WEEK_OF_YEAR
WEEK_OF_YEAR
public static final int WEEK_OF_YEAR
 WEEK_OF_MONTH
WEEK_OF_MONTH
public static final int WEEK_OF_MONTH
 DATE
DATE
public static final int DATE
 DAY_OF_MONTH
DAY_OF_MONTH
public static final int DAY_OF_MONTH
 DAY_OF_YEAR
DAY_OF_YEAR
public static final int DAY_OF_YEAR
 DAY_OF_WEEK
DAY_OF_WEEK
public static final int DAY_OF_WEEK
 DAY_OF_WEEK_IN_MONTH
DAY_OF_WEEK_IN_MONTH
public static final int DAY_OF_WEEK_IN_MONTH
 AM_PM
AM_PM
public static final int AM_PM
 HOUR
HOUR
public static final int HOUR
 HOUR_OF_DAY
HOUR_OF_DAY
public static final int HOUR_OF_DAY
 MINUTE
MINUTE
public static final int MINUTE
 SECOND
SECOND
public static final int SECOND
 MILLISECOND
MILLISECOND
public static final int MILLISECOND
 ZONE_OFFSET
ZONE_OFFSET
public static final int ZONE_OFFSET
 DST_OFFSET
DST_OFFSET
public static final int DST_OFFSET
 FIELD_COUNT
FIELD_COUNT
public static final int FIELD_COUNT
 SUNDAY
SUNDAY
public static final int SUNDAY
 MONDAY
MONDAY
public static final int MONDAY
 TUESDAY
TUESDAY
public static final int TUESDAY
 WEDNESDAY
WEDNESDAY
public static final int WEDNESDAY
 THURSDAY
THURSDAY
public static final int THURSDAY
 FRIDAY
FRIDAY
public static final int FRIDAY
 SATURDAY
SATURDAY
public static final int SATURDAY
 JANUARY
JANUARY
public static final int JANUARY
 FEBRUARY
FEBRUARY
public static final int FEBRUARY
 MARCH
MARCH
public static final int MARCH
 APRIL
APRIL
public static final int APRIL
 MAY
MAY
public static final int MAY
 JUNE
JUNE
public static final int JUNE
 JULY
JULY
public static final int JULY
 AUGUST
AUGUST
public static final int AUGUST
 SEPTEMBER
SEPTEMBER
public static final int SEPTEMBER
 OCTOBER
OCTOBER
public static final int OCTOBER
 NOVEMBER
NOVEMBER
public static final int NOVEMBER
 DECEMBER
DECEMBER
public static final int DECEMBER
 UNDECIMBER
UNDECIMBER
public static final int UNDECIMBER
 AM
AM
public static final int AM
 PM
PM
public static final int PM
 fields
fields
protected int fields[]
 isSet
isSet
protected boolean isSet[]
 time
time
protected long time
 isTimeSet
isTimeSet
protected boolean isTimeSet
 areFieldsSet
areFieldsSet
protected boolean areFieldsSet
 
 Calendar
Calendar
protected Calendar()
 Calendar
Calendar
 protected Calendar(TimeZone zone,
                    Locale aLocale)
 
 getInstance
getInstance
public static synchronized Calendar getInstance()
 getInstance
getInstance
public static synchronized Calendar getInstance(TimeZone zone)
 getInstance
getInstance
public static synchronized Calendar getInstance(Locale aLocale)
 getInstance
getInstance
 public static synchronized Calendar getInstance(TimeZone zone,
                                                 Locale aLocale)
 getAvailableLocales
getAvailableLocales
public static synchronized Locale[] getAvailableLocales()
 computeTime
computeTime
protected abstract void computeTime()
 computeFields
computeFields
protected abstract void computeFields()
complete method.
 getTime
getTime
public final Date getTime()
 setTime
setTime
public final void setTime(Date date)
 getTimeInMillis
getTimeInMillis
protected long getTimeInMillis()
 setTimeInMillis
setTimeInMillis
protected void setTimeInMillis(long millis)
 get
get
public final int get(int field)
 internalGet
internalGet
protected final int internalGet(int field)
 set
set
 public final void set(int field,
                       int value)
 set
set
 public final void set(int year,
                       int month,
                       int date)
clear first.
 set
set
 public final void set(int year,
                       int month,
                       int date,
                       int hour,
                       int minute)
clear first.
 set
set
 public final void set(int year,
                       int month,
                       int date,
                       int hour,
                       int minute,
                       int second)
clear first.
 clear
clear
public final void clear()
 clear
clear
public final void clear(int field)
 isSet
isSet
public final boolean isSet(int field)
 complete
complete
protected void complete()
 equals
equals
public abstract boolean equals(Object obj)
true if and only if the argument is
 not null and is a Calendar object that
 represents the same calendar as this object.
true if the objects are the same;
 false otherwise.
     before
before
public abstract boolean before(Object when)
 after
after
public abstract boolean after(Object when)
 add
add
 public abstract void add(int field,
                          int amount)
add(Calendar.DATE, -5).
 roll
roll
 public abstract void roll(int field,
                           boolean up)
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.
 setTimeZone
setTimeZone
public void setTimeZone(TimeZone value)
 getTimeZone
getTimeZone
public TimeZone getTimeZone()
 setLenient
setLenient
public void setLenient(boolean lenient)
 isLenient
isLenient
public boolean isLenient()
 setFirstDayOfWeek
setFirstDayOfWeek
public void setFirstDayOfWeek(int value)
 getFirstDayOfWeek
getFirstDayOfWeek
public int getFirstDayOfWeek()
 setMinimalDaysInFirstWeek
setMinimalDaysInFirstWeek
public void setMinimalDaysInFirstWeek(int value)
 getMinimalDaysInFirstWeek
getMinimalDaysInFirstWeek
public int getMinimalDaysInFirstWeek()
 getMinimum
getMinimum
public abstract int getMinimum(int field)
 getMaximum
getMaximum
public abstract int getMaximum(int field)
 getGreatestMinimum
getGreatestMinimum
public abstract int getGreatestMinimum(int field)
 getLeastMaximum
getLeastMaximum
public abstract int getLeastMaximum(int field)
 clone
clone
public Object clone()
 toString
toString
public String toString()
All Packages Class Hierarchy This Package Previous Next Index