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.