Interface RollConvention

  • All Superinterfaces:
    Named

    public interface RollConvention
    extends Named
    A convention defining how to roll dates.

    A periodic schedule is determined using a periodic frequency. When applying the frequency, the roll convention is used to fine tune the dates. This might involve selecting the last day of the month, or the third Wednesday.

    To get the next date in the schedule, take the base date and the periodic frequency. Once this date is calculated, the roll convention is applied to produce the next schedule date.

    The most common implementations are provided as constants on RollConventions. Additional implementations may be added by implementing this interface.

    All implementations of this interface must be immutable and thread-safe.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      java.time.LocalDate adjust​(java.time.LocalDate date)
      Adjusts the date according to the rules of the roll convention.
      static ExtendedEnum<RollConvention> extendedEnum()
      Gets the extended enum helper.
      default int getDayOfMonth()
      Gets the day-of-month that the roll convention implies.
      java.lang.String getName()
      Gets the name that uniquely identifies this convention.
      default boolean matches​(java.time.LocalDate date)
      Checks if the date matches the rules of the roll convention.
      default java.time.LocalDate next​(java.time.LocalDate date, Frequency periodicFrequency)
      Calculates the next date in the sequence after the input date.
      static RollConvention of​(java.lang.String uniqueName)
      Obtains an instance from the specified unique name.
      static RollConvention ofDayOfMonth​(int dayOfMonth)
      Obtains an instance from the day-of-month.
      static RollConvention ofDayOfWeek​(java.time.DayOfWeek dayOfWeek)
      Obtains an instance from the day-of-week.
      default java.time.LocalDate previous​(java.time.LocalDate date, Frequency periodicFrequency)
      Calculates the previous date in the sequence after the input date.
    • Method Detail

      • of

        static RollConvention of​(java.lang.String uniqueName)
        Obtains an instance from the specified unique name.
        Parameters:
        uniqueName - the unique name
        Returns:
        the roll convention
        Throws:
        java.lang.IllegalArgumentException - if the name is not known
      • ofDayOfMonth

        static RollConvention ofDayOfMonth​(int dayOfMonth)
        Obtains an instance from the day-of-month.

        This convention will adjust the input date to the specified day-of-month. The year and month of the result date will be the same as the input date. It is intended for use with periods that are a multiple of months.

        If the month being adjusted has a length less than the requested day-of-month then the last valid day-of-month will be chosen. As such, passing 31 to this method is equivalent to selecting the end-of-month convention.

        Parameters:
        dayOfMonth - the day-of-month, from 1 to 31
        Returns:
        the roll convention
        Throws:
        java.lang.IllegalArgumentException - if the day-of-month is invalid
      • ofDayOfWeek

        static RollConvention ofDayOfWeek​(java.time.DayOfWeek dayOfWeek)
        Obtains an instance from the day-of-week.

        This convention will adjust the input date to the specified day-of-week. It is intended for use with periods that are a multiple of weeks.

        In adjust(), if the input date is not the required day-of-week, then the next occurrence of the day-of-week is selected, up to 6 days later.

        In next(), the day-of-week is selected after the frequency is added. If the calculated date is not the required day-of-week, then the next occurrence of the day-of-week is selected, up to 6 days later.

        In previous(), the day-of-week is selected after the frequency is subtracted. If the calculated date is not the required day-of-week, then the previous occurrence of the day-of-week is selected, up to 6 days earlier.

        Parameters:
        dayOfWeek - the day-of-week
        Returns:
        the roll convention
      • extendedEnum

        static ExtendedEnum<RollConvention> extendedEnum()
        Gets the extended enum helper.

        This helper allows instances of the convention to be looked up. It also provides the complete set of available instances.

        Returns:
        the extended enum helper
      • adjust

        java.time.LocalDate adjust​(java.time.LocalDate date)
        Adjusts the date according to the rules of the roll convention.

        See the description of each roll convention to understand the rule applied.

        It is recommended to use next() and previous() rather than directly using this method.

        Parameters:
        date - the date to adjust
        Returns:
        the adjusted temporal
      • matches

        default boolean matches​(java.time.LocalDate date)
        Checks if the date matches the rules of the roll convention.

        See the description of each roll convention to understand the rule applied.

        Parameters:
        date - the date to check
        Returns:
        true if the date matches this convention
      • next

        default java.time.LocalDate next​(java.time.LocalDate date,
                                         Frequency periodicFrequency)
        Calculates the next date in the sequence after the input date.

        This takes the input date, adds the periodic frequency and adjusts the date as necessary to match the roll convention rules. The result will always be after the input date.

        The default implementation is suitable for month-based conventions.

        Parameters:
        date - the date to adjust
        periodicFrequency - the periodic frequency of the schedule
        Returns:
        the adjusted date
      • previous

        default java.time.LocalDate previous​(java.time.LocalDate date,
                                             Frequency periodicFrequency)
        Calculates the previous date in the sequence after the input date.

        This takes the input date, subtracts the periodic frequency and adjusts the date as necessary to match the roll convention rules. The result will always be before the input date.

        The default implementation is suitable for month-based conventions.

        Parameters:
        date - the date to adjust
        periodicFrequency - the periodic frequency of the schedule
        Returns:
        the adjusted date
      • getDayOfMonth

        default int getDayOfMonth()
        Gets the day-of-month that the roll convention implies.

        This extracts the day-of-month for simple roll conventions. The numeric roll conventions will return their day-of-month. The 'EOM' convention will return 31. All other conventions will return zero.

        Returns:
        the day-of-month that the roll convention implies, zero if not applicable
      • getName

        java.lang.String getName()
        Gets the name that uniquely identifies this convention.

        This name is used in serialization and can be parsed using of(String).

        Specified by:
        getName in interface Named
        Returns:
        the unique name