Package net.time4j.engine

Interface ChronoElement<V>

Type Parameters:
V - generic type of element values, usually extending the interface java.lang.Comparable (or it can be converted to any other sortable form)
All Superinterfaces:
Comparator<ChronoDisplay>
All Known Subinterfaces:
AdjustableElement<V,​T>, AdjustableTextElement<V>, CalendarDateElement, NavigableElement<V>, NumericalElement<V>, OrdinalWeekdayElement<T>, OrdinalWeekdayElement, ProportionalElement<V,​T>, StdCalendarElement<V,​T>, TextElement<V>, WallTimeElement, ZonalElement<V>
All Known Implementing Classes:
BasicElement, DisplayElement, EpochDays, FlagElement, ValidationElement
public interface ChronoElement<V> extends Comparator<ChronoDisplay>

Represents a chronological element which refers to a partial value of the whole temporal value and mainly serves for formatting purposes (as a carrier of a chronological information).

Each chronological system knows a set of elements whose values compose the total temporal value, usually the associated time coordinates on a time axis. Each element can be associated with a value of type V. Normally this value is an integer or an enum. Examples are the hour on a clock or the month of a calendar date.

The associated values are often defined as continuum without any gaps as integer within a given value range. However, there is no guarantee for such a continuum, for example daylight-saving-jumps or hebrew leap months.

Note: All implementations must be immutable and serializable.

Author:
Meno Hochschild
See Also:
ChronoEntity.get(ChronoElement)

  • Method Details

    • name

      String name()

      Returns the name which is unique within the context of a given chronology.

      The name can also serve as resource key together with the name of a chronology for a localized description.

      Returns:
      name of element, unique within a chronology

    • getType

      Class<V> getType()

      Yields the reified value type.

      Returns:
      type of associated values

    • getSymbol

      char getSymbol()

      Defines the default format symbol which is used in format patterns to refer to this element.

      In most cases the symbol should closely match the symbol-mapping as defined by the CLDR-standard of unicode-organization. Is the element not designed for formatting using patterns then this method just yields the ASCII-char "" (Codepoint 0).

      Returns:
      format symbol as char
      See Also:
      FormattableElement

    • compare

      int compare​(ChronoDisplay o1, ChronoDisplay o2)

      Applies an element-orientated sorting of any chronological entities.

      The value type V is usually a subtype of the interface Comparable so that this method will usually be based on the expression o1.get(this).compareTo(o2.get(this)). In other words, this method compares the element values of given chronological entities. It is even permitted to compare entities of different chronological types as long as the entities both support this element.

      It should be noted however that a element value comparison does often not induce any temporal (complete) order. Counter examples are the year of gregorian BC-era (reversed temporal order before Jesu birth) or the clock display of hours (12 is indeed the begin at midnight).

      Specified by:
      compare in interface Comparator<V>
      Parameters:
      o1 - the first object to be compared
      o2 - the second object to be compared
      Returns:
      a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second
      Throws:
      ChronoException - if this element is not registered in any entity and/or if no element rule exists to extract the element value

    • getDefaultMinimum

      V getDefaultMinimum()

      Returns the default minimum of this element which is not dependent on the chronological context.

      Note: This minimum does not necessarily define a minimum for all possible circumstances but only the default minimum under normal conditions such that the default minimum always exists and can be used as prototypical value. An example is the start of day which is usually midnight in ISO-8601 and can only deviate in specialized timezone context.

      Returns:
      default minimum value of element
      See Also:
      getDefaultMaximum()

    • getDefaultMaximum

      V getDefaultMaximum()

      Returns the default maximum of this element which is not dependent on the chronological context.

      Note: This maximum does not necessarily define a maximum for all possible circumstances but only the default maximum under normal conditions. An example is the second of minute whose default maximum is 59 while the largest maximum can be 60 in context of UTC-leapseconds.

      Returns:
      default maximum value of element
      See Also:
      getDefaultMinimum()

    • isDateElement

      boolean isDateElement()

      Queries if this element represents a calendar date element.

      Returns:
      boolean
      See Also:
      isTimeElement()

    • isTimeElement

      boolean isTimeElement()

      Queries if this element represents a wall time element.

      Returns:
      boolean
      See Also:
      isDateElement()

    • isLenient

      boolean isLenient()

      Queries if setting of element values is performed in a lenient way.

      Returns:
      true if lenient else false (standard)
      See Also:
      ElementRule.withValue(T, V, boolean)

    • getDisplayName

      default String getDisplayName​(Locale language)

      Obtains a localized name for display purposes if possible.

      Most elements have no localized names, but in case the i18n-module is loaded then elements like eras, years, quarters, months, weeks, day-of-month, day-of-week, am/pm, hour, minute and second do have localization support. The default implementation falls back to the technical element name.

      Note that the displayed name does not need to be unique for different elements. For example the localized names of PlainDate.MONTH_OF_YEAR and PlainDate.MONTH_AS_NUMBER are equal.

      Parameters:
      language - language setting
      Returns:
      localized name or if not available then a technical name will be chosen
      Since:
      3.22/4.18