Calendar class is an abstract class that provides methods
for converting between a specific instant in time and a set of fieldsYEAR, MONTH,
DAY_OF_MONTH, HOUR, and so on, and for
manipulating the calendar fields, such as getting the date of the next
week. An instant in time can be represented by a millisecond value that is
an offset from the Epoch, January 1, 1970
00:00:00.000 GMT (Gregorian).
The class also provides additional fields and methods for
implementing a concrete calendar system outside the package. Those
fields and methods are defined as protected.
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
calendar fields have been initialized with the current date and time:
Calendar rightNow = Calendar.getInstance();
A Calendar object can produce all the calendar 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 calendar fields, as well as their meaning. For example,
the first month of the calendar system has value MONTH ==
JANUARY for all calendars. Other values are defined by the
concrete subclass, such as ERA. See individual field
documentation and subclass documentation for details.
The calendar field values can be set by calling the set
methods. Any field values set in a Calendar will not be
interpreted until it needs to calculate its time value (milliseconds from
the Epoch) or values of the calendar fields. Calling the
get, getTimeInMillis, getTime,
add and roll involves such calculation.
Calendar has two modes for interpreting the calendar
fields, lenient and non-lenient. When a
Calendar is in lenient mode, it accepts a wider range of
calendar field values than it produces. When a Calendar
recomputes calendar field values for return by get(), all of
the calendar fields are normalized. For example, a lenient
GregorianCalendar interprets MONTH == JANUARY,
DAY_OF_MONTH == 32 as February 1.
When a Calendar is in non-lenient mode, it throws an
exception if there is any inconsistency in its calendar fields. For
example, a GregorianCalendar always produces
DAY_OF_MONTH values between 1 and the length of the month. A
non-lenient GregorianCalendar throws an exception upon
calculating its time or calendar field values if any out-of-range field
value has been set.
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 methods for setting their values.
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.
Calendar will resolve
calendar field values to determine the date and time in the
following way.
If there is any conflict in calendar field values,
Calendar gives priorities to calendar fields that have been set
more recently. The following are the default combinations of the
calendar fields. The most recent combination, as determined by the
most recently set single field, will be used.
For the date fields:
For the time of day fields:YEAR + MONTH + DAY_OF_MONTH YEAR + MONTH + WEEK_OF_MONTH + DAY_OF_WEEK YEAR + MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK YEAR + DAY_OF_YEAR YEAR + DAY_OF_WEEK + WEEK_OF_YEAR
HOUR_OF_DAY AM_PM + HOUR
If there are any calendar fields whose values haven't been set in the selected
field combination, Calendar uses their default values. The default
value of each field may vary by concrete calendar systems. For example, in
GregorianCalendar, the default of a field is the same as that
of the start of the Epoch: i.e., YEAR = 1970, MONTH =
JANUARY, DAY_OF_MONTH = 1, etc.
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
set(), add(), and roll().
set(f, value) changes calendar field
f to value. In addition, it sets an
internal member variable to indicate that calendar field f has
been changed. Although calendar field f is changed immediately,
the calendar's time value in milliseconds is not recomputed until the next call to
get(), getTime(), getTimeInMillis(),
add(), or roll() is made. Thus, multiple calls to
set() do not trigger multiple, unnecessary
computations. As a result of changing a calendar field using
set(), other calendar fields may also change, depending on the
calendar field, the calendar field value, and the calendar system. In addition,
get(f) will not necessarily return value set by
the call to the set method
after the calendar 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 date 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 date 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 or other constraints, such as time zone offset changes, 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, 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_MONTHis a larger field thanHOUR.
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.
java.lang.System.currentTimeMillis()DateGregorianCalendarTimeZonejava.text.DateFormatget 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.
DAY_OF_MONTHget and set indicating the
day of the month. This is a synonym for DATE.
The first day of the month has value 1.
DATEget 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.
DAY_OF_WEEKWEEK_OF_MONTHget and set indicating the
hour of the morning or afternoon. HOUR is used for the
12-hour clock (0 - 11). Noon and midnight are represented by 0, not by 12.
E.g., at 10:04:15.250 PM the HOUR is 10.
AM_PMHOUR_OF_DAYget 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.
HOURMONTHMONTHMONTHMONTHMONTHMONTHMONTHMONTHMONTHMONTHMONTHMONTHMONTHGregorianCalendar
does not use this value, lunar calendars do.
getDisplayName and getDisplayNames indicating a short name, such as "Jan".
LONG getDisplayName and getDisplayNames indicating a long name, such as "January".
SHORTisTimeSettime is valid.
The time is made invalid by a change to an item of field[].
timeTrue if this calendar allows out-of-range field values during computation
of time from fields[].
setLenient(boolean)isLenient()serialVersionOnStream
is written.
fields[]
to the millisecond time value
timecomplete()computeFields()timefields[].
This allows you to sync up the calendar 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()computeTime()Date object representing this
Calendar's time value (millisecond offset from the Epoch").
Date representing the time value.setTime(java.util.Date)getTimeInMillis()Date.
Note: Calling setTime() with
Date(Long.MAX_VALUE) or Date(Long.MIN_VALUE)
may yield incorrect field values from get().
date the given Date.getTime()setTimeInMillis(long)getTime()setTimeInMillis(long)millis the new time in UTC milliseconds from the epoch.setTime(java.util.Date)getTimeInMillis()complete()field the given calendar field.java.lang.ArrayIndexOutOfBoundsException if the specified field is out of range
(field < 0 || field >= FIELD_COUNT).set(int,int)complete()field the given calendar field.get(int)Calendar instance.
java.lang.IndexOutOfBoundsException if the specified field is out of range
(field < 0 || field >= FIELD_COUNT).areFieldsSetisTimeSetareAllFieldsSetset(int,int)field the given calendar field.value the value to be set for the given calendar field.java.lang.ArrayIndexOutOfBoundsException if the specified field is out of range
(field < 0 || field >= FIELD_COUNT).
in non-lenient mode.set(int,int,int)set(int,int,int,int,int)set(int,int,int,int,int,int)get(int)YEAR,
MONTH, and DAY_OF_MONTH.
Previous values of other calendar fields are retained. If this is not desired,
call clear()year the value used to set the YEAR calendar field.month the value used to set the MONTH calendar field.
Month value is 0-based. e.g., 0 for January.date the value used to set the DAY_OF_MONTH calendar field.set(int,int)set(int,int,int,int,int)set(int,int,int,int,int,int)YEAR,
MONTH, DAY_OF_MONTH,
HOUR_OF_DAY, and MINUTE.
Previous values of other fields are retained. If this is not desired,
call clear()year the value used to set the YEAR calendar field.month the value used to set the MONTH calendar field.
Month value is 0-based. e.g., 0 for January.date the value used to set the DAY_OF_MONTH calendar field.hourOfDay the value used to set the HOUR_OF_DAY calendar field.minute the value used to set the MINUTE calendar field.set(int,int)set(int,int,int)set(int,int,int,int,int,int)YEAR, MONTH,
DAY_OF_MONTH, HOUR, MINUTE, and
SECOND.
Previous values of other fields are retained. If this is not desired,
call clear()year the value used to set the YEAR calendar field.month the value used to set the MONTH calendar field.
Month value is 0-based. e.g., 0 for January.date the value used to set the DAY_OF_MONTH calendar field.hourOfDay the value used to set the HOUR_OF_DAY calendar field.minute the value used to set the MINUTE calendar field.second the value used to set the SECOND calendar field.set(int,int)set(int,int,int)set(int,int,int,int,int)Calendar undefined. This means that isSet(int)false for all the
calendar fields, and the date and time calculations will treat
the fields as if they had never been set. A
Calendar implementation class may use its specific
default field values for date/time calculations. For example,
GregorianCalendar uses 1970 if the
YEAR field value is undefined.
clear(int)Calendar undefined. This means that isSet(int)false, and
the date and time calculations will treat the field as if it
had never been set. A Calendar implementation
class may use the field's specific default value for date and
time calculations.
The HOUR_OF_DAYHOURAM_PMCalendar. Use set(int,int)
field the calendar field to be cleared.clear()field value in the given style and
locale. If no string representation is
applicable, null is returned. This method calls
get(field) to get the calendar
field value if the string representation is
applicable to the given calendar field.
For example, if this Calendar is a
GregorianCalendar and its date is 2005-01-01, then
the string representation of the MONTHDAY_OF_MONTHnull.
The default implementation supports the calendar fields for
which a java.text.DateFormatSymbolslocale.
field
the calendar field for which the string representation
is returnedstyle
the style applied to the string representation; one of
SHORTLONGlocale
the locale for the string representationfield in the given style, or
null if no string representation is
applicable.java.lang.IllegalArgumentException
if field or style is invalid,
or if this Calendar is non-lenient and any
of the calendar fields have invalid valuesjava.lang.NullPointerException
if locale is nullMap containing all names of the calendar
field in the given style and
locale and their corresponding field values. For
example, if this Calendar is a GregorianCalendarJANUARYFEBRUARYThe values of other calendar fields may be taken into
account to determine a set of display names. For example, if
this Calendar is a lunisolar calendar system and
the year value given by the YEAR
The default implementation supports display names contained in
a java.text.DateFormatSymbolsfield
is MONTHstyle is ALL_STYLESMap containing
all strings returned by java.text.DateFormatSymbols.getShortMonths()java.text.DateFormatSymbols.getMonths()
field
the calendar field for which the display names are returnedstyle
the style applied to the display names; one of SHORTLONGALL_STYLESlocale
the locale for the display namesMap containing all display names in
style and locale and their
field values, or null if no display names
are defined for fieldjava.lang.IllegalArgumentException
if field or style is invalid,
or if this Calendar is non-lenient and any
of the calendar fields have invalid valuesjava.lang.NullPointerException
if locale is nullcomputeTime()computeFields()true if the field has been set externally,
false otherwise.java.lang.IndexOutOfBoundsException if the specified
field is out of range
(field < 0 || field >= FIELD_COUNT).selectFields()setFieldsComputed(int)fieldMask the field to be marked as computed.java.lang.IndexOutOfBoundsException if the specified
field is out of range
(field < 0 || field >= FIELD_COUNT).isExternallySet(int)selectFields()fieldMask to unset. If fieldMask
specifies all the calendar fields, then the state of this
Calendar becomes that all the calendar fields are in sync
with the time value (millisecond offset from the Epoch).
fieldMask the field mask indicating which calendar fields are in
sync with the time value.java.lang.IndexOutOfBoundsException if the specified
field is out of range
(field < 0 || field >= FIELD_COUNT).isExternallySet(int)selectFields()field is (1 <<
field). For example, 0x26 represents the YEAR,
MONTH, and DAY_OF_MONTH fields (i.e., 0x26 is
equal to
(1<<YEAR)|(1<<MONTH)|(1<<DAY_OF_MONTH)).
This method supports the calendar fields resolution as described in
the class description. If the bit mask for a given field is on and its
field has not been set (i.e., isSet(field) is
false), then the default value of the field has to be
used, which case means that the field has been selected because the
selected combination involves the field.
isExternallySet(int)setInternallySetState(int)Calendar to the specified
Object. The result is true if and only if
the argument is a Calendar object of the same calendar
system that represents the same time value (millisecond offset from the
Epoch) under the same
Calendar parameters as this object.
The Calendar parameters are the values represented
by the isLenient, getFirstDayOfWeek,
getMinimalDaysInFirstWeek and getTimeZone
methods. If there is any difference in those parameters
between the two Calendars, this method returns
false.
Use the compareTo method to
compare only the time values.
obj the object to compare with.true if this object is equal to obj;
false otherwise.Calendar represents a time
before the time represented by the specified
Object. This method is equivalent to:
if and only ifcompareTo(when) < 0
when is a Calendar
instance. Otherwise, the method returns false.
when the Object to be comparedtrue if the time of this
Calendar is before the time represented by
when; false otherwise.compareTo(java.util.Calendar)Calendar represents a time
after the time represented by the specified
Object. This method is equivalent to:
if and only ifcompareTo(when) > 0
when is a Calendar
instance. Otherwise, the method returns false.
when the Object to be comparedtrue if the time of this Calendar is
after the time represented by when; false
otherwise.compareTo(java.util.Calendar)Calendar objects.
anotherCalendar the Calendar to be compared.0 if the time represented by the argument
is equal to the time represented by this Calendar; a value
less than 0 if the time of this Calendar is
before the time represented by the argument; and a value greater than
0 if the time of this Calendar is after the
time represented by the argument.java.lang.NullPointerException if the specified Calendar is
null.java.lang.IllegalArgumentException if the time value of the
specified Calendar object can't be obtained due to
any invalid calendar values.add(Calendar.DAY_OF_MONTH, -5).
field the calendar field.amount the amount of date or time to be added to the field.roll(int,int)set(int,int)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.
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.add(int,int)set(int,int)NOTE: This default implementation on Calendar just repeatedly calls the
version of roll() that 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.
field the calendar field.amount the signed amount to add to the calendar field.roll(int,boolean)add(int,int)set(int,int)lenient true if the lenient mode is to be turned
on; false if it is to be turned off.isLenient()java.text.DateFormat.setLenient(boolean)true if the interpretation mode of this calendar is lenient;
false otherwise.setLenient(boolean)SUNDAY in the U.S.,
MONDAY in France.
value the given first day of the week.getFirstDayOfWeek()getMinimalDaysInFirstWeek()SUNDAY in the U.S.,
MONDAY in France.
setFirstDayOfWeek(int)getMinimalDaysInFirstWeek()value the given minimal days required in the first week
of the year.getMinimalDaysInFirstWeek()setMinimalDaysInFirstWeek(int)Calendar instance. The minimum value is defined as
the smallest value returned by the get method
for any possible time value. The minimum value depends on
calendar system specific parameters of the instance.
field the calendar field.getMaximum(int)getGreatestMinimum(int)getLeastMaximum(int)getActualMinimum(int)getActualMaximum(int)Calendar instance. The maximum value is defined as
the largest value returned by the get method
for any possible time value. The maximum value depends on
calendar system specific parameters of the instance.
field the calendar field.getMinimum(int)getGreatestMinimum(int)getLeastMaximum(int)getActualMinimum(int)getActualMaximum(int)Calendar instance. The highest minimum
value is defined as the largest value returned by getActualMinimum(int)field the calendar field.getMinimum(int)getMaximum(int)getLeastMaximum(int)getActualMinimum(int)getActualMaximum(int)Calendar instance. The lowest maximum
value is defined as the smallest value returned by getActualMaximum(int)Calendar for the
Gregorian calendar system returns 28 for the
DAY_OF_MONTH field, because the 28th is the last
day of the shortest month of this calendar, February in a
common year.
field the calendar field.getMinimum(int)getMaximum(int)getGreatestMinimum(int)getActualMinimum(int)getActualMaximum(int)Calendar.
The default implementation of this method uses an iterative
algorithm to determine the actual minimum value for the
calendar field. Subclasses should, if possible, override this
with a more efficient implementation - in many cases, they can
simply return getMinimum().
field the calendar fieldCalendargetMinimum(int)getMaximum(int)getGreatestMinimum(int)getLeastMaximum(int)getActualMaximum(int)Calendar. For example, the actual maximum value of
the MONTH field is 12 in some years, and 13 in
other years in the Hebrew calendar system.
The default implementation of this method uses an iterative algorithm to determine the actual maximum value for the calendar field. Subclasses should, if possible, override this with a more efficient implementation.
field the calendar fieldCalendargetMinimum(int)getMaximum(int)getGreatestMinimum(int)getLeastMaximum(int)getActualMinimum(int)field the calendar fieldjava.lang.IndexOutOfBoundsException if field is negative,
equal to or greater then FIELD_COUNT.Calendar would only write out its state data and
the current time, and not write any field data out, such as
fields[], isTimeSet, areFieldsSet,
and isSet[]. nextStamp also should not be part
of the persistent state. Unfortunately, this didn't happen before JDK 1.1
shipped. To be compatible with JDK 1.1, we will always have to write out
the field values and state flags. However, nextStamp can be
removed from the serialization stream; this will probably happen in the
near future.