Index (Frames) | Index (No Frames) | Package | Package Tree | Tree
java.util

Class Calendar

java.lang.Object
|
+--java.util.Calendar

All Implemented Interfaces:

Serializable, Cloneable


public abstract class Calendar

extends Object

implements 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 rolling fields (that means increase/decrease a specific field by one, propagating overflows), or adding/substracting a fixed amount to a field.

See Also:

Field Summary

static intAM

Useful constant for 12-hour clock.
static intAM_PM

Constant representing the part of the day for 12-hour clock.
static intAPRIL

Constant representing April.
static intAUGUST

Constant representing August.
static intDATE

Constant representing the day time field, synonym for DAY_OF_MONTH.
static intDAY_OF_MONTH

Constant representing the day time field.
static intDAY_OF_WEEK

Constant representing the day of week time field.
static intDAY_OF_WEEK_IN_MONTH

Constant representing the day-of-week-in-month field.
static intDAY_OF_YEAR

Constant representing the day of year time field.
static intDECEMBER

Constant representing December.
static intDST_OFFSET

Constant representing the daylight saving time offset in milliseconds.
static intERA

Constant representing the era time field.
static intFEBRUARY

Constant representing February.
static intFIELD_COUNT

Number of time fields.
static intFRIDAY

Constant representing Friday.
static intHOUR

Constant representing the hour time field for 12-hour clock.
static intHOUR_OF_DAY

Constant representing the hour of day time field for 24-hour clock.
static intJANUARY

Constant representing January.
static intJULY

Constant representing July.
static intJUNE

Constant representing June.
static intMARCH

Constant representing March.
static intMAY

Constant representing May.
static intMILLISECOND

Constant representing the millisecond time field.
static intMINUTE

Constant representing the minute of hour time field.
static intMONDAY

Constant representing Monday.
static intMONTH

Constant representing the month time field.
static intNOVEMBER

Constant representing November.
static intOCTOBER

Constant representing October.
static intPM

Useful constant for 12-hour clock.
static intSATURDAY

Constant representing Saturday.
static intSECOND

Constant representing the second time field.
static intSEPTEMBER

Constant representing September.
static intSUNDAY

Constant representing Sunday.
static intTHURSDAY

Constant representing Thursday.
static intTUESDAY

Constant representing Tuesday.
static intUNDECIMBER

Constant representing Undecimber.
static intWEDNESDAY

Constant representing Wednesday.
static intWEEK_OF_MONTH

Constant representing the week of the month time field.
static intWEEK_OF_YEAR

Constant representing the week of the year field.
static intYEAR

Constant representing the year time field.
static intZONE_OFFSET

Constant representing the time zone offset time field for the time given in the other fields.
booleanareFieldsSet

Tells if the fields have a valid value.
int[]fields

The time fields.
boolean[]isSet

The flags which tell if the fields above have a value.
booleanisTimeSet

Tells if the above field has a valid value.
longtime

The time in milliseconds since the epoch.

Constructor Summary

Calendar()

Constructs a new Calendar with the default time zone and the default locale.
Calendar(java.util.TimeZone zone, java.util.Locale locale)

Constructs a new Calendar with the given time zone and the given locale.

Method Summary

voidadd(int field, int amount)

Adds the specified amount of time to the given time field.
booleanafter(java.lang.Object o)

Compares the given calendar with this.
booleanbefore(java.lang.Object o)

Compares the given calendar with this.
voidclear()

Clears the values of all the time fields.
voidclear(int field)

Clears the values of the specified time field.
java.lang.Objectclone()

Return a clone of this object.
voidcomplete()

Fills any unset fields in the time field list
voidcomputeFields()

Converts the milliseconds since the epoch UTC (time) to time fields (fields).
voidcomputeTime()

Converts the time field values (fields) to milliseconds since the epoch UTC (time).
booleanequals(java.lang.Object o)

Compares the given calendar with this.
intget(int field)

