com.ibm.icu.util

Class ChineseCalendar

Implemented Interfaces:
Cloneable, Comparable, Serializable

public class ChineseCalendar
extends Calendar

ChineseCalendar is a concrete subclass of Calendar that implements a traditional Chinese calendar. The traditional Chinese calendar is a lunisolar calendar: Each month starts on a new moon, and the months are numbered according to solar events, specifically, to guarantee that month 11 always contains the winter solstice. In order to accomplish this, leap months are inserted in certain years. Leap months are numbered the same as the month they follow. The decision of which month is a leap month depends on the relative movements of the sun and moon.

This class defines one addition field beyond those defined by Calendar: The IS_LEAP_MONTH field takes the value of 0 for normal months, or 1 for leap months.

All astronomical computations are performed with respect to a time zone of GMT+8:00 and a longitude of 120 degrees east. Although some calendars implement a historically more accurate convention of using Beijing's local longitude (116 degrees 25 minutes east) and time zone (GMT+7:45:40) for dates before 1929, we do not implement this here.

Years are counted in two different ways in the Chinese calendar. The first method is by sequential numbering from the 61st year of the reign of Huang Di, 2637 BCE, which is designated year 1 on the Chinese calendar. The second method uses 60-year cycles from the same starting point, which is designated year 1 of cycle 1. In this class, the EXTENDED_YEAR field contains the sequential year count. The ERA field contains the cycle number, and the YEAR field contains the year of the cycle, a value between 1 and 60.

There is some variation in what is considered the starting point of the calendar, with some sources starting in the first year of the reign of Huang Di, rather than the 61st. This gives continuous year numbers 60 years greater and cycle numbers one greater than what this class implements.

Because ChineseCalendar defines an additional field and redefines the way the ERA field is used, it requires a new format class, ChineseDateFormat. As always, use the methods DateFormat.getXxxInstance(Calendar cal,...) to obtain a formatter for this calendar.

References:

This class should not be subclassed.

ChineseCalendar usually should be instantiated using Calendar.getInstance(ULocale) passing in a ULocale with the tag "@calendar=chinese".

Author:
Alan Liu
See Also:
ChineseDateFormat, Calendar

Field Summary

static int
IS_LEAP_MONTH
Field indicating whether or not the current month is a leap month.

Fields inherited from class com.ibm.icu.util.Calendar

AM, AM_PM, APRIL, AUGUST, BASE_FIELD_COUNT, DATE, DAY_OF_MONTH, DAY_OF_WEEK, DAY_OF_WEEK_IN_MONTH, DAY_OF_YEAR, DECEMBER, DOW_LOCAL, DST_OFFSET, EPOCH_JULIAN_DAY, ERA, EXTENDED_YEAR, FEBRUARY, FRIDAY, GREATEST_MINIMUM, HOUR, HOUR_OF_DAY, INTERNALLY_SET, JANUARY, JAN_1_1_JULIAN_DAY, JULIAN_DAY, JULY, JUNE, LEAST_MAXIMUM, MARCH, MAXIMUM, MAX_DATE, MAX_FIELD_COUNT, MAX_JULIAN, MAX_MILLIS, MAY, MILLISECOND, MILLISECONDS_IN_DAY, MINIMUM, MINIMUM_USER_STAMP, MINUTE, MIN_DATE, MIN_JULIAN, MIN_MILLIS, MONDAY, MONTH, NOVEMBER, OCTOBER, ONE_DAY, ONE_HOUR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, PM, RESOLVE_REMAP, SATURDAY, SECOND, SEPTEMBER, SUNDAY, THURSDAY, TUESDAY, UNDECIMBER, UNSET, WEDNESDAY, WEEKDAY, WEEKEND, WEEKEND_CEASE, WEEKEND_ONSET, WEEK_OF_MONTH, WEEK_OF_YEAR, YEAR, YEAR_WOY, ZONE_OFFSET

Constructor Summary

ChineseCalendar()
Construct a Chinese calendar with the default time zone and locale.
ChineseCalendar(TimeZone zone, Locale locale)
Construct a Chinese calendar with the given time zone and locale.
ChineseCalendar(TimeZone zone, ULocale locale)
Construct a Chinese calendar with the given time zone and locale.

Method Summary

void
add(int field, int amount)
Override Calendar to handle leap months properly.
protected int[][][]
getFieldResolutionTable()
Override Calendar to add IS_LEAP_MONTH to the field resolution table.
String
getType()
Return the current Calendar type.
protected void
handleComputeFields(int julianDay)
Override Calendar to compute several fields specific to the Chinese calendar system.
protected int
handleComputeMonthStart(int eyear, int month, boolean useMonth)
Return the Julian day number of day before the first day of the given month in the given extended year.
protected int[]
handleCreateFields()
Override Calendar to allocate our additional field.
protected DateFormat
handleGetDateFormat(String pattern, ULocale locale)
Framework method to create a calendar-specific DateFormat object using the the given pattern.
protected int
handleGetExtendedYear()
Implement abstract Calendar method to return the extended year defined by the current fields.
protected int
handleGetLimit(int field, int limitType)
Override Calendar to return the limit value for the given field.
protected int
handleGetMonthLength(int extendedYear, int month)
Override Calendar method to return the number of days in the given extended year and month.
void
roll(int field, int amount)
Override Calendar to handle leap months properly.

Methods inherited from class com.ibm.icu.util.Calendar

