Class Calendar

public static final int ALL_STYLES

A style specifier for getDisplayNames(int,int,Locale) stating that names should be returned in both long and short variants.

Field Value:

0

Since:

1.6

See Also:

SHORT, LONG

public static final int AM

Useful constant for 12-hour clock.

Field Value:

0

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.

Field Value:

9

public static final int APRIL

Constant representing April.

Field Value:

3

public static final int AUGUST

Constant representing August.

Field Value:

7

public static final int DATE

Constant representing the day time field, synonym for DAY_OF_MONTH.

Field Value:

5

public static final int DAY_OF_MONTH

Constant representing the day time field.

Field Value:

5

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.

Field Value:

7

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.

Field Value:

8

public static final int DAY_OF_YEAR

Constant representing the day of year time field. This is 1 for the first day in month.

Field Value:

6

public static final int DECEMBER

Constant representing December.

Field Value:

11

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.

Field Value:

16

public static final int ERA

Constant representing the era time field.

Field Value:

0

public static final int FEBRUARY

Constant representing February.

Field Value:

1

public static final int FIELD_COUNT

Number of time fields.

Field Value:

17

public static final int FRIDAY

Constant representing Friday.

Field Value:

6

public static final int HOUR

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

Field Value:

10

public static final int HOUR_OF_DAY

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

Field Value:

11

public static final int JANUARY

Constant representing January.

Field Value:

0

public static final int JULY

Constant representing July.

Field Value:

6

public static final int JUNE

Constant representing June.

Field Value:

5

public static final int LONG

A style specifier for getDisplayName(int,int,Locale) and getDisplayNames(int,int,Locale) stating that names should be returned in their long variant if applicable.

Field Value:

2

Since:

1.6

public static final int MARCH

Constant representing March.

Field Value:

2

public static final int MAY

Constant representing May.

Field Value:

4

public static final int MILLISECOND

Constant representing the millisecond time field.

Field Value:

14

public static final int MINUTE

Constant representing the minute of hour time field.

Field Value:

12

public static final int MONDAY

Constant representing Monday.

Field Value:

2

public static final int MONTH

Constant representing the month time field. This field should contain one of the JANUARY,...,DECEMBER constants below.

Field Value:

2

public static final int NOVEMBER

Constant representing November.

Field Value:

10

public static final int OCTOBER

Constant representing October.

Field Value:

9

public static final int PM

Useful constant for 12-hour clock.

Field Value:

1

public static final int SATURDAY

Constant representing Saturday.

Field Value:

7

public static final int SECOND

Constant representing the second time field.

Field Value:

13

public static final int SEPTEMBER

Constant representing September.

Field Value:

8

public static final int SHORT

A style specifier for getDisplayName(int,int,Locale) and getDisplayNames(int,int,Locale) stating that names should be returned in their short variant if applicable.

Field Value:

1

Since:

1.6

public static final int SUNDAY

Constant representing Sunday.

Field Value:

1

public static final int THURSDAY

Constant representing Thursday.

Field Value:

5

public static final int TUESDAY

Constant representing Tuesday.

Field Value:

3

public static final int UNDECIMBER

Constant representing Undecimber. This is an artificial name useful for lunar calendars.

Field Value:

12

public static final int WEDNESDAY

Constant representing Wednesday.

Field Value:

4

public static final int WEEK_OF_MONTH

Constant representing the week of the month time field.

Field Value:

4

See Also:

setFirstDayOfWeek(int)

public static final int WEEK_OF_YEAR

Constant representing the week of the year field.

Field Value:

3

See Also:

setFirstDayOfWeek(int)

public static final int YEAR

Constant representing the year time field.

Field Value:

1

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.

Field Value:

15

protected boolean areFieldsSet

Tells if the fields have a valid value. This superseeds the isSet array.

protected int[] fields

The time fields. The array is indexed by the constants YEAR to DST_OFFSET.

protected boolean[] isSet

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

protected boolean isTimeSet

Tells if the above field has a valid value.

protected long time

The time in milliseconds since the epoch.

protected Calendar()

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

protected Calendar(TimeZone zone,
                   Locale locale)

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

Parameters:

zone - a time zone.

locale - a locale.

public abstract 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:

field - the time field. One of the time field constants.

amount - the amount of time.

Throws:

ArrayIndexOutOfBoundsException - if the field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

public boolean after(Object o)

Compares the given calendar with this.

Parameters:

o - the object to that we should compare.

Returns:

true, if the given object is a calendar, and this calendar represents a bigger time than the calendar o.

