Class DateTimeFieldRule<T>

java.lang.Object
javax.time.calendar.CalendricalRule<T>
javax.time.calendar.DateTimeFieldRule<T>
Type Parameters:
T - the underlying type representing the data, typically a Calendrical, Number or Enum, must be immutable, should be comparable
All Implemented Interfaces:
Serializable, Comparable<CalendricalRule<?>>, Comparator<Calendrical>
Direct Known Subclasses:
CopticChronology.DayOfMonthRule, CopticChronology.DayOfWeekRule, CopticChronology.DayOfYearRule, CopticChronology.MonthOfYearRule, CopticChronology.YearRule, HistoricChronology.DayOfMonthRule, HistoricChronology.DayOfWeekRule, HistoricChronology.DayOfYearRule, HistoricChronology.EraRule, HistoricChronology.MonthOfYearRule, HistoricChronology.YearRule, ISOChronology.AmPmOfDayRule, ISOChronology.DayOfWeekRule, ISOChronology.MonthOfYearRule, ISOChronology.QuarterOfYearRule, ISOChronology.Rule

public abstract class DateTimeFieldRule<T> extends CalendricalRule<T>
The rule defining how a measurable field of time operates.

Rule implementations define how a field like day-of-month operates. This includes the field name and minimum/maximum values.

DateTimeFieldRule is an abstract class and must be implemented with care to ensure other classes in the framework operate correctly. All instantiable subclasses must be final, immutable and thread-safe and must ensure serialization works correctly.