add, after, before, clear, clear, clone, compareTo, compareTo, complete, computeFields, computeGregorianFields, computeGregorianMonthStart, computeJulianDay, computeMillisInDay, computeTime, computeZoneOffset, equals, fieldDifference, fieldName, floorDivide, floorDivide, floorDivide, floorDivide, get, getActualMaximum, getActualMinimum, getAvailableLocales, getAvailableULocales, getDateTimeFormat, getDateTimeFormat, getDayOfWeekType, getDisplayName, getDisplayName, getFieldCount, getFieldResolutionTable, getFirstDayOfWeek, getGreatestMinimum, getGregorianDayOfMonth, getGregorianDayOfYear, getGregorianMonth, getGregorianYear, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getLeastMaximum, getLimit, getLocale, getMaximum, getMinimalDaysInFirstWeek, getMinimum, getStamp, getTime, getTimeInMillis, getTimeZone, getType, getWeekendTransition, gregorianMonthLength, gregorianPreviousMonthLength, handleComputeFields, handleComputeJulianDay, handleComputeMonthStart, handleCreateFields, handleGetDateFormat, handleGetDateFormat, handleGetExtendedYear, handleGetLimit, handleGetMonthLength, handleGetYearLength, hashCode, internalGet, internalGet, internalGetTimeInMillis, internalSet, isEquivalentTo, isGregorianLeapYear, isLenient, isSet, isWeekend, isWeekend, julianDayToDayOfWeek, julianDayToMillis, millisToJulianDay, newerField, newestStamp, pinField, prepareGetActual, resolveFields, roll, roll, set, set, set, set, setFirstDayOfWeek, setLenient, setMinimalDaysInFirstWeek, setTime, setTimeInMillis, setTimeZone, toString, validateField, validateField, validateFields, weekNumber, weekNumber

Field Details

IS_LEAP_MONTH

public static int IS_LEAP_MONTH
Field indicating whether or not the current month is a leap month. Should have a value of 0 for non-leap months, and 1 for leap months.

Constructor Details

ChineseCalendar

public ChineseCalendar()
Construct a Chinese calendar with the default time zone and locale.

ChineseCalendar

public ChineseCalendar(TimeZone zone,
                       Locale locale)
Construct a Chinese calendar with the given time zone and locale.
Parameters:
zone - time zone for this calendar
locale - locale for this calendar

ChineseCalendar

public ChineseCalendar(TimeZone zone,
                       ULocale locale)
Construct a Chinese calendar with the given time zone and locale.
Parameters:
zone - time zone for this calendar
locale - ulocale for this calendar

Method Details

add

public void add(int field,
                int amount)
Override Calendar to handle leap months properly.
Overrides:
add in interface Calendar

getFieldResolutionTable

protected int[][][] getFieldResolutionTable()
Override Calendar to add IS_LEAP_MONTH to the field resolution table.
Overrides:
getFieldResolutionTable in interface Calendar

getType

public String getType()
Return the current Calendar type.
Overrides:
getType in interface Calendar
Returns:
type of calendar (gregorian, etc.)

handleComputeFields

protected void handleComputeFields(int julianDay)
Override Calendar to compute several fields specific to the Chinese calendar system. These are:
  • ERA
  • YEAR
  • MONTH
  • DAY_OF_MONTH
  • DAY_OF_YEAR
  • EXTENDED_YEAR
The DAY_OF_WEEK and DOW_LOCAL fields are already set when this method is called. The getGregorianXxx() methods return Gregorian calendar equivalents for the given Julian day.

Compute the ChineseCalendar-specific field IS_LEAP_MONTH.

Overrides:
handleComputeFields in interface Calendar

handleComputeMonthStart

protected int handleComputeMonthStart(int eyear,
                                      int month,
                                      boolean useMonth)
Return the Julian day number of day before the first day of the given month in the given extended year.

Note: This method reads the IS_LEAP_MONTH field to determine whether the given month is a leap month.

Overrides:
handleComputeMonthStart in interface Calendar
Parameters:
eyear - the extended year
month - the zero-based month. The month is also determined by reading the IS_LEAP_MONTH field.
Returns:
the Julian day number of the day before the first day of the given month and year

handleCreateFields

protected int[] handleCreateFields()
Override Calendar to allocate our additional field.
Overrides:
handleCreateFields in interface Calendar

handleGetDateFormat

protected DateFormat handleGetDateFormat(String pattern,
                                         ULocale locale)
Framework method to create a calendar-specific DateFormat object using the the given pattern. This method is responsible for creating the calendar- specific DateFormat and DateFormatSymbols objects as needed.
Overrides:
handleGetDateFormat in interface Calendar

handleGetExtendedYear

protected int handleGetExtendedYear()
Implement abstract Calendar method to return the extended year defined by the current fields. This will use either the ERA and YEAR field as the cycle and year-of-cycle, or the EXTENDED_YEAR field as the continuous year count, depending on which is newer.
Overrides:
handleGetExtendedYear in interface Calendar

handleGetLimit

protected int handleGetLimit(int field,
                             int limitType)
Override Calendar to return the limit value for the given field.
Overrides:
handleGetLimit in interface Calendar

handleGetMonthLength

protected int handleGetMonthLength(int extendedYear,
                                   int month)
Override Calendar method to return the number of days in the given extended year and month.

Note: This method also reads the IS_LEAP_MONTH field to determine whether or not the given month is a leap month.

Overrides:
handleGetMonthLength in interface Calendar

roll

public void roll(int field,
                 int amount)
Override Calendar to handle leap months properly.
Overrides:
roll in interface Calendar

Copyright (c) 2006 IBM Corporation and others.