Throws:

ClassCastException - if o is not an calendar.

Since:

JDK1.2 you don't need to override this method

public boolean before(Object o)

Compares the given calendar with this.

Parameters:

o - the object to that we should compare.

Returns:

true, if the given object is a calendar, and this calendar represents a smaller time than the calendar o.

Throws:

ClassCastException - if o is not an calendar.

Since:

JDK1.2 you don't need to override this method

public final void clear()

Clears the values of all the time fields.

public final void clear(int field)

Clears the values of the specified time field.

Parameters:

field - the time field. One of the time field constants.

Throws:

ArrayIndexOutOfBoundsException - if field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

public Object clone()

Return a clone of this object.

Overrides:

clone in interface Object

public int compareTo(Calendar cal)

Compares the time of two calendar instances.

Parameters:

cal - the calendar to compare this instance with.

Returns:

0 if the two calendars are set to the same time, less than 0 if the time of this calendar is before that of cal, or more than 0 if the time of this calendar is after that of cal.

Throws:

NullPointerException - if cal is null.

IllegalArgumentException - if either calendar has fields set to invalid values.

Since:

1.5

protected void complete()

Fills any unset fields in the time field list

protected abstract void computeFields()

Converts the milliseconds since the epoch UTC (time) to time fields (fields). Override this method if you write your own Calendar.

protected abstract void computeTime()

Converts the time field values (fields) to milliseconds since the epoch UTC (time). Override this method if you write your own Calendar.

public boolean equals(Object o)

Compares the given calendar with this.

Overrides:

equals in interface Object

Parameters:

o - the object to that we should compare.

Returns:

