Package net.time4j.calendar

Class JapaneseCalendar

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("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

  • Field Details

  • Method Details

    • 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-08Heisei-1-01-08Heisei-1-01-08Heisei-1-01-08
      Heisei-1-01-07{exception}Shōwa-64-01-07Heisei-1-01-07
      Shōwa-64-01-08{exception}Heisei-1-01-08Shōwa-64-01-08
      Shōwa-64-01-07Shōwa-64-01-07Shōwa-64-01-07Shō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