Supported Calendars

This page documents supported calendar systems.

1. Introduction

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. Subclasses of Calendar interpret a Date according to the rules of a specific calendar system. The platform provides one public concrete subclass of Calendar: GregorianCalendar. The factory method, Calendar.getInstance, returns the concrete calendar system implementation for the given Locale. The following are supported calendar systems:

`Locale`	Calendar System	Since (JRE version)
th_TH (with any variant)	Thai Buddhist calendar	1.4
ja_JP_JP	Japanese imperial calendar	1.6
Any except above `Locale`s	Gregorian calendar (`GregorianCalendar`)	1.1

2. Thai Buddhist Calendar

In Thailand, the Gregorian calendar system is used with the Buddhist Era-based year numbering. In Buddhist Era (พุทธศักราช) or B.E. (พ.ศ.) for short, year 1 corresponds to BCE (BC) 543 (Julian). Therefore, Gregorian year + 543 is the B.E. year value.

The Calendar.getInstance method returns a Thai Buddhist calendar instance if a Thai locale is specified, which is determined by its language and country values. This Thai Buddhist calendar implementation supports dates accurately from B.E. 2484 (1941 Gregorian). The historical calendar system transitions are not supported by the implementation. The Calendar.ERA value for Buddhist Era is 1.

3. Japanese Imperial Calendar

In Japan, the Gregorian calendar system is used with the imperial era-based year numbering. An imperial era starts from an emperor's ascension and its year number is reset to 1 with a new era name. The first year of an imperial era is not in sync with the Gregorian year boundaries, and any day could be the first day of an imperial era. For example, the current era started from January 8, 1989 (Gregorian). However, the month and the day of month numberings are in sync with the Gregorian calendar system.

The Calendar.getInstance method returns a Japanese imperial calendar instance if ja_JP_JP locale is specified. This implementation supports the eras since Meiji with the following transition dates.

Era Name (in Japanese)	Era Abbr.	`ERA` field value	Transition date and time (Gregorian)
- (西暦)	-	0	-
Meiji (明治)	M	1	1868-01-01 00:00:00 local time
Taisho (大正)	T	2	1912-07-30 00:00:00 local time
Showa (昭和)	S	3	1926-12-25 00:00:00 local time
Heisei (平成)	H	4	1989-01-08 00:00:00 local time

Before Meiji, the Gregorian year numbering is supported. Unlike GregorianCalendar, the Japanese imperial calendar implementation doesn't support any Julian to Gregorian transition, and the year numbering before Gregorian 1 is 0, -1, -2, ..., not 1, 2, 3, ... Strictly speaking, the Gregorian calendar is in use from 1873 (Meiji 5) and other calendar systems were used before that year. However, the implementation defines the first day of Meiji as January 1, 1868, which is not historically accurate. The Japanese decrees related to calendar systems don't specify how to deal with time zones outside of Japan. The implementation assumes that era transitions occur at midnight in local time in any time zone.

In the Calendar API, some fields are in sync with the year value for the era transitions and therefore handle irregular rules in the first year of an imperial era. The following table shows those fields.

Calendar field	Description
`WEEK_OF_YEAR`	To determine the first `WEEK_OF_YEAR` of year 1 in each era, the same rules as determining the first week by the first day of week and minimal days in the first week values are applied. For example, if the first day of week is `SUNDAY` and the minimal days in the first week is 1, the `WEEK_OF_YEAR` value of 1926-12-18 is 51 of Taisho 15 and the value of 1926-12-25 is 1 of Showa 1.
`DAY_OF_YEAR`	The `DAY_OF_YEAR` value of the first day of each era is 1. For example, looking at the transition between the Showa and Heisei eras, the last day of the Showa era (Showa 64.01.07, gregorian value 1989-01-07) is 7 and the next day, which is the first day of the Heisei era (Heisei 1.01.08), is 1. The `getLeastMaximum` method returns the minimum value of all year 1 lengths in days.

4. Formatting and Parsing Non-GregorianCalendar Dates

A DateFormat instance has a Calendar instance for internal date-time conversions based on the given Locale or the default one. The same rule is applied for creating a Calendar instance. For example, if ja_JP_JP locale is specified, the DateFormat.getDateInstance method returns a DateFormat instance that handles Japanese imperial calendar dates. The following code:

DateFormat df = DateFormat.getDateInstance(DateFormat.FULL,
                                           new Locale("ja", "JP", "JP"));
System.out.println(df.format(new Date()));

will produce the output, like:

平成17年10月25日

Also, the DateFormat.parse method parses a date string with an imperial era. The following code:

System.out.println(df.parse("平成元年10月25日"));

will produce the output in the Asia/Tokyo time zone:

Wed Oct 25 00:00:00 JST 1989

Note that a Date object returned by the DateFormat.parse method represents a corresponding Gregorian date. To convert a Date to a Japanese imperial date, the Calendar.setTime method must be used with the given Date.

In SimpleDateFormat, the following rules are applied for the Thai Buddhist and Japanese imperial calendar systems.

Calendar system	Pattern Letter	Description
Thai Buddhist	`G`	The number of pattern letters doesn't affect displayed era names.
Thai Buddhist	`y`	The same rule of the number of pattern letters as `GregorianCalendar` is applied.
Japanese imperial	`G`	For formatting, if the number of pattern letters is 4 or more, the long era names (e.g., "平成") are used. Otherwise, the abbreviations (e.g., "H") are used. For parsing, both the long era names and abbreviations are accepted.
Japanese imperial	`y`	For formatting, if the number of pattern letters is 4 or more, the first year of an era is formatted as the locale specific representation, such as "元" in Japanese locale. Other year values are displayed as numbers. The 2- and 4-digit rules of `GregorianCalendar` date formatting are not applied. For parsing, both the locale specific representation and the number representation are accepted.

If the variant element is "TH" in Thai locale, the Thai digits are used for the date-time formatting. For example, the following code:

DateFormat df = DateFormat.getDateInstance(DateFormat.FULL,
                                           new Locale("th", "TH", "TH"));
System.out.println(df.format(new Date()));

will produce the output, like:
วันอังคารที่ ๒๕ ตุลาคม พ.ศ. ๒๕๔๘

5. Serialization Considerations

When a Calendar object returned by the Calendar.getInstance factory method is serialized and sent to another JVM, deserialization of the object fails if the destination JVM does not support the same Calendar subclass that has been used to create the serialized Calendar object. Please make sure that the same Calendar subclasses are supported in JVMs where you would like to exchange serialized Calendar objects.