Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

java.util
Class Calendar  view Calendar download Calendar.java

java.lang.Object
  extended byjava.util.Calendar
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable
Direct Known Subclasses:
GregorianCalendar

public abstract class Calendar
extends java.lang.Object
implements java.io.Serializable, java.lang.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.


Field Summary
static int AM
          Useful constant for 12-hour clock.
static int AM_PM
          Constant representing the part of the day for 12-hour clock.
static int APRIL
          Constant representing April.
protected  boolean areFieldsSet
          Tells if the fields have a valid value.
static int AUGUST
          Constant representing August.
private static java.lang.String bundleName
          The name of the resource bundle.
private static HashMap cache
          Cache of locale->calendar-class mappings.
private static java.lang.String calendarClassName
          This is the default calendar class, that is returned on java.util.Calendar.getInstance().
private static java.lang.Class[] ctorArgTypes
          Preset argument types for calendar-class constructor lookup.
static int DATE
          Constant representing the day time field, synonym for DAY_OF_MONTH.
static int DAY_OF_MONTH
          Constant representing the day time field.
static int DAY_OF_WEEK
          Constant representing the day of week time field.
static int DAY_OF_WEEK_IN_MONTH
          Constant representing the day-of-week-in-month field.
static int DAY_OF_YEAR
          Constant representing the day of year time field.
static int DECEMBER
          Constant representing December.
static int DST_OFFSET
          Constant representing the daylight saving time offset in milliseconds.
static int ERA
          Constant representing the era time field.
private  boolean explicitDSTOffset
          Is set to true if DST_OFFSET is explicitly set.
static int FEBRUARY
          Constant representing February.
static int FIELD_COUNT
          Number of time fields.
private static java.lang.String[] fieldNames
           
protected  int[] fields
          The time fields.
private  int firstDayOfWeek
          Sets what the first day of week is.
static int FRIDAY
          Constant representing Friday.
static int HOUR
          Constant representing the hour time field for 12-hour clock.
static int HOUR_OF_DAY
          Constant representing the hour of day time field for 24-hour clock.
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.
static int JANUARY
          Constant representing January.
static int JULY
          Constant representing July.
static int JUNE
          Constant representing June.
private  boolean lenient
          Specifies if the date/time interpretation should be lenient.
static int MARCH
          Constant representing March.
static int MAY
          Constant representing May.
static int MILLISECOND
          Constant representing the millisecond time field.
private  int minimalDaysInFirstWeek
          Sets how many days are required in the first week of the year.
static int MINUTE
          Constant representing the minute of hour time field.
static int MONDAY
          Constant representing Monday.
static int MONTH
          Constant representing the month time field.
static int NOVEMBER
          Constant representing November.
static int OCTOBER
          Constant representing October.
static int PM
          Useful constant for 12-hour clock.
static int SATURDAY
          Constant representing Saturday.
static int SECOND
          Constant representing the second time field.
static int SEPTEMBER
          Constant representing September.
private  int serialVersionOnStream
          The version of the serialized data on the stream.
(package private) static long serialVersionUID
          XXX - I have not checked the compatibility.
static int SUNDAY
          Constant representing Sunday.
static int THURSDAY
          Constant representing Thursday.
protected  long time
          The time in milliseconds since the epoch.
static int TUESDAY
          Constant representing Tuesday.
static int UNDECIMBER
          Constant representing Undecimber.
static int WEDNESDAY
          Constant representing Wednesday.
static int WEEK_OF_MONTH
          Constant representing the week of the month time field.
static int WEEK_OF_YEAR
          Constant representing the week of the year field.
static int YEAR
          Constant representing the year time field.
private  TimeZone zone
          The time zone of this calendar.
static int ZONE_OFFSET
          Constant representing the time zone offset time field for the time given in the other fields.
 
Constructor Summary
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.
 
Method Summary
abstract  void add(int field, int amount)
          Adds the specified amount of time to the given time field.
 boolean after(java.lang.Object o)
          Compares the given calendar with this.
 boolean before(java.lang.Object o)
          Compares the given calendar with this.
 void clear()
          Clears the values of all the time fields.
 void clear(int field)
          Clears the values of the specified time field.
 java.lang.Object clone()
          Return a clone of this object.
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).
protected abstract  void computeTime()
          Converts the time field values (fields) to milliseconds since the epoch UTC (time).
 boolean equals(java.lang.Object o)
          Compares the given calendar with this.
 int get(int field)
          Gets the value of the specified field.
 int getActualMaximum(int field)
          Gets the actual maximum value that is allowed for the specified field.
 int getActualMinimum(int field)
          Gets the actual minimum value that is allowed for the specified field.
