java.util
Class Calendar

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

public abstract class Calendar
extends Object

Calendar is an abstract base class for converting between a Date object and a set of integer fields such as YEAR, MONTH, DAY, HOUR, and so on. (A Date object represents a specific instant in time with millisecond precision. See Date for information about the Date class.)

Subclasses of Calendar interpret a Date according to the rules of a specific calendar system.

Like other locale-sensitive classes, Calendar provides a class method, getInstance, for getting a generally useful object of this type.

 Calendar rightNow = Calendar.getInstance();
 

A Calendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).

When computing a Date from time fields, there may be insufficient information to compute the Date (such as only year and month but no day in the month).

Insufficient information. The calendar will use default information to specify the missing fields. This may vary by calendar; for the Gregorian calendar, the default for a field is the same as that of the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. Note: The ambiguity in interpretation of what day midnight belongs to, is resolved as so: midnight "belongs" to the following day.
23:59 on Dec 31, 1969 < 00:00 on Jan 1, 1970.
12:00 PM is midday, and 12:00 AM is midnight.
11:59 PM on Jan 1 < 12:00 AM on Jan 2 < 12:01 AM on Jan 2.
11:59 AM on Mar 10 < 12:00 PM on Mar 10 < 12:01 PM on Mar 10.
24:00 or greater are invalid. Hours greater than 12 are invalid in AM/PM mode. Setting the time will never change the date.

If equivalent times are entered in AM/PM or 24 hour mode, equality will be determined by the actual time rather than the entered time.

This class has been subset for Java ME based on the JDK 1.3 Calendar class. Many methods and variables have been pruned, and other methods simplified, in an effort to reduce the size of this class.

See Also:
Date, TimeZone

Field Summary
static int AM
          Value of the AM_PM field indicating the period of the day from midnight to just before noon.
static int AM_PM
          Field number for get and set indicating whether the HOUR is before or after noon.
static int APRIL
          Value of the MONTH field indicating the fourth month of the year.
static int AUGUST
          Value of the MONTH field indicating the eighth month of the year.
static int DATE
          Field number for get and set indicating the day of the month.
static int DAY_OF_MONTH
          Field number for get and set indicating the day of the month.
static int DAY_OF_WEEK
          Field number for get and set indicating the day of the week.
static int DECEMBER
          Value of the MONTH field indicating the twelfth month of the year.
static int FEBRUARY
          Value of the MONTH field indicating the second month of the year.
protected  int[] fields
          The field values for the currently set time for this calendar.
static int FRIDAY
          Value of the DAY_OF_WEEK field indicating Friday.
static int HOUR
          Field number for get and set indicating the hour of the morning or afternoon.
static int HOUR_OF_DAY
          Field number for get and set indicating the hour of the day.
protected  boolean[] isSet
          The flags which tell if a specified time field for the calendar is set.
static int JANUARY
          Value of the MONTH field indicating the first month of the year.
static int JULY
          Value of the MONTH field indicating the seventh month of the year.
static int JUNE
          Value of the MONTH field indicating the sixth month of the year.
static int MARCH
          Value of the MONTH field indicating the third month of the year.
static int MAY
          Value of the MONTH field indicating the fifth month of the year.
static int MILLISECOND
          Field number for get and set indicating the millisecond within the second.
static int MINUTE
          Field number for get and set indicating the minute within the hour.
static int MONDAY
          Value of the DAY_OF_WEEK field indicating Monday.
static int MONTH
          Field number for get and set indicating the month.
static int NOVEMBER
          Value of the MONTH field indicating the eleventh month of the year.
static int OCTOBER
          Value of the MONTH field indicating the tenth month of the year.
static int PM
          Value of the AM_PM field indicating the period of the day from noon to just before midnight.
static int SATURDAY
          Value of the DAY_OF_WEEK field indicating Saturday.
static int SECOND
          Field number for get and set indicating the second within the minute.
static int SEPTEMBER
          Value of the MONTH field indicating the ninth month of the year.
static int SUNDAY
          Value of the DAY_OF_WEEK field indicating Sunday.
static int THURSDAY
          Value of the DAY_OF_WEEK field indicating Thursday.
protected  long time
          The currently set time for this calendar, expressed in milliseconds after January 1, 1970, 0:00:00 GMT.
static int TUESDAY
          Value of the DAY_OF_WEEK field indicating Tuesday.
static int WEDNESDAY
          Value of the DAY_OF_WEEK field indicating Wednesday.
static int YEAR
          Field number for get and set indicating the year.
 
Constructor Summary
protected Calendar()
          Constructs a Calendar with the default time zone.
 
