JapaneseCalendar (Time4J-Base 5.8 API)

java.lang.Object
- net.time4j.engine.ChronoEntity<T>
- - net.time4j.engine.TimePoint<U,D>
  - - net.time4j.engine.Calendrical<JapaneseCalendar.Unit,JapaneseCalendar>
    - - net.time4j.calendar.JapaneseCalendar

All Implemented Interfaces:

Serializable, Comparable<JapaneseCalendar>, CalendarDate, ChronoDisplay, Temporal<CalendarDate>, LocalizedPatternSupport
```
@CalendarType(value="japanese")
public final class JapaneseCalendar
extends Calendrical<JapaneseCalendar.Unit,JapaneseCalendar>
implements LocalizedPatternSupport
```
Represents the Japanese calendar from 701 AD (julian) until now.

Introduction

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
Furthermore, all elements defined in EpochDays and CommonElements are supported.

Example of usage
```
     ChronoFormatter<JapaneseCalendar> formatter =
       ChronoFormatter.ofPattern(
         "MMMM/dd, G y",
         PatternType.CLDR_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.CLDR_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").

Support for unicode ca-extensions
```
      Locale locale = Locale.forLanguageTag("en-u-ca-japanese");
      ChronoFormatter<CalendarDate> f = ChronoFormatter.ofGenericCalendarStyle(DisplayMode.FULL, locale);
      assertThat(
          f.format(PlainDate.of(2017, 10, 1)),
          is("Sunday, October 1, 29 Heisei"));
 
```
Since:

3.32/4.27

Author:

Meno Hochschild

See Also:

Nengo, EastAsianMonth, NumberSystem.JAPANESE, Serialized Form

Concurrency:
This class is immutable and can be used by multiple threads in parallel.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class JapaneseCalendar.Unit
Defines some calendar units for the Japanese calendar.

Nested Classes
Modifier and Type	Class and Description
`static class`	`JapaneseCalendar.Unit` Defines some calendar units for the Japanese calendar.

Field Summary

Fields
Modifier and Type	Field and Description
`static StdCalendarElement<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<Integer,JapaneseCalendar>`	`DAY_OF_YEAR` Represents the Japanese day of year.
`static TextElement<Nengo>`	`ERA` Represents the Japanese era (nengo).
`static ChronoElement<Integer>`	`KOKI_YEAR` Counts the years since the supposed foundation date of Japan by the legendary emperor Jimmu.
`static StdCalendarElement<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<Integer,JapaneseCalendar>`	`YEAR_OF_ERA` Represents the Japanese year associated with a nengo.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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(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).
`String`	`toString()` Provides a complete textual representation of the state of this time point.

Methods inherited from class net.time4j.engine.Calendrical
getDaysSinceEpochUTC, isAfter, isBefore, isSimultaneous, minus, plus

Methods inherited from class net.time4j.engine.TimePoint
max, min, minus, minus, plus, plus, until, until

Methods inherited from class net.time4j.engine.ChronoEntity
contains, get, get, getInt, getMaximum, getMinimum, getRegisteredElements, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.time4j.format.LocalizedPatternSupport
getFormatPattern, getFormatPattern, useDynamicFormatPattern

Methods inherited from interface net.time4j.engine.CalendarDate
from, from, from, transform, transform, transform, transform, transform, transform

Methods inherited from interface net.time4j.engine.Temporal
isAfterAll, isAfterOrEqual, isBeforeAll, isBeforeOrEqual

Field Detail

ERA

@FormattableElement(format="G")
public static final TextElement<Nengo> ERA

Represents the Japanese era (nengo).

YEAR_OF_ERA
```
@FormattableElement(format="y")
public static final StdCalendarElement<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.