static Locale[] getAvailableLocales()
          Gets the set of locales for which a Calendar is available.
private static ResourceBundle getBundle(Locale locale)
          get resource bundle: The resources should be loaded via this method only.
 int getFirstDayOfWeek()
          Gets what the first day of week is.
abstract  int getGreatestMinimum(int field)
          Gets the greatest minimum value that is allowed for the specified field.
static Calendar getInstance()
          Creates a calendar representing the actual time, using the default time zone and locale.
static Calendar getInstance(Locale locale)
          Creates a calendar representing the actual time, using the default time zone and the given locale.
static Calendar getInstance(TimeZone zone)
          Creates a calendar representing the actual time, using the given time zone and the default locale.
static Calendar getInstance(TimeZone zone, Locale locale)
          Creates a calendar representing the actual time, using the given time zone and locale.
abstract  int getLeastMaximum(int field)
          Gets the smallest maximum value that is allowed for the specified field.
abstract  int getMaximum(int field)
          Gets the biggest value that is allowed for the specified field.
 int getMinimalDaysInFirstWeek()
          Gets how many days are required in the first week of the year.
abstract  int getMinimum(int field)
          Gets the smallest value that is allowed for the specified field.
 Date getTime()
          Converts the time represented by this object to a Date-Object.
 long getTimeInMillis()
          Returns the time represented by this Calendar.
 TimeZone getTimeZone()
          Gets the time zone of this calendar
 int hashCode()
          Returns a hash code for this calendar.
protected  int internalGet(int field)
          Gets the value of the specified field.
 boolean isLenient()
          Tells if the date/time interpretation is lenient.
 boolean isSet(int field)
          Determines if the specified field has a valid value.
private  void readObject(java.io.ObjectInputStream stream)
          Reads the object back from stream (deserialization).
abstract  void roll(int field, boolean up)
          Rolls the specified time field up or down.
 void roll(int field, int amount)
          Rolls up or down the specified time field by the given amount.
 void set(int field, int value)
          Sets the time field with the given value.
 void set(int year, int month, int date)
          Sets the fields for year, month, and date
 void set(int year, int month, int date, int hour, int minute)
          Sets the fields for year, month, date, hour, and minute
 void set(int year, int month, int date, int hour, int minute, int second)
          Sets the fields for year, month, date, hour, and minute
 void setFirstDayOfWeek(int value)
          Sets what the first day of week is.
 void setLenient(boolean lenient)
          Specifies if the date/time interpretation should be lenient.
 void setMinimalDaysInFirstWeek(int value)
          Sets how many days are required in the first week of the year.
 void setTime(Date date)
          Sets this Calendar's time to the given Date.
 void setTimeInMillis(long time)
          Sets this Calendar's time to the given Time.
 void setTimeZone(TimeZone zone)
          Sets the time zone to the specified value.
 java.lang.String toString()
          Returns a string representation of this object.
private  void writeObject(java.io.ObjectOutputStream stream)
          Saves the state of the object to the stream.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

ERA

public static final int ERA
Constant representing the era time field.

See Also:
Constant Field Values

YEAR

public static final int YEAR
Constant representing the year time field.

See Also:
Constant Field Values

MONTH

public static final int MONTH
Constant representing the month time field. This field should contain one of the JANUARY,...,DECEMBER constants below.

See Also:
Constant Field Values

WEEK_OF_YEAR

public static final int WEEK_OF_YEAR
Constant representing the week of the year field.

See Also:
setFirstDayOfWeek(int) 55 , Constant Field Values

WEEK_OF_MONTH

public static final int WEEK_OF_MONTH
Constant representing the week of the month time field.

See Also:
setFirstDayOfWeek(int) 55 , Constant Field Values

DATE

public static final int DATE
Constant representing the day time field, synonym for DAY_OF_MONTH.

See Also:
Constant Field Values

DAY_OF_MONTH

public static final int DAY_OF_MONTH
Constant representing the day time field.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values