Method Summary
 boolean after(Object when)
          Compares the time field records.
 boolean before(Object when)
          Compares the time field records.
protected abstract  void computeFields()
          Converts the current millisecond time value time to field values in fields[].
protected abstract  void computeTime()
          Converts the current field values in fields[] to the millisecond time value time.
 boolean equals(Object obj)
          Compares this Calendar to an object reference.
 int get(int field)
          Gets the value for a given time field.
static Calendar getInstance()
          Gets a calendar using the default time zone and locale.
static Calendar getInstance(TimeZone zone)
          Gets a calendar using the specified time zone and default locale.
 Date getTime()
          Gets this Calendar's current time.
protected  long getTimeInMillis()
          Gets this Calendar's current time as a long expressed in milliseconds after January 1, 1970, 0:00:00 GMT (the epoch).
 TimeZone getTimeZone()
          Gets the time zone.
 int hashCode()
          Override hashCode.
 void set(int field, int value)
          Sets the time field with the given value.
 void setTime(Date date)
          Sets this Calendar's current time with the given Date.
protected  void setTimeInMillis(long millis)
          Sets this Calendar's current time from the given long value.
 void setTimeZone(TimeZone value)
          Sets the time zone with the given time zone value.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

AM

public static final int AM
Value of the AM_PM field indicating the period of the day from midnight to just before noon.

AM_PM

public static final int AM_PM
Field number for get and set indicating whether the HOUR is before or after noon. E.g., at 10:04:15.250 PM the AM_PM is PM.
See Also:
AM, PM, HOUR

APRIL

public static final int APRIL
Value of the MONTH field indicating the fourth month of the year.

AUGUST

public static final int AUGUST
Value of the MONTH field indicating the eighth month of the year.

DATE

public static final int DATE
Field number for get and set indicating the day of the month. This is a synonym for DAY_OF_MONTH.
See Also:
DAY_OF_MONTH

DAY_OF_MONTH

public static final int DAY_OF_MONTH
Field number for get and set indicating the day of the month. This is a synonym for DATE.
See Also:
DATE

DAY_OF_WEEK

public static final int DAY_OF_WEEK
Field number for get and set indicating the day of the week.

DECEMBER

public static final int DECEMBER
Value of the MONTH field indicating the twelfth month of the year.

FEBRUARY

public static final int FEBRUARY
Value of the MONTH field indicating the second month of the year.

fields

protected int[] fields
The field values for the currently set time for this calendar.
Since:
JDE 4.0.0

FRIDAY

public static final int FRIDAY
Value of the DAY_OF_WEEK field indicating Friday.

HOUR

public static final int HOUR
Field number for get and set indicating the hour of the morning or afternoon. HOUR is used for the 12-hour clock (0 - 11). Noon and midnight are represented by 0, not by 12. E.g., at 10:04:15.250 PM the HOUR is 10.
See Also:
AM_PM, HOUR_OF_DAY

HOUR_OF_DAY

public static final int HOUR_OF_DAY
Field number for get and set indicating the hour of the day. HOUR_OF_DAY is used for the 24-hour clock. E.g., at 10:04:15.250 PM the HOUR_OF_DAY is 22.

isSet

protected boolean[] isSet
The flags which tell if a specified time field for the calendar is set. This is an array of FIELD_COUNT booleans,
Since:
JDE 4.0.0

JANUARY

public static final int JANUARY
Value of the MONTH field indicating the first month of the year.

JULY

public static final int JULY
Value of the MONTH field indicating the seventh month of the year.

JUNE

public static final int JUNE
Value of the MONTH field indicating the sixth month of the year.

MARCH

public static final int MARCH
Value of the MONTH field indicating the third month of the year.

MAY

public static final int MAY
Value of the MONTH field indicating the fifth month of the year.

MILLISECOND

public static final int MILLISECOND
Field number for get and set indicating the millisecond within the second. E.g., at 10:04:15.250 PM the MILLISECOND is 250.

MINUTE

public static final int MINUTE
Field number for get and set indicating the minute within the hour. E.g., at 10:04:15.250 PM the MINUTE is 4.

MONDAY

public static final int MONDAY
Value of the DAY_OF_WEEK field indicating Monday.

MONTH

public static final int MONTH
Field number for get and set indicating the month. This is a calendar-specific value.

NOVEMBER

public static final int NOVEMBER
Value of the MONTH field indicating the eleventh month of the year.

OCTOBER

public static final int OCTOBER
Value of the MONTH field indicating the tenth month of the year.

PM

public static final int PM
Value of the AM_PM field indicating the period of the day from noon to just before midnight.

SATURDAY

