Documentation Contents

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

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.
Contact Us