Interface DateSequence

  • All Superinterfaces:
    Named

    public interface DateSequence
    extends Named
    A series of dates identified by name.

    This interface encapsulates a sequence of dates as used in standard financial instruments. The most common are the quarterly IMM dates, which are on the third Wednesday of March, June, September and December.

    The most common implementations are provided in DateSequences.

    Note that the dates produced by the sequence may not be business days. The application of a holiday calendar is typically the responsibility of the caller.

    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 dateMatching​(java.time.YearMonth yearMonth)
      Finds the date in the sequence that corresponds to the specified year-month.
      static ExtendedEnum<DateSequence> extendedEnum()
      Gets the extended enum helper.
      java.lang.String getName()
      Gets the name that uniquely identifies this sequence.
      default java.time.LocalDate next​(java.time.LocalDate date)
      Finds the next date in the sequence, always returning a date later than the input date.
      java.time.LocalDate nextOrSame​(java.time.LocalDate date)
      Finds the next date in the sequence, returning the input date if it is a date in the sequence.
      default java.time.LocalDate nth​(java.time.LocalDate date, int sequenceNumber)
      Finds the nth date in the sequence after the input date, always returning a date later than the input date.
      default java.time.LocalDate nthOrSame​(java.time.LocalDate date, int sequenceNumber)
      Finds the nth date in the sequence on or after the input date, returning the input date if it is a date in the sequence.
      static DateSequence of​(java.lang.String uniqueName)
      Obtains an instance from the specified unique name.
    • Method Detail

      • of

        static DateSequence of​(java.lang.String uniqueName)
        Obtains an instance from the specified unique name.
        Parameters:
        uniqueName - the unique name
        Returns:
        the date sequence
        Throws:
        java.lang.IllegalArgumentException - if the name is not known
      • extendedEnum

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

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

        Returns:
        the extended enum helper
      • next

        default java.time.LocalDate next​(java.time.LocalDate date)
        Finds the next date in the sequence, always returning a date later than the input date.

        Given an input date, this method returns the next date after it from the sequence.

        Parameters:
        date - the input date
        Returns:
        the next sequence date after the input date
        Throws:
        java.lang.IllegalArgumentException - if there are no more sequence dates
      • nextOrSame

        java.time.LocalDate nextOrSame​(java.time.LocalDate date)
        Finds the next date in the sequence, returning the input date if it is a date in the sequence.

        Given an input date, this method returns a date from the sequence. If the input date is in the sequence, it is returned. Otherwise, the next date in the sequence after the input date is returned.

        Parameters:
        date - the input date
        Returns:
        the input date if it is a sequence date, otherwise the next sequence date
        Throws:
        java.lang.IllegalArgumentException - if there are no more sequence dates
      • nth

        default java.time.LocalDate nth​(java.time.LocalDate date,
                                        int sequenceNumber)
        Finds the nth date in the sequence after the input date, always returning a date later than the input date.

        Given an input date, this method returns a date from the sequence. If the sequence number is 1, then the first date in the sequence after the input date is returned.

        If the sequence number is 2 or larger, then the date referred to by sequence number 1 is calculated, and the nth matching sequence date after that date returned.

        Parameters:
        date - the input date
        sequenceNumber - the 1-based index of the date to find
        Returns:
        the nth sequence date after the input date
        Throws:
        java.lang.IllegalArgumentException - if the sequence number is zero or negative or if there are no more sequence dates
      • nthOrSame

        default java.time.LocalDate nthOrSame​(java.time.LocalDate date,
                                              int sequenceNumber)
        Finds the nth date in the sequence on or after the input date, returning the input date if it is a date in the sequence.

        Given an input date, this method returns a date from the sequence. If the sequence number is 1, then either the input date or the first date in the sequence after the input date is returned.

        If the sequence number is 2 or larger, then the date referred to by sequence number 1 is calculated, and the nth matching sequence date after that date returned.

        Parameters:
        date - the input date
        sequenceNumber - the 1-based index of the date to find
        Returns:
        the nth sequence date on or after the input date
        Throws:
        java.lang.IllegalArgumentException - if the sequence number is zero or negative or if there are no more sequence dates
      • dateMatching

        java.time.LocalDate dateMatching​(java.time.YearMonth yearMonth)
        Finds the date in the sequence that corresponds to the specified year-month.

        Given an input month, this method returns the date from the sequence that is associated with the year-month. In most cases, the returned date will be in the same month as the input month, but this is not guaranteed.

        Parameters:
        yearMonth - the input year-month
        Returns:
        the next sequence date after the input date
        Throws:
        java.lang.IllegalArgumentException - if there are no more sequence dates
      • getName

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

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

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