Calendar

GregorianCalendar is a concrete subclass of
Calendar and provides the standard calendar system
used by most of the world.

The Calendar class is an abstract class that provides methods
for converting between a specific instant in time and a set of calendar fields such as YEAR, 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.

Getting and Setting Calendar Field Values

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.

Leniency

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 Fields Resolution

When computing a date and time from the calendar fields, there
may be insufficient information for the computation (such as only
year and month with no day of month), or there may be inconsistent
information (such as Tuesday, July 15, 1996 (Gregorian) -- July 15,
1996 is actually a Monday). 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.

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:

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.

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

The calendar fields can be changed using three methods:
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 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 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. 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.

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.

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.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

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.

FRIDAY

HOUR

Field number for get 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.

MONDAY

MONTH

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

WEDNESDAY

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.

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.

isSet

The flags which tell if a specified calendar 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.

Public methods

add

Adds or subtracts the specified amount of time to the given calendar 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:

clear

Sets all the calendar field values and the time value
(millisecond offset from the Epoch) of
this Calendar undefined. This means that isSet() will return 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

Sets the given calendar field value and the time value
(millisecond offset from the Epoch) of
this Calendar undefined. This means that isSet(field) will return 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.

clone

compareTo

Compares the time values (millisecond offsets from the Epoch) represented by two
Calendar objects.

Parameters

anotherCalendar

Calendar:
the Calendar to be compared.

Returns

int

the value 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.

equals

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

get

Returns the value of the given calendar field. In lenient mode,
all calendar fields are normalized. In non-lenient mode, all
calendar fields are validated and this method throws an
exception if any calendar fields have out-of-range values. The
normalization and validation are handled by the
complete() method, which process is calendar
system dependent.

getActualMaximum

Returns the maximum value that the specified calendar field
could have, given the time value of this
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.

Parameters

field

int:
the calendar field

Returns

int

the maximum of the given calendar field for the time
value of this Calendar

getActualMinimum

Returns the minimum value that the specified calendar field
could have, given the time value of this 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().

Parameters

field

int:
the calendar field

Returns

int

the minimum of the given calendar field for the time
value of this Calendar

getDisplayName

Returns the string representation of the calendar
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 MONTH field would be
"January" in the long style in an English locale or "Jan" in
the short style. However, no string representation would be
available for the DAY_OF_MONTH field, and this method
would return null.

The default implementation supports the calendar fields for
which a DateFormatSymbols has names in the given
locale.

Parameters

field

int:
the calendar field for which the string representation
is returned

style

int:
the style applied to the string representation; one of
SHORT or LONG.

getDisplayNames

Returns a Map 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 GregorianCalendar, the returned map would contain "Jan" to
JANUARY, "Feb" to FEBRUARY, and so on, in the
short style in an English locale.

The 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 field has a leap
month, this method would return month names containing the leap
month name, and month names are mapped to their values specific
for the year.

getGreatestMinimum

Returns the highest minimum value for the given calendar field
of this Calendar instance. The highest minimum
value is defined as the largest value returned by getActualMinimum(int) for any possible time value. The
greatest minimum value depends on calendar system specific
parameters of the instance.

getLeastMaximum

Returns the lowest maximum value for the given calendar field
of this Calendar instance. The lowest maximum
value is defined as the smallest value returned by getActualMaximum(int) for any possible time value. The least
maximum value depends on calendar system specific parameters of
the instance. For example, a 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.

getMaximum

Returns the maximum value for the given calendar field of this
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.

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.

getMinimum

Returns the minimum value for the given calendar field of this
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.

roll

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

int:
the time field.

up

boolean:
indicates if the value of the specified time field is to be
rolled up or rolled down. Use true if rolling up, false otherwise.

roll

Adds the specified (signed) amount to the specified calendar field
without changing larger fields. A negative amount means to roll
down.

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.

setLenient

Specifies 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 (non-lenient) interpretation, such dates will cause an exception to be
thrown. The default is lenient.

Parameters

lenient

boolean:
true if the lenient mode is to be turned
on; false if it is to be turned off.

setMinimalDaysInFirstWeek

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.

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.

Protected methods

complete

Fills in any unset fields in the calendar fields. First, the computeTime() method is called if the time value (millisecond offset
from the Epoch) has not been calculated from
calendar field values. Then, the computeFields() method is
called to calculate all calendar field values.

computeFields

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