 |
Chapter 17 The java.util Package |
 |
|
Chapter 17 The java.util Package |
|
java.util.Calendar
java.lang.Object
java.util.GregorianCalendar
java.lang.Cloneable, java.io.Serializable
New as of JDK 1.1
The Calendar class is an abstractclass that is used to convert between Date objects, which represent points in time, and calendar fields, like months or days of the week. The JDK 1.0 Date class included calendar and text-formatting methods. As of JDK 1.1, both of these functions have been split off from Date in order to support internationalization. As of JDK 1.1, Date represents only a point in time, measured in milliseconds. A subclass of Calendar examines the Date in the context of a particular calendar system; a Calendar instance is a locale-sensitive object. Also as of JDK 1.1, the java.text.DateFormat class generates and parses strings representing points in time.
Calendar defines a number of symbolic constants. They represent either fields or values. For example, MONTH is a field constant. It can be passed to get() and set() to retrieve and adjust the month. AUGUST, on the other hand, represents a particular month value. Calling get(Calendar.MONTH) could return Calendar.AUGUST.
Internally, Calendar keeps track of a point in time in two ways. First, a "raw" value is maintained, which is simply a count of milliseconds since midnight, January 1, 1970 GMT, or, in other words, a Date object. Second, the calendar keeps track of a number of fields, which are the values that are specific to the Calendar type. These are values such as day of the week, day of the month, and month. The raw millisecond value can be calculated from the field values, or vice versa.
When a Date object is computed from the time fields, there may be insufficient information to compute the raw millisecond value. For example, the year and the month could be set, but not the day of the month. In this case, Calendar uses default information to fill in the missing fields. For GregorianCalendar, the default field values are taken from the date of the epoch, or midnight, January 1, 1970 GMT.
Another problem that can arise when computing a Date object from the time fields is that of inconsistent information in the fields. For example, the time fields could specify "Sunday, March 8, 1997" when in fact March 8, 1997 is a Saturday. If the time fields contain inconsistent information, Calendar gives preference to the combinations of fields in the following order:
There is also the possibility of ambiguity for certain points in time, so the following rules apply. The time 24:00:00 belongs to the next day and midnight is an A.M. time, while noon is a P.M. time.
public abstract class java.util.Calendar extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable {
// Constants
public final static int AM;
public final static int AM_PM;
public final static int APRIL;
public final static int AUGUST;
public final static int DATE;
public final static int DAY_OF_MONTH;
public final static int DAY_OF_WEEK;
public final static int DAY_OF_WEEK_IN_MONTH;
public final static int DAY_OF_YEAR;
public final static int DECEMBER;
public final static int DST_OFFSET;
public final static int ERA;
public final static int FEBRUARY;
public final static int FIELD_COUNT;
public final static int FRIDAY;
public final static int HOUR;
public final static int HOUR_OF_DAY;
public final static int JANUARY;
public final static int JULY;
public final static int JUNE;
public final static int MARCH;
public final static int MAY;
public final static int MILLISECOND;
public final static int MINUTE;
public final static int MONDAY;
public final static int MONTH;
public final static int NOVEMBER;
public final static int OCTOBER;
public final static int PM;
public final static int SATURDAY;
public final static int SECOND;
public final static int SEPTEMBER;
public final static int SUNDAY;
public final static int THURSDAY;
public final static int TUESDAY;
public final static int UNDECIMBER;
public final static int WEDNESDAY;
public final static int WEEK_OF_MONTH;
public final static int WEEK_OF_YEAR;
public final static int YEAR;
public final static int ZONE_OFFSET;
// Variables
protected boolean areFieldsSet;
protected int[] fields;
protected boolean[] isSet;
protected boolean isTimeSet;
protected long time;
// Constructors
protected Calendar();
protected Calendar(TimeZone zone, Locale aLocale);
// Class Methods
public static synchronized Locale[] getAvailableLocales();
public static synchronized Calendar getInstance();
public static synchronized Calendar getInstance(TimeZone zone);
public static synchronized Calendar getInstance(Locale aLocale);
public static synchronized Calendar getInstance(TimeZone zone,
Locale aLocale);
// Instance Methods
public abstract void add(int field, int amount);
public abstract boolean after(Object when);
public abstract boolean before(Object when);
public final void clear();
public final void clear(int field);
public Object clone();
public abstract boolean equals(Object when);
public final int get(int field);
public int getFirstDayOfWeek();
public abstract int getGreatestMinimum(int field);
public abstract int getLeastMaximum(int field);
public abstract int getMaximum(int field);
public int getMinimalDaysInFirstWeek();
public abstract int getMinimum(int field);
public final Date getTime();
public TimeZone getTimeZone();
public boolean isLenient();
public final boolean isSet(int field);
public abstract void roll(int field, boolean up);
public final void set(int field, int value);
public final void set(int year, int month, int date);
public final void set(int year, int month, int date,
int hour, int minute);
public final void set(int year, int month, int date, int hour,
int minute, int second);
public void setFirstDayOfWeek(int value);
public void setLenient(boolean lenient);
public void setMinimalDaysInFirstWeek(int value);
public final void setTime(Date date);
public void setTimeZone(TimeZone value);
// Protected Instance Methods
protected void complete();
protected abstract void computeFields();
protected abstract void computeTime();
protected long getTimeInMillis();
protected final int internalGet(int field);
protected void setTimeInMillis(long millis);
}
A constant value that represents morning times.
A field constant that represents the A.M./P.M. flag of this object.
A constant value that represents the month of April.
A constant value that represents the month of August.
A field constant that represents the day of the month of this object.
A field constant that represents the day of the month of this object. This field is synonymous with DATE.
A field constant that represents the day of the week of this object.
A field constant that represents the day of the week in the current month. For example, February 10, 1997, has a DAY_OF_WEEK_IN_MONTH value of 2 because it is the second Monday in February for that year.
A field constant that represents the day of the year of this object. January 1 is the first day of the year.
A constant value that represents the month of December.
A field constant that represents the offset due to daylight savings time, in milliseconds, of this object.
A field constant that represents the era of this object. A Gregorian calendar has two eras, BC and AD.
A constant value that represents the month of February.
A constant that represents the number of attribute fields for Calendar objects.
A constant value that represents the day Friday.
A field constant that represents the hour of this object.
A field constant that represents the hour of the day of this object. A time of 1:00 P.M. has an HOUR value of 1, but an HOUR_OF_DAY value of 13.
A constant value that represents the month of January.
A constant value that represents the month of July.
A constant value that represents the month of June.
A constant value that represents the month of March.
A constant value that represents the month of May.
A field constant that represents the milliseconds of this object.
A field constant that represents the minutes of this object.
A constant value that represents the day Monday.
A field constant that represents the month of this object.
A constant value that represents the month of November.
A constant value that represents the month of October.
A constant value that represents afternoon and evening times.
A constant value that represents the day Saturday.
A field constant that represents the seconds of this object.
A constant value that represents the month of September.
A constant value that represents the day Sunday.
A constant value that represents the day Thursday.
A constant value that represents the day Tuesday.
A constant value that represents the thirteenth month used in lunar calendars.
A constant value that represents the day Wednesday.
A field constant that represents the week of the month of this object.
A field constant that represents the week of the year of this object.
A field constant that represents the year of this object.
A field constant that represents the raw time zone offset, in milliseconds, of this object. The value should be added to GMT to get local time.
A boolean value that indicates if the time fields of this Calendar have been set. These fields can be computed from the raw millisecond time value.
An array that stores the time field values for this Calendar.
An array that contains a flag for each entry in the fields array. The value of each flag indicates if the corresponding entry in fields has been set for this Calendar.
A boolean value that indicates if the raw millisecond time value of this Calendar has been set. The value can be computed from the time fields.
The raw time value for this Calendar. The value is the number of milliseconds since midnight, January 1, 1970 GMT.
This constructor creates a Calendar that uses the system's default time zone and locale. The default time zone is that returned by TimeZone.getDefault(). The default locale is that returned by Locale.getDefault().
The TimeZone to use.
The Locale to use.
This constructor creates a Calendar that uses the supplied time zone and locale.
An array of Locale objects for which Calendar objects are installed.
This method returns an array of locales that have corresponding Calendar objects.
A Calendar for the default time zone and locale.
This method returns a newly constructed Calendar for the default time zone and locale. Future implementations of this method may infer the subclass of Calendar to instantiate based on the default locale. However, the current implementation always returns a GregorianCalendar. The default time zone is that returned by TimeZone.getDefault(). The default locale is that returned by Locale.getDefault().
The TimeZone to use.
A Calendar for the given time zone and the default locale.
This method returns a newly constructed Calendar for the given time zone and the default locale. Future implementations of this method may infer the subclass of Calendar to instantiate based on the default locale. However, the current implementation always returns a GregorianCalendar. The default locale is that returned by Locale.getDefault().
The Locale to use.
A Calendar for the given locale and the default time zone.
This method returns a newly constructed Calendar for the given locale and the default time zone. Future implementations of this method may infer the subclass of Calendar to instantiate based on the given locale. However, the current implementation always returns a GregorianCalendar. The default time zone is that returned by TimeZone.getDefault().
The TimeZone to use.
The Locale to use.
A Calendar for the given time zone and locale.
This method returns a newly constructed Calendar for the given time zone and locale. Future implementations of this method may infer the subclass of Calendar to instantiate based on the given locale. However, the current implementation always returns a GregorianCalendar.
The time field to be modified.
The amount to add to the specified field value. This value can be negative.
This method adds the given amount to the specified time field. For example, you can compute a date 90 days beyond the current date of this Calendar by calling add(Calendar.DATE, 90).
The object to compare to this Calendar.
true if this object is after when; false otherwise.
This method returns true if when is a Calendar object whose value falls before the value of this Calendar.
The object to compare to this Calendar.
true if this object is before when; false otherwise.
This method returns true if when is a Calendar object whose value falls after the value of this Calendar.
This method clears the values of all of the time fields of this Calendar.
The time field to be cleared.
This method clears the specified time field by setting its value to 0.
A copy of this Calendar.
Object.clone()
This method creates a copy of this Calendar and returns it. In other words, the returned Calendar has the same time field values and raw time value as this Calendar.
The object to be compared with this object.
true if the objects are equal; false if they are not.
Object.equals()
This method returns true if when is an instance of Calendar and it contains the same value as the object this method is associated with.
The time field to be retrieved.
The value of the given time field.
This method returns the value of the specified time field. If the fields of this Calendar have not been set, they are set from the raw time value before the requested field is returned.
The first day of the week for this Calendar.
This method returns the day that is considered the beginning of the week for this Calendar. This value is determined by the Locale of this Calendar. For example, the first day of the week in the United States is Sunday, while in France it is Monday.
A time field constant.
The highest minimum value for the given time field.
This method returns the highest minimum value for the given time field, if the field has a range of minimum values. If the field does not have a range of minimum values, this method is equivalent to getMinimum().
A time field constant.
The lowest maximum value for the given time field.
This method returns the lowest maximum value for the given time field, if the field has a range of maximum values. If the field does not have a range of maximum values, this method is equivalent to getMaximum(). For example, for a GregorianCalendar, the lowest maximum value of DATE_OF_MONTH is 28.
A time field constant.
The maximum value for the given time field.
This method returns the maximum value for the given time field. For example, for a GregorianCalendar, the maximum value of DATE_OF_MONTH is 31.
The number of days that must be in the first week of the year.
This method returns the number of days that must be in the first week of the year. For example, a value of 7 indicates that the first week of the year must be a full week, while a value of 1 indicates that the first week of the year can contain a single day. This value is determined by the Locale of this Calendar.
A time field constant.
The minimum value for the given time field.
This method returns the minimum value for the given time field. For example, for a GregorianCalendar, the minimum value of DATE_OF_MONTH is 1.
A Date object that represents the point in time represented by this Calendar.
This method returns a newly created Date object that is constructed from the value returned by getTimeInMillis().
The TimeZone of this Calendar.
This method returns the TimeZone object for this Calendar.
A boolean value that indicates the leniency of this Calendar.
This method returns the current leniency of this Calendar. A value of false indicates that the Calendar throws exceptions when questionable data is passed to it, while a value of true indicates that the Calendar makes its best guess to interpret questionable data. For example, if the Calendar is being lenient, a date such as March 135, 1997 is interpreted as the 134th day after March 1, 1997.
A time field constant.
true if the time field has been set; false otherwise.
This method returns a boolean value that indicates whether or not the specified time field has been set.
The time field to be adjusted.
A boolean value that indicates if the given field should be incremented.
This method adds or subtracts one time unit from the given time field. For example, to increase the current date by one day, you can call roll(Calendar.DATE, true).
The method maintains the field being rolled within its valid range. For example, in a calendar system that uses hours and minutes to measure time, rolling the minutes up from 59 sets that field to 0. By the same token, rolling that field down from 0 sets it to 59.
The roll() method does not adjust the value of any other field than the one specified by its field argument. In particular, for calendar systems that have months with different numbers of days, it may be necessary to adjust the month and also year when the day of the month is rolled up. It is the responsibility of the caller of roll() to perform that adjustment.
The time field to be set.
The new value.
This method sets the value of the specified time field.
The value for the year field.
The value for the month field, where 0 represents the first month.
The value for the day-of-the-month field.
This method sets the values of the year, month, and day-of-the-month fields of this Calendar.
public final void set(int year, int month, int date, int hour, int minute)
The value for the year field.
The value for the month field, where 0 represents the first month.
The value for the day-of-the-month field.
The value for the hour field.
The value for the minute field.
This method sets the values of the year, month, day-of-the-month, hour, and minute fields of this Calendar.
public final void set(int year, int month, int date, int hour, int minute, int second)
The value for the year field.
The value for the month field, where 0 represents the first month.
The value for the day-of-the-month field.
The value for the hour field.
The value for the minute field.
The value for the second field.
This method sets the values of the year, month, day-of-the-month, hour, minute, and second fields of this Calendar.
The value for the first day of the week.
This method sets the day that is considered the beginning of the week for this Calendar. This value should be determined by the Locale of this Calendar. For example, the first day of the week in the United States is Sunday; in France it's Monday.
A boolean value that specifies the leniency of this Calendar.
This method sets the leniency of this Calendar. A value of false specifies that the Calendar throws exceptions when questionable data is passed to it, while a value of true indicates that the Calendar makes its best guess to interpret questionable data. For example, if the Calendar is being lenient, a date such as March 135, 1997 is interpreted as the 135th day after March 1, 1997.
The value for the minimum number of days in the first week of the year.
This method sets the minimum number of days in the first week of the year. For example, a value of 7 indicates the first week of the year must be a full week, while a value of 1 indicates the first week of the year can contain a single day. This value should be determined by the Locale of this Calendar.
A Date object that represents the new time value.
This method sets the point in time that is represented by this Calendar.
A TimeZone object that represents the new time zone.
This method is used to set the time zone of this Calendar.
This method fills out the fields of this Calendar as much as possible by calling computeTime() and computeFields().
This method calculates the time fields of this Calendar from its raw time value.
This method calculates the raw time value of this Calendar from its time field values.
The raw time value of this Calendar.
This method returns the raw time value of this Calendar. The value is measured as the number of milliseconds since midnight, January 1, 1970 GMT.
A time field constant.
The value of the given time field.
This method returns the value of the specified time field without first checking to see if it needs to be computed from the raw time value.
The new raw time value for this Calendar.
This method sets the raw time value of this Calendar. The value is measured as the number of milliseconds since midnight, January 1, 1970 GMT.
|
Method |
Inherited From |
Method |
Inherited From |
|---|---|---|---|
|
finalize() |
Object |
getClass() |
Object |
|
hashCode() |
Object |
notify() |
Object |
|
notifyAll() |
Object |
toString() |
Object |
|
wait() |
Object |
wait(long) |
Object |
|
wait(long, int) |
Object |
Cloneable, Date, DateFormat, GregorianCalendar, Locale, Serializable, TimeZone
|
 |
|
| BitSet |  |
Date |