true, if the given object is a calendar, that represents the same time (but doesn't necessary have the same fields).

public int get(int field)

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

Parameters:

field - the time field. One of the time field constants.

Returns:

the value of the specified field

Throws:

ArrayIndexOutOfBoundsException - if the field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

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.

Parameters:

field - the time field. One of the time field constants.

Returns:

the actual maximum value.

Throws:

ArrayIndexOutOfBoundsException - if the field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

Since:

jdk1.2

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.

Parameters:

field - the time field. One of the time field constants.

Returns:

the actual minimum value.

Throws:

ArrayIndexOutOfBoundsException - if the field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

Since:

jdk1.2

public static Locale[] getAvailableLocales()

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

Returns:

the set of locales.

Throws:

MissingResourceException - if locale data couldn't be found.

public String getDisplayName(int field,
                             int style,
                             Locale locale)

Returns a localised textual representation of the current value of the given field using the specified style. If there is no applicable textual representation (e.g. the field has a numeric value), then null is returned. If one does exist, then the value is obtained from get(int) and converted appropriately. For example, if the MONTH field is requested, then get(MONTH) is called. This is then converted to a textual representation based on its value and the style requested; if the LONG style is requested and the returned value is 11 from a GregorianCalendar implementation, then "December" is returned. By default, a textual representation is available for all fields which have an applicable value obtainable from DateFormatSymbols.

Parameters:

field - the calendar field whose textual representation should be obtained.

style - the style to use; either LONG or SHORT.

locale - the locale to use for translation.

Returns:

the textual representation of the given field in the specified style, or null if none is applicable.

Throws:

IllegalArgumentException - if field or style or invalid, or the calendar is non-lenient and has invalid values.

NullPointerException - if locale is null.

Since:

1.6

public Map getDisplayNames(int field,
                                           int style,
                                           Locale locale)

Returns a map linking all specified textual representations of the given field to their numerical values. The textual representations included are determined by the specified style and locale. For example, if the style LONG is specified and the German locale, then the map will contain "Montag" to MONDAY, "Dienstag" to TUESDAY, "Mittwoch" to WEDNESDAY and so on. The default implementation uses the values returned by DateFormatSymbols so, for example, the style ALL_STYLES and the field MONTH will return a map filled with the values returned from DateFormatSymbols.getMonths() and DateFormatSymbols.getShortMonths(). If there are no textual representations for a given field (usually because it is purely numeric, such as the year in the GregorianCalendar), null is returned.

Parameters:

field - the calendar field whose textual representation should be obtained.

style - the style to use; either LONG, SHORT or ALL_STYLES.

locale - the locale to use for translation.

Returns:

a map of the textual representations of the given field in the specified style to their numeric values, or null if none is applicable.

Throws:

IllegalArgumentException - if field or style or invalid, or the calendar is non-lenient and has invalid values.

NullPointerException - if locale is null.

Since:

1.6

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.

public abstract int getGreatestMinimum(int field)

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

Parameters:

field - the time field. One of the time field constants.

Returns:

the greatest minimum value.

public static Calendar getInstance()

Creates a calendar representing the actual time, using the default time zone and locale.

Returns:

The new calendar.

public static Calendar getInstance(Locale locale)

Creates a calendar representing the actual time, using the default time zone and the given locale.

Parameters:

locale - a locale (null not permitted).

Returns:

The new calendar.

Throws:

NullPointerException - if locale is null.

public static Calendar getInstance(TimeZone zone)

Creates a calendar representing the actual time, using the given time zone and the default locale.

Parameters:

zone - a time zone (null not permitted).

Returns:

The new calendar.

Throws:

NullPointerException - if zone is null.

public static Calendar getInstance(TimeZone zone,
                                   Locale locale)

Creates a calendar representing the actual time, using the given time zone and locale.

Parameters:

zone - a time zone (null not permitted).

locale - a locale (null not permitted).

Returns:

The new calendar.

Throws:

NullPointerException - if zone or locale is null.

public abstract 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:

field - the time field. One of the time field constants.

Returns:

the least maximum value.

public abstract int getMaximum(int field)

Gets the biggest value that is allowed for the specified field.

Parameters:

field - the time field. One of the time field constants.

Returns:

the biggest value.

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:

setMinimalDaysInFirstWeek(int)

public abstract int getMinimum(int field)

Gets the smallest value that is allowed for the specified field.

Parameters:

field - the time field. One of the time field constants.

Returns:

the smallest value.

public final Date getTime()

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

Returns:

the Date.

public long getTimeInMillis()

Returns the time represented by this Calendar.

Returns:

the time in milliseconds since the epoch.

public TimeZone getTimeZone()

Gets the time zone of this calendar

Returns:

the current time zone.

public int hashCode()

Returns a hash code for this calendar.

Overrides:

hashCode in interface Object

Returns:

a hash code, which fullfits the general contract of hashCode()

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:

field - the time field. One of the time field constants.

Returns:

the value of the specified field, undefined if areFieldsSet or isSet[field] is false.

Throws:

ArrayIndexOutOfBoundsException - if the field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

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.

public final boolean isSet(int field)

Determines if the specified field has a valid value.

Returns:

true if the specified field has a value.

Throws:

ArrayIndexOutOfBoundsException - if the field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

public abstract 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:

field - the time field. One of the time field constants.

up - the direction, true for up, false for down.

Throws:

ArrayIndexOutOfBoundsException - if the field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

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.

Parameters:

field - the time field. One of the time field constants.

amount - the amount to roll by, positive for rolling up, negative for rolling down.

Throws:

ArrayIndexOutOfBoundsException - if the field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

Since:

JDK1.2

public void set(int field,
                int value)

Sets the time field with the given value. This does invalidate the time in milliseconds.

Parameters:

field - the time field. One of the time field constants

value - the value to be set.

Throws:

ArrayIndexOutOfBoundsException - if field is outside the valid range. The value of field must be >= 0 and <= FIELD_COUNT.

public final void set(int year,
                      int month,
                      int date)

Sets the fields for year, month, and date

Parameters:

year - the year.

month - the month, one of the constants JANUARY..UNDICEMBER.

date - the day of the month

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:

year - the year.

month - the month, one of the constants JANUARY..UNDICEMBER.

date - the day of the month

hour - the hour of day.

minute - the minute.

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:

year - the year.

month - the month, one of the constants JANUARY..UNDICEMBER.

date - the day of the month

hour - the hour of day.

minute - the minute.

second - the second.

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:

value - the first day of week. One of SUNDAY to SATURDAY.

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:

lenient - true, if the date should be interpreted linient, false if it should be interpreted strict.

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:

value - the minimal days required in the first week.

public final void setTime(Date date)

Sets this Calendar's time to the given Date. All time fields are invalidated by this method.

Parameters:

date - the date (null not permitted).

Throws:

NullPointerException - if date is null.

public void setTimeInMillis(long time)

Sets this Calendar's time to the given Time. All time fields are invalidated by this method.

Parameters:

time - the time in milliseconds since the epoch

public void setTimeZone(TimeZone zone)

Sets the time zone to the specified value.

Parameters:

zone - the new time zone

public String toString()

Returns a string representation of this object. It is mainly for debugging purposes and its content is implementation specific.

Overrides:

toString in interface Object