java.util
Class Calendar
java.lang.Object
|
+--java.util.Calendar
All Implemented Interfaces:
Serializable, Cloneable
This class is an abstract base class for Calendars, which can be
used to convert between
Date
objects and a set of
integer fields which represent
YEAR
,
MONTH
,
DAY
, etc. The
Date
object represents a time in milliseconds since the Epoch.
This class is locale sensitive. To get the Object matching the
current locale you can use
getInstance
. You can even provide
a locale or a timezone.
getInstance
returns currently
a
GregorianCalendar
for the current date.
If you want to convert a date from the Year, Month, Day, DayOfWeek,
etc. Representation to a
Date
-Object, you can create
a new Calendar with
getInstance()
,
clear()
all fields,
set(int,int)
the
fields you need and convert it with
getTime()
.
If you want to convert a
Date
-object to the Calendar
representation, create a new Calendar, assign the
Date
-Object with
setTime()
, and read the
fields with
get(int)
.
When computing the date from time fields, it may happen, that there
are either two few fields set, or some fields are inconsistent. This
cases will handled in a calendar specific way. Missing fields are
replaced by the fields of the epoch: 1970 January 1 00:00.
To understand, how the day of year is computed out of the fields
look at the following table. It is traversed from top to bottom,
and for the first line all fields are set, that line is used to
compute the day.
month + day_of_month
month + week_of_month + day_of_week
month + day_of_week_of_month + day_of_week
day_of_year
day_of_week + week_of_year
The hour_of_day-field takes precedence over the ampm and
hour_of_ampm fields.
Note: This can differ for non-Gregorian calendar.
To convert a calendar to a human readable form and vice versa, use
the
java.text.DateFormat
class.
Other useful things you can do with an calendar, is
roll
ing fields (that means increase/decrease a
specific field by one, propagating overflows), or
add
ing/substracting a fixed amount to a field.
See Also:
void | add(int field, int amount)
|
boolean | after(java.lang.Object o)
|
boolean | before(java.lang.Object o)
|
void | clear()
|
void | clear(int field)
|
java.lang.Object | clone()
|
void | complete()
|
void | computeFields()
|
void | computeTime()
|
boolean | equals(java.lang.Object o)
|
int | get(int field)
|
int | getActualMaximum(int field)
|
int | getActualMinimum(int field)
|
static synchronized java.util.Locale[] | getAvailableLocales()
|
int | getFirstDayOfWeek()
|
int | getGreatestMinimum(int field)
|
static synchronized java.util.Calendar | getInstance()
|
static synchronized java.util.Calendar | getInstance(java.util.TimeZone zone)
|
static synchronized java.util.Calendar | getInstance(java.util.Locale locale)
|
static synchronized java.util.Calendar | getInstance(java.util.TimeZone zone, java.util.Locale locale)
|
int | getLeastMaximum(int field)
|
int | getMaximum(int field)
|
int | getMinimalDaysInFirstWeek()
|
int | getMinimum(int field)
|
java.util.Date | getTime()
|
long | getTimeInMillis()
|
java.util.TimeZone | getTimeZone()
|
int | hashCode()
|
int | internalGet(int field)
|
boolean | isLenient()
|
boolean | isSet(int field)
|
void | roll(int field, boolean up)
|
void | roll(int field, int amount)
|
void | set(int field, int value)
|
void | set(int year, int month, int date)
|
void | set(int year, int month, int date, int hour, int minute)
|
void | set(int year, int month, int date, int hour, int minute, int second)
|
void | setFirstDayOfWeek(int value)
|
void | setLenient(boolean lenient)
|
void | setMinimalDaysInFirstWeek(int value)
|
void | setTime(java.util.Date date)
|
void | setTimeInMillis(long time)
|
void | setTimeZone(java.util.TimeZone zone)
|
java.lang.String | toString()
|
AM
public static final int AM
Useful constant for 12-hour clock.
AM_PM
public static final int AM_PM
Constant representing the part of the day for 12-hour clock. This
should be one of AM or PM.
APRIL
public static final int APRIL
Constant representing April.
AUGUST
public static final int AUGUST
Constant representing August.
DATE
public static final int DATE
Constant representing the day time field, synonym for DAY_OF_MONTH.
DAY_OF_MONTH
public static final int DAY_OF_MONTH
Constant representing the day time field.
DAY_OF_WEEK
public static final int DAY_OF_WEEK
Constant representing the day of week time field. This field
should contain one of the SUNDAY,...,SATURDAY constants below.
DAY_OF_WEEK_IN_MONTH
public static final int DAY_OF_WEEK_IN_MONTH
Constant representing the day-of-week-in-month field. For
instance this field contains 2 for the second thursday in a
month. If you give a negative number here, the day will count
from the end of the month.
DAY_OF_YEAR
public static final int DAY_OF_YEAR
Constant representing the day of year time field. This is
1 for the first day in month.
DECEMBER
public static final int DECEMBER
Constant representing December.
DST_OFFSET
public static final int DST_OFFSET
Constant representing the daylight saving time offset in
milliseconds. The default is the value given by the time zone.
ERA
public static final int ERA
Constant representing the era time field.
FEBRUARY
public static final int FEBRUARY
Constant representing February.
FIELD_COUNT
public static final int FIELD_COUNT
Number of time fields.
FRIDAY
public static final int FRIDAY
Constant representing Friday.
HOUR
public static final int HOUR
Constant representing the hour time field for 12-hour clock.
HOUR_OF_DAY
public static final int HOUR_OF_DAY
Constant representing the hour of day time field for 24-hour clock.
JANUARY
public static final int JANUARY
Constant representing January.
JULY
public static final int JULY
Constant representing July.
JUNE
public static final int JUNE
Constant representing June.
MARCH
public static final int MARCH
Constant representing March.
MAY
public static final int MAY
Constant representing May.
MILLISECOND
public static final int MILLISECOND
Constant representing the millisecond time field.
MINUTE
public static final int MINUTE
Constant representing the minute of hour time field.
MONDAY
public static final int MONDAY
Constant representing Monday.
MONTH
public static final int MONTH
Constant representing the month time field. This field
should contain one of the JANUARY,...,DECEMBER constants below.
NOVEMBER
public static final int NOVEMBER
Constant representing November.
OCTOBER
public static final int OCTOBER
Constant representing October.
PM
public static final int PM
Useful constant for 12-hour clock.
SATURDAY
public static final int SATURDAY
Constant representing Saturday.
SECOND
public static final int SECOND
Constant representing the second time field.
SEPTEMBER
public static final int SEPTEMBER
Constant representing September.
SUNDAY
public static final int SUNDAY
Constant representing Sunday.
THURSDAY
public static final int THURSDAY
Constant representing Thursday.
TUESDAY
public static final int TUESDAY
Constant representing Tuesday.
UNDECIMBER
public static final int UNDECIMBER
Constant representing Undecimber. This is an artificial name useful
for lunar calendars.
WEDNESDAY
public static final int WEDNESDAY
Constant representing Wednesday.
WEEK_OF_MONTH
public static final int WEEK_OF_MONTH
Constant representing the week of the month time field.
See Also:
WEEK_OF_YEAR
public static final int WEEK_OF_YEAR
Constant representing the week of the year field.
See Also:
YEAR
public static final int YEAR
Constant representing the year time field.
ZONE_OFFSET
public static final int ZONE_OFFSET
Constant representing the time zone offset time field for the
time given in the other fields. It is measured in
milliseconds. The default is the offset of the time zone.
areFieldsSet
protected boolean areFieldsSet
Tells if the fields have a valid value. This superseeds the isSet
array.
fields
protected int[] fields
The time fields. The array is indexed by the constants YEAR to
DST_OFFSET.
isSet
protected boolean[] isSet
The flags which tell if the fields above have a value.
isTimeSet
protected boolean isTimeSet
Tells if the above field has a valid value.
time
protected long time
The time in milliseconds since the epoch.
Calendar
protected Calendar()
Constructs a new Calendar with the default time zone and the default
locale.
Calendar
protected Calendar(java.util.TimeZone zone, java.util.Locale locale)
Constructs a new Calendar with the given time zone and the given
locale.
Parameters:
add
public void add(int field, int amount)
Adds the specified amount of time to the given time field. The
amount may be negative to subtract the time. If the field overflows
it does what you expect: Jan, 25 + 10 Days is Feb, 4.
Parameters:
after
public boolean after(java.lang.Object o)
Compares the given calendar with this.
Since:- JDK1.2 you don't need to override this method
Parameters:
Returns:
- true, if the given object is a calendar, and this calendar
represents a bigger time than the calendar o.
Throws:
before
public boolean before(java.lang.Object o)
Compares the given calendar with this.
Since:- JDK1.2 you don't need to override this method
Parameters:
Returns:
- true, if the given object is a calendar, and this calendar
represents a smaller time than the calendar o.
Throws:
clear
public final void clear()
Clears the values of all the time fields.
clear
public final void clear(int field)
Clears the values of the specified time field.
Parameters:
clone
public Object clone()
Return a clone of this object.
complete
protected void complete()
Fills any unset fields in the time field list
Returns:
- true if the specified field has a value.
computeFields
protected void computeFields()
Converts the milliseconds since the epoch UTC
(time
) to time fields
(fields
). Override this method if you write your
own Calendar.
computeTime
protected void computeTime()
Converts the time field values (fields
) to
milliseconds since the epoch UTC (time
). Override
this method if you write your own Calendar.
equals
public boolean equals(java.lang.Object o)
Compares the given calendar with this.
Parameters:
Returns:
- true, if the given object is a calendar, that represents
the same time (but doesn't necessary have the same fields).
get
public final int get(int field)
Gets the value of the specified field. They are recomputed
if they are invalid.
Parameters:
Returns:
- the value of the specified field
getActualMaximum
public int getActualMaximum(int field)
Gets the actual maximum value that is allowed for the specified field.
This value is dependent on the values of the other fields.
Since:Parameters:
Returns:
- the actual maximum value.
getActualMinimum
public int getActualMinimum(int field)
Gets the actual minimum value that is allowed for the specified field.
This value is dependent on the values of the other fields.
Since:Parameters:
Returns:
- the actual minimum value.
getAvailableLocales
public static synchronized Locale[] getAvailableLocales()
Gets the set of locales for which a Calendar is available.
Returns:
Throws:
getFirstDayOfWeek
public int getFirstDayOfWeek()
Gets what the first day of week is. This is used for
WEEK_OF_MONTH and WEEK_OF_YEAR fields.
Returns:
- the first day of week. One of SUNDAY to SATURDAY.
getGreatestMinimum
public int getGreatestMinimum(int field)
Gets the greatest minimum value that is allowed for the specified field.
Parameters:
Returns:
- the greatest minimum value.
getInstance
public static synchronized Calendar getInstance()
Creates a calendar representing the actual time, using the default
time zone and locale.
getInstance
public static synchronized Calendar getInstance(java.util.Locale locale)
Creates a calendar representing the actual time, using the default
time zone and the given locale.
Parameters:
getInstance
public static synchronized Calendar getInstance(java.util.TimeZone zone)
Creates a calendar representing the actual time, using the given
time zone and the default locale.
Parameters:
getInstance
public static synchronized Calendar getInstance(java.util.TimeZone zone, java.util.Locale locale)
Creates a calendar representing the actual time, using the given
time zone and locale.
Parameters:
getLeastMaximum
public int getLeastMaximum(int field)
Gets the smallest maximum value that is allowed for the
specified field. For example this is 28 for DAY_OF_MONTH.
Parameters:
Returns:
getMaximum
public int getMaximum(int field)
Gets the biggest value that is allowed for the specified field.
Parameters:
Returns:
getMinimalDaysInFirstWeek
public int getMinimalDaysInFirstWeek()
Gets how many days are required in the first week of the year.
Returns:
- the minimal days required in the first week.
See Also:
getMinimum
public int getMinimum(int field)
Gets the smallest value that is allowed for the specified field.
Parameters:
Returns:
getTime
public final Date getTime()
Converts the time represented by this object to a
Date
-Object.
Returns:
getTimeInMillis
public long getTimeInMillis()
Returns the time represented by this Calendar.
Returns:
- the time in milliseconds since the epoch.
getTimeZone
public TimeZone getTimeZone()
Gets the time zone of this calendar
Returns:
hashCode
public int hashCode()
Returns a hash code for this calendar.
Returns:
- a hash code, which fullfits the general contract of
hashCode()
internalGet
protected final int internalGet(int field)
Gets the value of the specified field. This method doesn't
recompute the fields, if they are invalid.
Parameters:
Returns:
- the value of the specified field, undefined if
areFieldsSet
or isSet[field]
is false.
isLenient
public boolean isLenient()
Tells if the date/time interpretation is lenient.
Returns:
- true, if the date should be interpreted linient,
false if it should be interpreted strict.
isSet
public final boolean isSet(int field)
Determines if the specified field has a valid value.
Parameters:
Returns:
- true if the specified field has a value.
roll
public void roll(int field, boolean up)
Rolls the specified time field up or down. This means add one
to the specified field, but don't change the other fields. If
the maximum for this field is reached, start over with the
minimum value.
Note: There may be situation, where the other
fields must be changed, e.g rolling the month on May, 31.
The date June, 31 is automatically converted to July, 1.
Parameters:
roll
public void roll(int field, int amount)
Rolls up or down the specified time field by the given amount.
A negative amount rolls down. The default implementation is
call roll(int, boolean)
for the specified amount.
Subclasses should override this method to do more intuitiv things.
Since:Parameters:
set
public final void set(int field, int value)
Sets the time field with the given value. This does invalidate
the time in milliseconds.
Parameters:
set
public final void set(int year, int month, int date)
Sets the fields for year, month, and date
Parameters:
set
public final void set(int year, int month, int date, int hour, int minute)
Sets the fields for year, month, date, hour, and minute
Parameters:
set
public final void set(int year, int month, int date, int hour, int minute, int second)
Sets the fields for year, month, date, hour, and minute
Parameters:
setFirstDayOfWeek
public void setFirstDayOfWeek(int value)
Sets what the first day of week is. This is used for
WEEK_OF_MONTH and WEEK_OF_YEAR fields.
Parameters:
setLenient
public void setLenient(boolean lenient)
Specifies if the date/time interpretation should be lenient.
If the flag is set, a date such as "February 30, 1996" will be
treated as the 29th day after the February 1. If this flag
is false, such dates will cause an exception.
Parameters:
setMinimalDaysInFirstWeek
public void setMinimalDaysInFirstWeek(int value)
Sets how many days are required in the first week of the year.
If the first day of the year should be the first week you should
set this value to 1. If the first week must be a full week, set
it to 7.
Parameters:
setTime
public final void setTime(java.util.Date date)
Sets this Calendar's time to the given Date. All time fields
are invalidated by this method.
Parameters:
setTimeInMillis
public void setTimeInMillis(long time)
Sets this Calendar's time to the given Time. All time fields
are invalidated by this method.
Parameters:
setTimeZone
public void setTimeZone(java.util.TimeZone zone)
Sets the time zone to the specified value.
Parameters:
toString
public String toString()
Returns a string representation of this object. It is mainly
for debugging purposes and its content is implementation
specific.
Date
objects and a set of integer fields which representYEAR
,MONTH
,DAY
, etc. TheDate
object represents a time in milliseconds since the Epoch.This class is locale sensitive. To get the Object matching the current locale you can use
getInstance
. You can even provide a locale or a timezone.getInstance
returns currently aGregorianCalendar
for the current date.If you want to convert a date from the Year, Month, Day, DayOfWeek, etc. Representation to a
Date
-Object, you can create a new Calendar withgetInstance()
,clear()
all fields,set(int,int)
the fields you need and convert it withgetTime()
.If you want to convert a
Date
-object to the Calendar representation, create a new Calendar, assign theDate
-Object withsetTime()
, and read the fields withget(int)
.When computing the date from time fields, it may happen, that there are either two few fields set, or some fields are inconsistent. This cases will handled in a calendar specific way. Missing fields are replaced by the fields of the epoch: 1970 January 1 00:00.
To understand, how the day of year is computed out of the fields look at the following table. It is traversed from top to bottom, and for the first line all fields are set, that line is used to compute the day.
The hour_of_day-field takes precedence over the ampm and hour_of_ampm fields.
Note: This can differ for non-Gregorian calendar.
To convert a calendar to a human readable form and vice versa, use the
java.text.DateFormat
class.Other useful things you can do with an calendar, is
roll
ing fields (that means increase/decrease a specific field by one, propagating overflows), oradd
ing/substracting a fixed amount to a field.