See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      A serialization identifier for this class.
      See Also:
    • FRACTION_CONTEXT

      private static final MathContext FRACTION_CONTEXT
      A Math context for calculating fractions from values.
    • VALUE_CONTEXT

      private static final MathContext VALUE_CONTEXT
      A Math context for calculating values from fractions.
    • minimumValue

      private final int minimumValue
      The minimum value for the field.
    • maximumValue

      private final int maximumValue
      The maximum value for the field.
    • textStores

      The cached text for this rule.
  • Constructor Details

    • DateTimeFieldRule

      protected DateTimeFieldRule(Class<T> reifiedClass, Chronology chronology, String name, PeriodUnit periodUnit, PeriodUnit periodRange, int minimumValue, int maximumValue)
      Constructor.
      Parameters:
      reifiedClass - the reified class, not null
      chronology - the chronology, not null
      name - the name of the type, not null
      periodUnit - the period unit, not null
      periodRange - the period range, not null
      minimumValue - the minimum value
      maximumValue - the minimum value
    • DateTimeFieldRule

      protected DateTimeFieldRule(Class<T> reifiedClass, Chronology chronology, String name, PeriodUnit periodUnit, PeriodUnit periodRange, int minimumValue, int maximumValue, boolean hasText)
      Constructor.
      Parameters:
      reifiedClass - the reified class, not null
      chronology - the chronology, not null
      name - the name of the type, not null
      periodUnit - the period unit, not null
      periodRange - the period range, not null
      minimumValue - the minimum value
      maximumValue - the minimum value
      hasText - true if this field has a text representation
  • Method Details

    • getInteger

      public final Integer getInteger(Calendrical calendrical)
      Gets the Integer value of this field from the specified calendrical returning null if the value cannot be returned.

      This uses CalendricalRule.getValue(Calendrical) to find the value and then converts it to an Integer.

      Parameters:
      calendrical - the calendrical to get the field value from, not null
      Returns:
      the value of the field, null if unable to extract the field
    • getInt

      public final int getInt(Calendrical calendrical)
      Gets the int value of this field from the specified calendrical throwing an exception if the value cannot be returned.

      This uses CalendricalRule.getValue(Calendrical) to find the value and then converts it to an int ensuring it isn't null.

      Parameters:
      calendrical - the calendrical to get the field value from, not null
      Returns:
      the value of the field, never null
      Throws:
      UnsupportedRuleException - if the field cannot be extracted
    • convertValueToInteger

      private Integer convertValueToInteger(T value)
      Converts the typed value of the rule to the Integer equivalent.

      This method avoids boxing and unboxing when the value is an Integer.

      Parameters:
      value - the value to convert, not null
      Returns:
      the int value of the field
    • convertValueToInt

      public int convertValueToInt(T value)
      Converts the typed value of the rule to the int equivalent.

      This default implementation handles Integer and Enum. When the reified type is another type, this method must be overridden.

      Parameters:
      value - the value to convert, not null
      Returns:
      the int value of the field
      Throws:
      ClassCastException - if the value cannot be converted
    • convertIntToValue

      public T convertIntToValue(int value)
      Converts the int to a typed value of the rule.

      The int will be checked to ensure that it is within the valid range of values for the field.

      This default implementation handles Integer and Enum. When the reified type is another type, this method must be overridden.

      Parameters:
      value - the value to convert, not null
      Returns:
      the int value of the field
      Throws:
      IllegalCalendarFieldValueException - if the value is invalid
      ClassCastException - if the value cannot be converted
    • isValidValue

      public boolean isValidValue(int value)
      Checks if the value is valid or invalid for this field.

      This method has no knowledge of other calendrical fields, thus only the outer minimum and maximum range for the field is validated.

      This method performs the same check as isValidValue(long).

      Parameters:
      value - the value to check
      Returns:
      true if the value is valid, false if invalid
    • isValidValue

      public boolean isValidValue(long value)
      Checks if the value is valid or invalid for this field.

      This method has no knowledge of other calendrical fields, thus only the outer minimum and maximum range for the field is validated.

      This method performs the same check as isValidValue(int).

      Parameters:
      value - the value to check
      Returns:
      true if the value is valid, false if invalid
    • checkValue

      public int checkValue(int value)
      Checks if the value is invalid and throws an exception if it is.

      This method has no knowledge of other calendrical fields, thus only the outer minimum and maximum range for the field is validated.

      This method performs the same check as checkValue(long). The implementation uses isValidValue(int).

      Parameters:
      value - the value to check
      Returns:
      the value
      Throws:
      IllegalCalendarFieldValueException - if the value is invalid
    • checkValue

      public int checkValue(long value)
      Checks if the value is invalid and throws an exception if it is.

      This method has no knowledge of other calendrical fields, thus only the outer minimum and maximum range for the field is validated.

      This method performs the same check as checkValue(int). The implementation uses isValidValue(long).

      Parameters:
      value - the value to check
      Returns:
      the value cast to an int
      Throws:
      IllegalCalendarFieldValueException - if the value is invalid
    • isFixedValueSet

      public boolean isFixedValueSet()
      Is the set of values, from the minimum value to the maximum, a fixed set, or does it vary according to other fields.
      Returns:
      true if the set of values is fixed
    • getMinimumValue

      public int getMinimumValue()
      Gets the minimum value that the field can take.
      Returns:
      the minimum value for this field
    • getLargestMinimumValue

      public int getLargestMinimumValue()
      Gets the largest possible minimum value that the field can take.

      The default implementation returns getMinimumValue(). Subclasses must override this as necessary.

      Returns:
      the largest possible minimum value for this field
    • getMinimumValue

      public int getMinimumValue(Calendrical calendrical)
      Gets the minimum value that the field can take using the specified calendrical information to refine the accuracy of the response.

      The result of this method may still be inaccurate, if there is insufficient information in the calendrical.

      The default implementation returns getMinimumValue(). Subclasses must override this as necessary.

      Parameters:
      calendrical - context calendrical, not null
      Returns:
      the minimum value of the field given the context
    • getMaximumValue

      public int getMaximumValue()
      Gets the maximum value that the field can take.
      Returns:
      the maximum value for this field
    • getSmallestMaximumValue

      public int getSmallestMaximumValue()
      Gets the smallest possible maximum value that the field can take.

      The default implementation returns getMaximumValue(). Subclasses must override this as necessary.

      Returns:
      the smallest possible maximum value for this field
    • getMaximumValue

      public int getMaximumValue(Calendrical calendrical)
      Gets the minimum value that the field can take using the specified calendrical information to refine the accuracy of the response.

      The result of this method will still be inaccurate if there is insufficient information in the calendrical.

      For example, if this field is the ISO day-of-month field, then the number of days in the month varies depending on the month and year. If both the month and year can be derived from the calendrical, then the maximum value returned will be accurate. Otherwise the 'best guess' value from getMaximumValue() will be returned.

      The default implementation returns getMaximumValue(). Subclasses must override this as necessary.

      Parameters:
      calendrical - context calendrical, not null
      Returns:
      the minimum value of the field given the context
    • getText

      public String getText(int value, Locale locale, DateTimeFormatterBuilder.TextStyle textStyle)
      Gets the text for this field.

      Some fields have a textual representation, such as day-of-week or month-of-year. This method provides a convenient way to convert a value to such a textual representation. More control is available using getTextStore(java.util.Locale, javax.time.calendar.format.DateTimeFormatterBuilder.TextStyle).

      If there is no textual mapping, then the value is returned as per Integer.toString(). Note that this is different to what occurs in printing /parsing, where a more advanced localized conversion from int to String is used.

      Parameters:
      value - the value to convert to text, not null
      locale - the locale to use, not null
      textStyle - the text style, not null
      Returns:
      the text of the field, never null
    • getTextStore

      public DateTimeFieldRule.TextStore getTextStore(Locale locale, DateTimeFormatterBuilder.TextStyle textStyle)
      Gets the text map for this field with the specified locale and style.

      Some fields have a textual representation, such as day-of-week or month-of-year. The text store provides details of those textual representations.

      To supply text, subclasses should pass true in the constructor and override createTextStores(java.util.EnumMap<javax.time.calendar.format.DateTimeFormatterBuilder.TextStyle, javax.time.calendar.DateTimeFieldRule.TextStore>, java.util.Locale). This method is not normally overridden.

      Parameters:
      locale - the locale to use, not null
      textStyle - the text style, not null
      Returns:
      the text cache, null if no text available
    • createTextStores

      protected void createTextStores(EnumMap<DateTimeFormatterBuilder.TextStyle,DateTimeFieldRule.TextStore> textStores, Locale locale)
      Creates the text store for each style for the specified locale.

      It is intended that a new copy of the text store should be created in response to calling this method as the result is cached by getTextStore(java.util.Locale, javax.time.calendar.format.DateTimeFormatterBuilder.TextStyle).

      Parameters:
      textStores - the map to populate with TextStore instances, not null
      locale - the locale to use, not null
    • convertIntToFraction

      public BigDecimal convertIntToFraction(int value)
      Converts a value for this field to a fraction between 0 and 1.

      The fractional value is between 0 (inclusive) and 1 (exclusive). It can only be returned if isFixedValueSet() returns true and the getMinimumValue() returns zero. The fraction is obtained by calculation from the field range using 9 decimal places and a rounding mode of FLOOR.

      For example, the second-of-minute value of 15 would be returned as 0.25, assuming the standard definition of 60 seconds in a minute.

      Parameters:
      value - the value to convert, valid for this field
      Returns:
      the fractional value of the field
      Throws:
      UnsupportedRuleException - if the value cannot be converted
      IllegalCalendarFieldValueException - if the value is invalid
    • convertFractionToInt

      public int convertFractionToInt(BigDecimal fraction)
      Converts a fraction from 0 to 1 for this field to a value.

      The fractional value must be between 0 (inclusive) and 1 (exclusive). It can only be returned if isFixedValueSet() returns true and the getMinimumValue() returns zero. The value is obtained by calculation from the field range and a rounding mode of FLOOR.

      For example, the fractional second-of-minute of 0.25 would be converted to 15, assuming the standard definition of 60 seconds in a minute.

      Parameters:
      fraction - the fraction to convert, not null
      Returns:
      the value of the field, checked for validity
      Throws:
      UnsupportedRuleException - if the value cannot be converted
      IllegalCalendarFieldValueException - if the value is invalid