KOKI_YEAR
```
public static final ChronoElement<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.

MONTH_OF_YEAR
```
@FormattableElement(format="M",
                    alt="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.

MONTH_AS_ORDINAL

public static final StdCalendarElement<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 number/index during the lunisolar year Kaei 7
`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.

DAY_OF_MONTH

@FormattableElement(format="d")
public static final StdCalendarElement<Integer,JapaneseCalendar> DAY_OF_MONTH

Represents the Japanese day of month.

DAY_OF_YEAR

@FormattableElement(format="D")
public static final StdCalendarElement<Integer,JapaneseCalendar> DAY_OF_YEAR

Represents the Japanese day of year.

DAY_OF_WEEK
```
@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.

See Also:

getDefaultWeekmodel(), CommonElements.localDayOfWeek(Chronology, Weekmodel)

WEEKDAY_IN_MONTH

@FormattableElement(format="F")
public static final OrdinalWeekdayElement<JapaneseCalendar> WEEKDAY_IN_MONTH

Element with the ordinal day-of-week within given calendar month.

Method Detail

ofGregorian
```
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).

Parameters:

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 >= 1

Returns:

new instance of JapaneseCalendar

Throws:

IllegalArgumentException - in case of any inconsistencies

See Also:

of(Nengo, int, EastAsianMonth, int, Leniency)

of
```
public static JapaneseCalendar of(Nengo nengo,
                                  int yearOfNengo,
                                  EastAsianMonth month,
                                  int dayOfMonth)
```
Equivalent to JapaneseCalendar.of(nengo, yearOfNengo, month, dayOfMonth, Leniency.SMART).

Parameters:

nengo - Japanese era

yearOfNengo - year of nengo starting with number 1

month - japanese month (must not be a leap month for all years after or equal to Meiji 6)

dayOfMonth - day of month >= 1

Returns:

new instance of JapaneseCalendar

Throws:

IllegalArgumentException - in case of any inconsistencies

See Also:

of(Nengo, int, EastAsianMonth, int, Leniency)

of

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):

Output in different leniency modes
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

Parameters:: nengo - Japanese era; yearOfNengo - year of nengo starting with number 1; month - japanese month (must not be a leap month for all years after or equal to Meiji 6); dayOfMonth - day of month >= 1; leniency - helps to resolve ambivalent input if not strict
Returns:: new instance of JapaneseCalendar
Throws:: IllegalArgumentException - in case of any inconsistencies

nowInSystemTime
```
public static JapaneseCalendar nowInSystemTime()
```
Obtains the current calendar date in system time.

Convenient short-cut for: SystemClock.inLocalView().now(JapaneseCalendar.axis()).

Returns:

current calendar date in system time zone using the system clock

See Also:

SystemClock.inLocalView(), ZonalClock.now(Chronology)

getEra
```
public Nengo getEra()
```
Yields the Japanese era (nengo).

Returns:

Nengo

See Also:

ERA

getYear
```
public int getYear()
```
Yields the Japanese year which belongs to a nengo.

Returns:

int >= 1

See Also:

YEAR_OF_ERA

getMonth
```
public EastAsianMonth getMonth()
```
Yields the Japanese month.

Returns:

japanese month

See Also:

MONTH_OF_YEAR

getDayOfMonth
```
public int getDayOfMonth()
```
Yields the Japanese day of month.

Returns:

int

See Also:

DAY_OF_MONTH

getDayOfWeek
```
public Weekday getDayOfWeek()
```
Determines the day of week.

The Japanese calendar also uses a 7-day-week.

Returns:

Weekday

See Also:

DAY_OF_WEEK

getDayOfYear
```
public int getDayOfYear()
```
Yields the Japanese day of year.

Returns:

int >= 1

See Also:

DAY_OF_YEAR

lengthOfMonth
```
public int lengthOfMonth()
```
Yields the length of current Japanese month in days.

Returns:

int

lengthOfYear
```
public int lengthOfYear()
```
Yields the length of current Japanese year in days.

Returns:

int

isLeapYear
```
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.

Returns:

boolean

at
```
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.

Parameters:

time - wall time

Returns:

general timestamp as composition of this date and given time

atTime
```
public GeneralTimestamp<JapaneseCalendar> atTime(int hour,
                                                 int minute)
```
Is equivalent to at(PlainTime.of(hour, minute)).

Parameters:

hour - hour of day in range (0-24)

minute - minute of hour in range (0-59)

Returns:

general timestamp as composition of this date and given time

Throws:

IllegalArgumentException - if any argument is out of range

compareTo
```
public 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().

Specified by:

compareTo in interface Comparable<JapaneseCalendar>

Overrides:

compareTo in class Calendrical<JapaneseCalendar.Unit,JapaneseCalendar>

Parameters:

other - the other Japanese calendar to be compared with

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object

See Also:

Calendrical.isBefore(CalendarDate), Calendrical.isAfter(CalendarDate), Calendrical.isSimultaneous(CalendarDate)

equals
```
public boolean equals(Object obj)
```
Description copied from class: Calendrical

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

Overrides:

equals in class Calendrical<JapaneseCalendar.Unit,JapaneseCalendar>

See Also:

Chronology.getChronoType()

hashCode
```
public int hashCode()
```
Description copied from class: Calendrical

Based on the epoch day number.

Overrides:

hashCode in class Calendrical<JapaneseCalendar.Unit,JapaneseCalendar>

toString
```
public String toString()
```
Description copied from class: TimePoint

Provides 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).

Specified by:

toString in class TimePoint<JapaneseCalendar.Unit,JapaneseCalendar>

getDefaultWeekmodel
```
public static Weekmodel getDefaultWeekmodel()
```
Obtains the standard week model of this calendar.

The Japanese calendar usually starts on Sunday.

Returns:

Weekmodel

axis

public static TimeAxis<JapaneseCalendar.Unit,JapaneseCalendar> axis()

Returns the associated time axis.

Returns:: chronology

Class JapaneseCalendar

Introduction

Following elements which are declared as constants are registered by this class

Example of usage

Support for unicode ca-extensions

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class net.time4j.engine.Calendrical

Methods inherited from class net.time4j.engine.TimePoint

Methods inherited from class net.time4j.engine.ChronoEntity

Methods inherited from class java.lang.Object

Methods inherited from interface net.time4j.format.LocalizedPatternSupport

Methods inherited from interface net.time4j.engine.CalendarDate

Methods inherited from interface net.time4j.engine.Temporal

Field Detail

ERA

YEAR_OF_ERA

KOKI_YEAR

MONTH_OF_YEAR

MONTH_AS_ORDINAL

DAY_OF_MONTH

DAY_OF_YEAR

DAY_OF_WEEK

WEEKDAY_IN_MONTH

Method Detail

ofGregorian

of

of

nowInSystemTime

getEra

getYear

getMonth

getDayOfMonth

getDayOfWeek

getDayOfYear

lengthOfMonth

lengthOfYear

isLeapYear

at

atTime

compareTo

equals

hashCode

toString

getDefaultWeekmodel

axis