public static final int SATURDAY
Value of the DAY_OF_WEEK field indicating Saturday.

SECOND

public static final int SECOND
Field number for get and set indicating the second within the minute. E.g., at 10:04:15.250 PM the SECOND is 15.

SEPTEMBER

public static final int SEPTEMBER
Value of the MONTH field indicating the ninth month of the year.

SUNDAY

public static final int SUNDAY
Value of the DAY_OF_WEEK field indicating Sunday.

THURSDAY

public static final int THURSDAY
Value of the DAY_OF_WEEK field indicating Thursday.

time

protected long time
The currently set time for this calendar, expressed in milliseconds after January 1, 1970, 0:00:00 GMT.
Since:
JDE 4.0.0

TUESDAY

public static final int TUESDAY
Value of the DAY_OF_WEEK field indicating Tuesday.

WEDNESDAY

public static final int WEDNESDAY
Value of the DAY_OF_WEEK field indicating Wednesday.

YEAR

public static final int YEAR
Field number for get and set indicating the year. This is a calendar-specific value.
Constructor Detail

Calendar

protected Calendar()
Constructs a Calendar with the default time zone.
See Also:
TimeZone.getDefault()
Method Detail

after

public boolean after(Object when)
Compares the time field records. Equivalent to comparing result of conversion to UTC.
Parameters:
when - the Calendar to be compared with this Calendar.
Returns:
true if the current time of this Calendar is after the time of Calendar when; false otherwise.

before

public boolean before(Object when)
Compares the time field records. Equivalent to comparing result of conversion to UTC.
Parameters:
when - the Calendar to be compared with this Calendar.
Returns:
true if the current time of this Calendar is before the time of Calendar when; false otherwise.

computeFields

protected abstract void computeFields()
Converts the current millisecond time value time to field values in fields[]. This allows you to sync up the time field values with a new time that is set for the calendar.

computeTime

protected abstract void computeTime()
Converts the current field values in fields[] to the millisecond time value time.
Since:
JDE 4.0.0

equals

public boolean equals(Object obj)
Compares this Calendar to an object reference.
Overrides:
equals in class Object
Parameters:
obj - the object reference with which to compare
Returns:
true if this object is equal to obj; false otherwise

get

public final int get(int field)
Gets the value for a given time field.
Parameters:
field - the given time field (either YEAR, MONTH, DATE, DAY_OF_WEEK, HOUR_OF_DAY, HOUR, AM_PM, MINUTE, SECOND, or MILLISECOND
Returns:
the value for the given time field.
Throws:
ArrayIndexOutOfBoundsException - if the parameter is not one of the above.

getInstance

public static Calendar getInstance()
Gets a calendar using the default time zone and locale.
Returns:
a Calendar.

getInstance

public static Calendar getInstance(TimeZone zone)
Gets a calendar using the specified time zone and default locale.
Parameters:
zone - the time zone to use
Returns:
a Calendar.

getTime

public final Date getTime()
Gets this Calendar's current time.
Returns:
the current time.
See Also:
setTime(java.util.Date)

getTimeInMillis

protected long getTimeInMillis()
Gets this Calendar's current time as a long expressed in milliseconds after January 1, 1970, 0:00:00 GMT (the epoch).
Returns:
the current time as UTC milliseconds from the epoch.
See Also:
setTimeInMillis(long)

getTimeZone

public TimeZone getTimeZone()
Gets the time zone.
Returns:
the time zone object associated with this calendar.
See Also:
setTimeZone(java.util.TimeZone)

hashCode

public int hashCode()
Override hashCode. Generates the hash code for the Calendar object
Overrides:
hashCode in class Object

Following copied from class: Object
Returns:
a hash code value for this object.
See Also:
Object.equals(java.lang.Object), Hashtable

set

public final void set(int field,
                      int value)
Sets the time field with the given value.
Parameters:
field - the given time field.
value - the value to be set for the given time field.
Throws:
ArrayIndexOutOfBoundsException - if an illegal field parameter is received.

setTime

public final void setTime(Date date)
Sets this Calendar's current time with the given Date.

Note: Calling setTime() with Date(Long.MAX_VALUE) or Date(Long.MIN_VALUE) may yield incorrect field values from get().

Parameters:
date - the given Date.
See Also:
getTime()

setTimeInMillis

protected void setTimeInMillis(long millis)
Sets this Calendar's current time from the given long value.
Parameters:
millis - the new time in UTC milliseconds from the epoch.
See Also:
getTimeInMillis()

setTimeZone

public void setTimeZone(TimeZone value)
Sets the time zone with the given time zone value.
Parameters:
value - the given time zone.
See Also:
getTimeZone()



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.