@CalendarType(value="japanese") public final class JapaneseCalendar extends Calendrical<JapaneseCalendar.Unit,JapaneseCalendar> implements LocalizedPatternSupport
Represents the Japanese calendar from 701 AD (julian) until now.
It is a mixed calendar, lunisolar before Meiji 6 (= 1873-01-01) and then gregorian. A special era system
is used to count years where a Japanese era is also called Nengo. The first year of an era or nengo
always has the number 1. Before Meiji, nengos were announced at any irregular time, often even more than
one nengo during the reign of an emperor. In midage during the nanboku-chō-period (1334-1392), there
were even two concurrent nengo systems in effect (southern versus northern court causing a certain kind
of non-temporal state in year counting and sorting). In modern times, nengos are associated only once with
the actual emperor or tenno.
While the gregorian period since Meiji 6 uses exactly the same months from January to December) and day-dating methods like in Western calendar, the lunisolar period in old times was completely different. All months were either 29 or 30 days long. The month length depended on the astronomical event of New Moon, but did often not follow exactly the new moon due to historical deviations and misleading calculations. The Japanese people had originally adopted their calendar from China. Therefore the old lunisolar calendar knew sometimes leap months in order to compensate for the difference between lunar cycles and the revolution of the earth around the sun. Such a leap month could be inserted any time during a lunisolar year, usually every 2 or 3 years. A leap month has the same number as the preceding month but is indicated by a special char (Time4J uses the asterisk for non-East-Asian languages). See also Wikipedia.
Note: The lunisolar calendar part does not use astronomical calculations but depends on the original chronological tables from Paul Y. Tsuchihashi for the purpose of greatest historical accuracy.
Following elements which are declared as constants are registered by this class:
DAY_OF_WEEKDAY_OF_MONTHDAY_OF_YEARWEEKDAY_IN_MONTHMONTH_OF_YEARMONTH_AS_ORDINALKOKI_YEARYEAR_OF_ERAERAFurthermore, all elements defined in EpochDays and CommonElements are supported.
Example of usage:
ChronoFormatter<JapaneseCalendar> formatter =
ChronoFormatter.ofPattern(
"MMMM/dd, G y",
PatternType.NON_ISO_DATE,
Locale.ENGLISH,
JapaneseCalendar.axis());
JapaneseCalendar jcal = JapaneseCalendar.ofGregorian(Nengo.HEISEI, 29, 4, 14);
System.out.println(formatter.format(jcal)); // April/14, Heisei 29
ChronoFormatter<JapaneseCalendar> parser =
ChronoFormatter.ofPattern(
"Gy年M月d日",
PatternType.NON_ISO_DATE,
Locale.JAPANESE,
JapaneseCalendar.axis()
).with(Leniency.LAX); // use parsed nengo (attention: Ansei-1 == Kaei-7)
System.out.println(parser.parse("安政元年閏7月14日")); // Ansei-1(1854)-*7-14
The second example also uses the preferred form for the first year of a nengo as "元" (gannen). Another special feature: Two-digit-years using a pivot year are effectively switched off even if the pattern "yy" is used (but users should avoid this pattern and prefer "y").
Nengo,
EastAsianMonth,
NumberSystem.JAPANESE,
Serialized Form| Modifier and Type | Class and Description |
|---|---|
static class |
JapaneseCalendar.Unit
Defines some calendar units for the Japanese calendar.
|
| Modifier and Type | Field and Description |
|---|---|
static StdCalendarElement<java.lang.Integer,JapaneseCalendar> |
DAY_OF_MONTH
Represents the Japanese day of month.
|
static StdCalendarElement<Weekday,JapaneseCalendar> |
DAY_OF_WEEK
Represents the Japanese day of week.
|
static StdCalendarElement<java.lang.Integer,JapaneseCalendar> |
DAY_OF_YEAR
Represents the Japanese day of year.
|
static TextElement<Nengo> |
ERA
Represents the Japanese era (nengo).
|
static ChronoElement<java.lang.Integer> |
KOKI_YEAR
Counts the years since the supposed foundation date of Japan by the legendary emperor Jimmu.
|
static StdCalendarElement<java.lang.Integer,JapaneseCalendar> |
MONTH_AS_ORDINAL
Represents the ordinal index of a Japanese month.
|
static TextElement<EastAsianMonth> |
MONTH_OF_YEAR
Represents the Japanese month.
|
static OrdinalWeekdayElement<JapaneseCalendar> |
WEEKDAY_IN_MONTH
Element with the ordinal day-of-week within given calendar month.
|
static StdCalendarElement<java.lang.Integer,JapaneseCalendar> |
YEAR_OF_ERA
Represents the Japanese year associated with a nengo.
|
| Modifier and Type | Method and Description |
|---|---|
GeneralTimestamp<JapaneseCalendar> |
at(PlainTime time)
Creates a new local timestamp with this date and given wall time.
|
GeneralTimestamp<JapaneseCalendar> |
atTime(int hour,
int minute)
Is equivalent to
at(PlainTime.of(hour, minute)). |
static TimeAxis<JapaneseCalendar.Unit,JapaneseCalendar> |
axis()
Returns the associated time axis.
|
int |
compareTo(JapaneseCalendar other)
Compares first by the temporal position then by nengo position.
|
boolean |
equals(java.lang.Object obj)
Based on the epoch day number and the calendar system.
|
int |
getDayOfMonth()
Yields the Japanese day of month.
|
Weekday |
getDayOfWeek()
Determines the day of week.
|
int |
getDayOfYear()
Yields the Japanese day of year.
|
static Weekmodel |
getDefaultWeekmodel()
Obtains the standard week model of this calendar.
|
Nengo |
getEra()
Yields the Japanese era (nengo).
|
EastAsianMonth |
getMonth()
Yields the Japanese month.
|
int |
getYear()
Yields the Japanese year which belongs to a nengo.
|
int |
hashCode()
Based on the epoch day number.
|
boolean |
isLeapYear()
Is the year of this date a leap year?
|
int |
lengthOfMonth()
Yields the length of current Japanese month in days.
|
int |
lengthOfYear()
Yields the length of current Japanese year in days.
|
static JapaneseCalendar |
nowInSystemTime()
Obtains the current calendar date in system time.
|
static JapaneseCalendar |
of(Nengo nengo,
int yearOfNengo,
EastAsianMonth month,
int dayOfMonth)
Equivalent to
JapaneseCalendar.of(nengo, yearOfNengo, month, dayOfMonth, Leniency.SMART). |
static JapaneseCalendar |
of(Nengo nengo,
int yearOfNengo,
EastAsianMonth month,
int dayOfMonth,
Leniency leniency)
Creates a new instance of a Japanese calendar date.
|
static JapaneseCalendar |
ofGregorian(Nengo nengo,
int yearOfNengo,
int month,
int dayOfMonth)
Creates a modern Japanese calendar for all dates since Meiji 6 (gregorian calendar rules).
|
java.lang.String |
toString()
Provides a complete textual representation of the state of
this time point.
|
getDaysSinceEpochUTC, isAfter, isBefore, isSimultaneous, minus, plus, transform, transform, transformmax, min, minus, minus, plus, plus, until, untilcontains, get, get, getInt, getMaximum, getMinimum, getRegisteredElements, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with@FormattableElement(format="G") public static final TextElement<Nengo> ERA
Represents the Japanese era (nengo).
@FormattableElement(format="y") public static final StdCalendarElement<java.lang.Integer,JapaneseCalendar> YEAR_OF_ERA
Represents the Japanese year associated with a nengo.
Its maximum value corresponds to the value 1 of next nengo if present.
public static final ChronoElement<java.lang.Integer> KOKI_YEAR
Counts the years since the supposed foundation date of Japan by the legendary emperor Jimmu.
This imperial way of counting years was used from 1873 until the end of Second World War (called
Kōki) and is 660 years in advance of gregorian years. However, the standard way of counting years
in this calendar is the nengo-based year.
@FormattableElement(format="M", standalone="L") public static final TextElement<EastAsianMonth> MONTH_OF_YEAR
Represents the Japanese month.
If used in combination with numeric formatting (via pattern length smaller than 3, M or MM) then
the format attribute Attributes.NUMBER_SYSTEM will be taken into account. The East Asian
languages Japanese, Chinese and Korean usually define an extra literal behind the number for the
month. In such a case, the strong recommendation is to use numerical formatting together with the
literal, for example the pattern "M月" in Japanese. Patterns using "MMM" or even
"MMMM" (without the literal "月") should only be used if the context is in modern
times after 1872 and gregorian month names are wished.
public static final StdCalendarElement<java.lang.Integer,JapaneseCalendar> MONTH_AS_ORDINAL
Represents the ordinal index of a Japanese month.
The value is only identical to the regular month number since Meiji 6 (1873). If users want
to get the regular month number all times then it is only safe to use the expression
japaneseDate.get(MONTH_OF_YEAR).getNumber(), not this element. Following example
illustrates the difference for the lunisolar year Kaei-7 (1854) which contains a leap month:
MONTH_OF_YEAR |
1 | 2 | 3 | 4 | 5 | 6 | 7 | *7 | 8 | 9 | 10 | 11 | 12 |
| MONTH_AS_ORDINAL | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
This element can be used in conjunction with
ordinal formatting.
@FormattableElement(format="d") public static final StdCalendarElement<java.lang.Integer,JapaneseCalendar> DAY_OF_MONTH
Represents the Japanese day of month.
@FormattableElement(format="D") public static final StdCalendarElement<java.lang.Integer,JapaneseCalendar> DAY_OF_YEAR
Represents the Japanese day of year.
@FormattableElement(format="E") public static final StdCalendarElement<Weekday,JapaneseCalendar> DAY_OF_WEEK
Represents the Japanese day of week.
If the day-of-week is set to a new value then Time4J handles the Japanese calendar week as starting on Sunday.
@FormattableElement(format="F") public static final OrdinalWeekdayElement<JapaneseCalendar> WEEKDAY_IN_MONTH
Element with the ordinal day-of-week within given calendar month.
public static JapaneseCalendar ofGregorian(Nengo nengo, int yearOfNengo, int month, int dayOfMonth)
Creates a modern Japanese calendar for all dates since Meiji 6 (gregorian calendar rules).
Leaving the gregorian condition aside, equivalent to
JapaneseCalendar.of(nengo, yearOfNengo, EastAsianMonth.valueOf(month), dayOfMonth, Leniency.SMART).
nengo - Japanese era (Meiji or later)yearOfNengo - year of nengo starting with number 1 (if Meiji then starting with 6)month - gregorian month (1-12)dayOfMonth - day of month >= 1JapaneseCalendarjava.lang.IllegalArgumentException - in case of any inconsistenciesof(Nengo, int, EastAsianMonth, int, Leniency)public static JapaneseCalendar of(Nengo nengo, int yearOfNengo, EastAsianMonth month, int dayOfMonth)
Equivalent to JapaneseCalendar.of(nengo, yearOfNengo, month, dayOfMonth, Leniency.SMART).
nengo - Japanese erayearOfNengo - year of nengo starting with number 1month - japanese month (must not be a leap month for all years after or equal to Meiji 6)dayOfMonth - day of month >= 1JapaneseCalendarjava.lang.IllegalArgumentException - in case of any inconsistenciesof(Nengo, int, EastAsianMonth, int, Leniency)public static JapaneseCalendar of(Nengo nengo, int yearOfNengo, EastAsianMonth month, int dayOfMonth, Leniency leniency)
Creates a new instance of a Japanese calendar date.
The leniency mainly handles the transition of nengos and is strongly recommended to be smart. The strict and the lax mode do not try to change given nengo in case of transition. If such a nengo is not really appropriate because the nengo was not yet introduced on that day then the strict mode will throw an exception while the lax mode does not do anything. The smart mode however, will adjust the nengo to a better matching nengo. Example for the transition from Shōwa to Heisei which happened on 1989-01-08 (Heisei-1-01-08):
| Input | Strict | Smart | Lax |
|---|---|---|---|
| Heisei-1-01-08 | Heisei-1-01-08 | Heisei-1-01-08 | Heisei-1-01-08 |
| Heisei-1-01-07 | {exception} | Shōwa-64-01-07 | Heisei-1-01-07 |
| Shōwa-64-01-08 | {exception} | Heisei-1-01-08 | Shōwa-64-01-08 |
| Shōwa-64-01-07 | Shōwa-64-01-07 | Shōwa-64-01-07 | Shōwa-64-01-07 |
nengo - Japanese erayearOfNengo - year of nengo starting with number 1month - japanese month (must not be a leap month for all years after or equal to Meiji 6)dayOfMonth - day of month >= 1leniency - helps to resolve ambivalent input if not strictJapaneseCalendarjava.lang.IllegalArgumentException - in case of any inconsistenciespublic static JapaneseCalendar nowInSystemTime()
Obtains the current calendar date in system time.
Convenient short-cut for: SystemClock.inLocalView().now(JapaneseCalendar.axis()).
SystemClock.inLocalView(),
ZonalClock.now(Chronology)public int getYear()
Yields the Japanese year which belongs to a nengo.
>= 1YEAR_OF_ERApublic EastAsianMonth getMonth()
Yields the Japanese month.
MONTH_OF_YEARpublic int getDayOfMonth()
Yields the Japanese day of month.
DAY_OF_MONTHpublic Weekday getDayOfWeek()
Determines the day of week.
The Japanese calendar also uses a 7-day-week.
DAY_OF_WEEKpublic int getDayOfYear()
Yields the Japanese day of year.
>= 1DAY_OF_YEARpublic int lengthOfMonth()
Yields the length of current Japanese month in days.
public int lengthOfYear()
Yields the length of current Japanese year in days.
public boolean isLeapYear()
Is the year of this date a leap year?
Note: If this instance is before Meiji 6 (lunisolar period) then the lunisolar year is considered as a leap year if and only if it contains a leap month.
public GeneralTimestamp<JapaneseCalendar> at(PlainTime time)
Creates a new local timestamp with this date and given wall time.
If the time T24:00 is used
then the resulting timestamp will automatically be normalized such
that the timestamp will contain the following day instead.
time - wall timepublic GeneralTimestamp<JapaneseCalendar> atTime(int hour, int minute)
Is equivalent to at(PlainTime.of(hour, minute)).
hour - hour of day in range (0-24)minute - minute of hour in range (0-59)java.lang.IllegalArgumentException - if any argument is out of rangepublic int compareTo(JapaneseCalendar other)
Compares first by the temporal position then by nengo position.
The natural ordering is consistent with equals(Object) because the non-temporal state
is also taken into consideration. If users wish a temporal ordering only then they might consider
the methods isBefore(), isAfter() or isSimultaneous().
compareTo in interface java.lang.Comparable<JapaneseCalendar>compareTo in class Calendrical<JapaneseCalendar.Unit,JapaneseCalendar>other - the other Japanese calendar to be compared withCalendrical.isBefore(CalendarDate),
Calendrical.isAfter(CalendarDate),
Calendrical.isSimultaneous(CalendarDate)public boolean equals(java.lang.Object obj)
CalendricalBased on the epoch day number and the calendar system.
In other words: Two date object are equal if they have the same temporal position on the local timeline and have the same calendrical type. Subclasses which define further state attributes must override this method.
If an only temporal comparison is required then the method
Calendrical.isSimultaneous(CalendarDate) is to be used.
equals in class Calendrical<JapaneseCalendar.Unit,JapaneseCalendar>Chronology.getChronoType()public int hashCode()
CalendricalBased on the epoch day number.
hashCode in class Calendrical<JapaneseCalendar.Unit,JapaneseCalendar>public java.lang.String toString()
TimePointProvides a complete textual representation of the state of this time point.
The textual description often follows the conventions of ISO-8601. Usually the description starts with the chronological informations which are coarse-grained and ends with those ones which are fine-grained (for example the ISO-notation YYYY-MM-DD).
toString in class TimePoint<JapaneseCalendar.Unit,JapaneseCalendar>public static Weekmodel getDefaultWeekmodel()
Obtains the standard week model of this calendar.
The Japanese calendar usually starts on Sunday.
public static TimeAxis<JapaneseCalendar.Unit,JapaneseCalendar> axis()
Returns the associated time axis.