Gets the value of the specified field.
intgetActualMaximum(int field)

Gets the actual maximum value that is allowed for the specified field.
intgetActualMinimum(int field)

Gets the actual minimum value that is allowed for the specified field.
static synchronized java.util.Locale[]getAvailableLocales()

Gets the set of locales for which a Calendar is available.
intgetFirstDayOfWeek()

Gets what the first day of week is.
intgetGreatestMinimum(int field)

Gets the greatest minimum value that is allowed for the specified field.
static synchronized java.util.CalendargetInstance()

Creates a calendar representing the actual time, using the default time zone and locale.
static synchronized java.util.CalendargetInstance(java.util.TimeZone zone)

Creates a calendar representing the actual time, using the given time zone and the default locale.
static synchronized java.util.CalendargetInstance(java.util.Locale locale)

Creates a calendar representing the actual time, using the default time zone and the given locale.
static synchronized java.util.CalendargetInstance(java.util.TimeZone zone, java.util.Locale locale)

Creates a calendar representing the actual time, using the given time zone and locale.
intgetLeastMaximum(int field)

Gets the smallest maximum value that is allowed for the specified field.
intgetMaximum(int field)

Gets the biggest value that is allowed for the specified field.
intgetMinimalDaysInFirstWeek()

Gets how many days are required in the first week of the year.
intgetMinimum(int field)

Gets the smallest value that is allowed for the specified field.
java.util.DategetTime()

Converts the time represented by this object to a Date-Object.
longgetTimeInMillis()

Returns the time represented by this Calendar.
java.util.TimeZonegetTimeZone()

Gets the time zone of this calendar
inthashCode()

Returns a hash code for this calendar.
intinternalGet(int field)

Gets the value of the specified field.
booleanisLenient()

Tells if the date/time interpretation is lenient.
booleanisSet(int field)

Determines if the specified field has a valid value.
voidroll(int field, boolean up)

Rolls the specified time field up or down.
voidroll(int field, int amount)

Rolls up or down the specified time field by the given amount.
voidset(int field, int value)

Sets the time field with the given value.
voidset(int year, int month, int date)

Sets the fields for year, month, and date
voidset(int year, int month, int date, int hour, int minute)

Sets the fields for year, month, date, hour, and minute
voidset(int year, int month, int date, int hour, int minute, int second)

Sets the fields for year, month, date, hour, and minute
voidsetFirstDayOfWeek(int value)

Sets what the first day of week is.
voidsetLenient(boolean lenient)

Specifies if the date/time interpretation should be lenient.
voidsetMinimalDaysInFirstWeek(int value)

Sets how many days are required in the first week of the year.
voidsetTime(java.util.Date date)

Sets this Calendar's time to the given Date.
voidsetTimeInMillis(long time)

Sets this Calendar's time to the given Time.
voidsetTimeZone(java.util.TimeZone zone)

Sets the time zone to the specified value.
java.lang.StringtoString()

Returns a string representation of this object.

Field Details

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.


Constructor Details

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:


Method Details

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:Parameters:

Returns:

Throws:


before

public boolean before(java.lang.Object o)

Compares the given calendar with this.

Since:Parameters:

Returns:

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:


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:


get

public final int get(int field)

Gets the value of the specified field. They are recomputed if they are invalid.

Parameters:

Returns:


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:


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:


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:


getGreatestMinimum

public int getGreatestMinimum(int field)

Gets the greatest minimum value that is allowed for the specified field.

Parameters:

Returns:


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:

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:


getTimeZone

public TimeZone getTimeZone()

Gets the time zone of this calendar

Returns:


hashCode

public int hashCode()

Returns a hash code for this calendar.

Returns:


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:


isLenient

public boolean isLenient()

Tells if the date/time interpretation is lenient.

Returns:


isSet

public final boolean isSet(int field)

Determines if the specified field has a valid value.

Parameters:

Returns:


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.