HOUR

public static final int HOUR
Constant representing the hour time field for 12-hour clock.

See Also:
Constant Field Values

HOUR_OF_DAY

public static final int HOUR_OF_DAY
Constant representing the hour of day time field for 24-hour clock.

See Also:
Constant Field Values

MINUTE

public static final int MINUTE
Constant representing the minute of hour time field.

See Also:
Constant Field Values

SECOND

public static final int SECOND
Constant representing the second time field.

See Also:
Constant Field Values

MILLISECOND

public static final int MILLISECOND
Constant representing the millisecond time field.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values

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.

See Also:
Constant Field Values

FIELD_COUNT

public static final int FIELD_COUNT
Number of time fields.

See Also:
Constant Field Values

SUNDAY

public static final int SUNDAY
Constant representing Sunday.

See Also:
Constant Field Values

MONDAY

public static final int MONDAY
Constant representing Monday.

See Also:
Constant Field Values

TUESDAY

public static final int TUESDAY
Constant representing Tuesday.

See Also:
Constant Field Values

WEDNESDAY

public static final int WEDNESDAY
Constant representing Wednesday.

See Also:
Constant Field Values

THURSDAY

public static final int THURSDAY
Constant representing Thursday.

See Also:
Constant Field Values

FRIDAY

public static final int FRIDAY
Constant representing Friday.

See Also:
Constant Field Values

SATURDAY

public static final int SATURDAY
Constant representing Saturday.

See Also:
Constant Field Values

JANUARY

public static final int JANUARY
Constant representing January.

See Also:
Constant Field Values

FEBRUARY

public static final int FEBRUARY
Constant representing February.

See Also:
Constant Field Values

MARCH

public static final int MARCH
Constant representing March.

See Also:
Constant Field Values

APRIL

public static final int APRIL
Constant representing April.

See Also:
Constant Field Values

MAY

public static final int MAY
Constant representing May.

See Also:
Constant Field Values

JUNE

public static final int JUNE
Constant representing June.

See Also:
Constant Field Values

JULY

public static final int JULY
Constant representing July.

See Also:
Constant Field Values

AUGUST

public static final int AUGUST
Constant representing August.

See Also:
Constant Field Values

SEPTEMBER

public static final int SEPTEMBER
Constant representing September.

See Also:
Constant Field Values

OCTOBER

public static final int OCTOBER
Constant representing October.

See Also:
Constant Field Values

NOVEMBER

public static final int NOVEMBER
Constant representing November.

See Also:
Constant Field Values

DECEMBER

public static final int DECEMBER
Constant representing December.

See Also:
Constant Field Values

UNDECIMBER

public static final int UNDECIMBER
Constant representing Undecimber. This is an artificial name useful for lunar calendars.

See Also:
Constant Field Values

AM

public static final int AM
Useful constant for 12-hour clock.

See Also:
Constant Field Values

PM

public static final int PM
Useful constant for 12-hour clock.

See Also:
Constant Field Values

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.


time

protected long time
The time in milliseconds since the epoch.


isTimeSet

protected boolean isTimeSet
Tells if the above field has a valid value.


areFieldsSet

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


zone

private TimeZone zone
The time zone of this calendar. Used by sub classes to do UTC / local time conversion. Sub classes can access this field with getTimeZone().


calendarClassName

private static final java.lang.String calendarClassName
This is the default calendar class, that is returned on java.util.Calendar.getInstance(). XXX - this isn't localized anywhere, is it?

See Also:
getInstance() 55 , Constant Field Values

lenient

private 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.


firstDayOfWeek

private int firstDayOfWeek
Sets what the first day of week is. This is used for WEEK_OF_MONTH and WEEK_OF_YEAR fields.


minimalDaysInFirstWeek

private int minimalDaysInFirstWeek
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.


explicitDSTOffset

private boolean explicitDSTOffset
Is set to true if DST_OFFSET is explicitly set. In that case it's value overrides the value computed from the current time and the timezone.


serialVersionOnStream

