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 Locales

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.

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.

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:

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:

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.