Package net.time4j.engine

Class CalendarVariant<D extends CalendarVariant<D>>

java.lang.Object
net.time4j.engine.ChronoEntity<D>
net.time4j.engine.CalendarVariant<D>
Type Parameters:
D - generic type of self reference
All Implemented Interfaces:
Serializable, Comparable<D>, CalendarDate, ChronoDisplay, Temporal<CalendarDate>, VariantSource
Direct Known Subclasses:
HijriCalendar, HinduCalendar, HistoricCalendar
public abstract class CalendarVariant<D extends CalendarVariant<D>> extends ChronoEntity<D> implements CalendarDate, VariantSource, Comparable<D>, Serializable

Represents an immutable calendar variant.

Display and change chronological element values

The calendar variant consists of chronological elements. This base class delegates the element and time arithmetic to the associated calendar family respective to the underlying rules of elements and units. However, any concrete subclass is required to define the state and reflect it in all get()-methods and also to specify the serialization behaviour.

Element values can only be changed by creating a new immutable copy of the original instance. This is done via all with()-methods.

Calendar system

Every calendar variant is a member of a calendar family. That means referring to a calendar system via a variant name. Hence a limited day arithmetic using the class CalendarDays is always possible.

Sorting

The sorting algorithm prefers the temporal order then the lexicographical comparison based on variant names. In case of doubt the documentation of the subclass is leading. Alternatively, the interface Temporal can be used to enable a pure temporal order.

Implementation notes

  • All subclasses must be final und immutable.
  • Documentation of supported and registered elements is required.
  • The natural order should be consistent with equals().
Since:
3.4/4.3
Author:
Meno Hochschild
See Also:
Chronology, CalendarFamily

  • Constructor Details

    • CalendarVariant

      public CalendarVariant()

  • Method Details

    • withVariant

      public D withVariant​(String variant)

      Creates a copy of this instance with given variant.

      If given variant is equal to the variant of this instance then the method will just return this instance.

      Parameters:
      variant - name of new variant
      Returns:
      copy of this instance with equal epoch-day-value but different variant
      Throws:
      ChronoException - if given variant is not supported
      Since:
      3.14/4.11

    • withVariant

      public D withVariant​(VariantSource variantSource)

      Equivalent to withVariant(variantSource.getVariant()).

      Parameters:
      variantSource - source of desired calendar variant
      Returns:
      copy of this instance with equal epoch-day-value but different variant
      Throws:
      ChronoException - if given variant is not supported
      Since:
      3.14/4.11

    • compareTo

      public int compareTo​(D calendarVariant)

      Compares two calendar variants preferably by their temporal positions on the common date axis and then by their variant names.

      Implementation note: In order to make the natural order consistent with equals() the whole state must be taken into account, with preference for those attributes which define the temporal position on the time axis.

      Specified by:
      compareTo in interface Comparable<D extends CalendarVariant<D>>
      Parameters:
      calendarVariant - the object to be compared.
      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:
      equals(Object)

    • isAfter

      public boolean isAfter​(CalendarDate other)
      Description copied from interface: Temporal

      Queries if this object is after given object on a timeline.

      Specified by:
      isAfter in interface Temporal<D extends CalendarVariant<D>>
      Parameters:
      other - object this instance is compared to
      Returns:
      true if this instance is temporally after temporal else false

    • isBefore

      public boolean isBefore​(CalendarDate other)
      Description copied from interface: Temporal

      Queries if this object is before given object on a timeline.

      Specified by:
      isBefore in interface Temporal<D extends CalendarVariant<D>>
      Parameters:
      other - object this instance is compared to
      Returns:
      true if this instance is temporally before temporal else false

    • isSimultaneous

      public boolean isSimultaneous​(CalendarDate other)
      Description copied from interface: Temporal

      Queries if this object and given object have the same position on the time axis.

      Is equivalent to !isAfter(temporal) && !isBefore(temporal). This method differs from the Object-method equals() such that first the comparison type must be a temporal one and second that only temporal-only state will be considered.

      Specified by:
      isSimultaneous in interface Temporal<D extends CalendarVariant<D>>
      Parameters:
      other - object this instance is compared to
      Returns:
      true if this instance is temporally equal to temporal else false

    • plus

      public D plus​(CalendarDays days)

      Adds given calendar days to this instance.

      Parameters:
      days - calendar days to be added
      Returns:
      result of addition
      Throws:
      ArithmeticException - in case of numerical overflow
      Since:
      3.4/4.3

    • minus

      public D minus​(CalendarDays days)

      Subtracts given calendar days from this instance.

      Parameters:
      days - calendar days to be subtracted
      Returns:
      result of subtraction
      Throws:
      ArithmeticException - in case of numerical overflow
      Since:
      3.4/4.3

    • equals

      public abstract boolean equals​(Object obj)

      Compares the whole state of this instance with given object.

      Implementations will usually define their state based on the temporal position and the variant name. Exceptions from this rule should be explicitly documented and reasoned.

      Overrides:
      equals in class Object
      See Also:
      compareTo(CalendarVariant)

    • hashCode

      public abstract int hashCode()

      Subclasses must redefine this method corresponding to the behaviour of equals().

      Overrides:
      hashCode in class Object

    • toString

      public abstract String toString()

      Provides a complete textual representation of the state of this calendar variant.

      Overrides:
      toString in class Object

    • getDaysSinceEpochUTC

      public long getDaysSinceEpochUTC()
      Description copied from interface: CalendarDate

      Counts the elapsed days since UTC epoch.

      Specified by:
      getDaysSinceEpochUTC in interface CalendarDate
      Returns:
      count of days relative to UTC epoch [1972-01-01]
      See Also:
      EpochDays.UTC