private int serialVersionOnStream
The version of the serialized data on the stream.
0 or not present
JDK 1.1.5 or later.
1
JDK 1.1.6 or later. This always writes a correct `time' value on the stream, as well as the other fields, to be compatible with earlier versions

Since:
JDK1.1.6

serialVersionUID

static final long serialVersionUID
XXX - I have not checked the compatibility. The documentation of the serialized-form is quite hairy...

See Also:
Constant Field Values

bundleName

private static final java.lang.String bundleName
The name of the resource bundle. Used only by getBundle()

See Also:
Constant Field Values

cache

private static HashMap cache
Cache of locale->calendar-class mappings. This avoids having to do a ResourceBundle lookup for every getInstance call.


ctorArgTypes

private static java.lang.Class[] ctorArgTypes
Preset argument types for calendar-class constructor lookup.


fieldNames

private static final java.lang.String[] fieldNames
Constructor Detail

Calendar

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


Calendar

protected Calendar(TimeZone zone,
                   Locale locale)
Constructs a new Calendar with the given time zone and the given locale.

Method Detail

getBundle

private static ResourceBundle getBundle(Locale locale)
get resource bundle: The resources should be loaded via this method only. Iff an application uses this method, the resourcebundle is required.


getInstance

public static Calendar getInstance()
Creates a calendar representing the actual time, using the default time zone and locale.


getInstance

public static Calendar getInstance(TimeZone zone)
Creates a calendar representing the actual time, using the given time zone and the default locale.


getInstance

public static Calendar getInstance(Locale locale)
Creates a calendar representing the actual time, using the default time zone and the given locale.


getInstance

public static Calendar getInstance(TimeZone zone,
                                   Locale locale)
Creates a calendar representing the actual time, using the given time zone and locale.


getAvailableLocales

public static Locale[] getAvailableLocales()
Gets the set of locales for which a Calendar is available.


computeTime

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.


computeFields

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.


getTime

public final Date getTime()
Converts the time represented by this object to a Date-Object.


setTime

public final void setTime(Date date)
Sets this Calendar's time to the given Date. All time fields are invalidated by this method.


getTimeInMillis

public long getTimeInMillis()
Returns the time represented by this Calendar.


setTimeInMillis

public void setTimeInMillis(long time)
Sets this Calendar's time to the given Time. All time fields are invalidated by this method.


get

public int get(int field)
Gets the value of the specified field. They are recomputed if they are invalid.


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.


set

public void set(int field,
                int value)
Sets the time field with the given value. This does invalidate the time in milliseconds.


set

public final void set(int year,
                      int month,
                      int date)
Sets the fields for year, month, and date


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


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


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.


isSet

public final boolean isSet(int field)
Determines if the specified field has a valid value.


complete

protected void complete()
Fills any unset fields in the time field list


equals

public boolean equals(java.lang.Object o)
Compares the given calendar with this.


hashCode

public int hashCode()
Returns a hash code for this calendar.


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

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

add

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.


roll

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.


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:
JDK1.2

setTimeZone

public void setTimeZone(TimeZone zone)
Sets the time zone to the specified value.


getTimeZone

public TimeZone getTimeZone()
Gets the time zone of this calendar


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.


isLenient

public boolean isLenient()
Tells if the date/time interpretation is lenient.


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.


getFirstDayOfWeek

public int getFirstDayOfWeek()
Gets what the first day of week is. This is used for WEEK_OF_MONTH and WEEK_OF_YEAR fields.


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.


getMinimalDaysInFirstWeek

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


getMinimum

public abstract int getMinimum(int field)
Gets the smallest value that is allowed for the specified field.


getMaximum

public abstract int getMaximum(int field)
Gets the biggest value that is allowed for the specified field.


getGreatestMinimum

public abstract int getGreatestMinimum(int field)
Gets the greatest minimum value that is allowed for the specified field.


getLeastMaximum

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.


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:
jdk1.2

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:
jdk1.2

clone

public java.lang.Object clone()
Return a clone of this object.


toString

public java.lang.String toString()
Returns a string representation of this object. It is mainly for debugging purposes and its content is implementation specific.


writeObject

private void writeObject(java.io.ObjectOutputStream stream)
                  throws java.io.IOException
Saves the state of the object to the stream. Ideally we would only write the time field, but we need to be compatible with earlier versions.
This doesn't write the JDK1.1 field nextStamp to the stream, as I don't know what it is good for, and because the documentation says, that it could be omitted.


readObject

private void readObject(java.io.ObjectInputStream stream)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException
Reads the object back from stream (deserialization).