Class Schedule

  • All Implemented Interfaces:
    DayCount.ScheduleInfo, java.io.Serializable, Bean, ImmutableBean

    public final class Schedule
    extends java.lang.Object
    implements DayCount.ScheduleInfo, ImmutableBean, java.io.Serializable
    A complete schedule of periods (date ranges), with both unadjusted and adjusted dates.

    The schedule consists of one or more adjacent periods (date ranges). This is typically used as the basis for financial calculations, such as accrual of interest.

    It is recommended to create a Schedule using a PeriodicSchedule.

    See Also:
    Serialized Form
    • Method Detail

      • ofTerm

        public static Schedule ofTerm​(SchedulePeriod period)
        Obtains a 'Term' instance based on a single period.

        A 'Term' schedule has one period with a frequency of 'Term'.

        Parameters:
        period - the single period
        Returns:
        the merged 'Term' schedule
      • size

        public int size()
        Gets the number of periods in the schedule.

        This returns the number of periods, which will be at least one.

        Returns:
        the number of periods
      • isTerm

        public boolean isTerm()
        Checks if this schedule represents a single 'Term' period.

        A 'Term' schedule has one period and a frequency of 'Term'.

        Returns:
        true if this is a 'Term' schedule
      • isSinglePeriod

        public boolean isSinglePeriod()
        Checks if this schedule has a single period.
        Returns:
        true if this is a single period
      • getPeriod

        public SchedulePeriod getPeriod​(int index)
        Gets a schedule period by index.

        This returns a period using a zero-based index.

        Parameters:
        index - the zero-based period index
        Returns:
        the schedule period
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is invalid
      • getFirstPeriod

        public SchedulePeriod getFirstPeriod()
        Gets the first schedule period.
        Returns:
        the first schedule period
      • getLastPeriod

        public SchedulePeriod getLastPeriod()
        Gets the last schedule period.
        Returns:
        the last schedule period
      • getStartDate

        public java.time.LocalDate getStartDate()
        Gets the start date of the schedule.

        The first date in the schedule, typically treated as inclusive. If the schedule adjusts for business days, then this is the adjusted date.

        Specified by:
        getStartDate in interface DayCount.ScheduleInfo
        Returns:
        the schedule start date
      • getEndDate

        public java.time.LocalDate getEndDate()
        Gets the end date of the schedule.

        The last date in the schedule, typically treated as exclusive. If the schedule adjusts for business days, then this is the adjusted date.

        Specified by:
        getEndDate in interface DayCount.ScheduleInfo
        Returns:
        the schedule end date
      • getUnadjustedStartDate

        public java.time.LocalDate getUnadjustedStartDate()
        Gets the unadjusted start date.

        The start date before any business day adjustment.

        Returns:
        the unadjusted schedule start date
      • getUnadjustedEndDate

        public java.time.LocalDate getUnadjustedEndDate()
        Gets the unadjusted end date.

        The end date before any business day adjustment.

        Returns:
        the unadjusted schedule end date
      • getInitialStub

        public java.util.Optional<SchedulePeriod> getInitialStub()
        Gets the initial stub if it exists.

        There is an initial stub if the first period is a stub and the frequency is not 'Term'.

        A period will be allocated to one and only one of getInitialStub(), getRegularPeriods() and getFinalStub().

        Returns:
        the initial stub, empty if no initial stub
      • getFinalStub

        public java.util.Optional<SchedulePeriod> getFinalStub()
        Gets the final stub if it exists.

        There is a final stub if there is more than one period and the last period is a stub.

        A period will be allocated to one and only one of getInitialStub(), getRegularPeriods() and getFinalStub().

        Returns:
        the final stub, empty if no final stub
      • getRegularPeriods

        public com.google.common.collect.ImmutableList<SchedulePeriod> getRegularPeriods()
        Gets the regular schedule periods.

        The regular periods exclude any initial or final stub. In most cases, the periods returned will be regular, corresponding to the periodic frequency and roll convention, however there are cases when this is not true. This includes the case where isTerm() returns true. See SchedulePeriod.isRegular(Frequency, RollConvention).

        A period will be allocated to one and only one of getInitialStub(), getRegularPeriods() and getFinalStub().

        Returns:
        the non-stub schedule periods
      • getUnadjustedDates

        public com.google.common.collect.ImmutableList<java.time.LocalDate> getUnadjustedDates()
        Gets the complete list of unadjusted dates.

        This returns a list including all the unadjusted period boundary dates. This is the same as a list containing the unadjusted start date of the schedule followed by the unadjusted end date of each period.

        Returns:
        the list of unadjusted dates, in order
      • isEndOfMonthConvention

        public boolean isEndOfMonthConvention()
        Checks if the end of month convention is in use.

        If true then when building a schedule, dates will be at the end-of-month if the first date in the series is at the end-of-month.

        Specified by:
        isEndOfMonthConvention in interface DayCount.ScheduleInfo
        Returns:
        true if the end of month convention is in use
      • getPeriodEndDate

        public java.time.LocalDate getPeriodEndDate​(java.time.LocalDate date)
        Finds the period end date given a date in the period.

        The first matching period is returned. The adjusted start and end dates of each period are used in the comparison. The start date is included, the end date is excluded.

        Specified by:
        getPeriodEndDate in interface DayCount.ScheduleInfo
        Parameters:
        date - the date to find
        Returns:
        the end date of the period that includes the specified date
      • mergeToTerm

        public Schedule mergeToTerm()
        Merges this schedule to form a new schedule with a single 'Term' period.

        The result will have one period of type 'Term', with dates matching this schedule.

        Returns:
        the merged 'Term' schedule
      • merge

        public Schedule merge​(int groupSize,
                              java.time.LocalDate firstRegularStartDate,
                              java.time.LocalDate lastRegularEndDate)
        Merges this schedule to form a new schedule by combining the schedule periods.

        This produces a schedule where some periods are merged together. For example, this could be used to convert a 3 monthly schedule into a 6 monthly schedule.

        The merging is controlled by the group size, which defines the number of periods to merge together in the result. For example, to convert a 3 monthly schedule into a 6 monthly schedule the group size would be 2 (6 divided by 3).

        A group size of zero or less will throw an exception. A group size of 1 will return this schedule providing that the specified start and end date match. A larger group size will return a schedule where each group of regular periods are merged.

        The specified dates must be one of the dates of this schedule (unadjusted or adjusted). All periods of this schedule before the first regular start date, if any, will form a single period in the result. All periods of this schedule after the last regular start date, if any, will form a single period in the result. If this schedule has an initial or final stub, it may be merged with a regular period as part of the process.

        For example, a schedule with an initial stub and 5 regular periods can be grouped by 2 if the specified firstRegularStartDate equals the end of the first regular period.

        Parameters:
        groupSize - the group size
        firstRegularStartDate - the unadjusted start date of the first regular payment period
        lastRegularEndDate - the unadjusted end date of the last regular payment period
        Returns:
        the merged schedule
        Throws:
        java.lang.IllegalArgumentException - if the group size is zero or less
        ScheduleException - if the merged schedule cannot be created because the dates don't match this schedule or the regular periods don't match the grouping size
      • mergeRegular

        public Schedule mergeRegular​(int groupSize,
                                     boolean rollForwards)
        Merges this schedule to form a new schedule by combining the regular schedule periods.

        This produces a schedule where some periods are merged together. For example, this could be used to convert a 3 monthly schedule into a 6 monthly schedule.

        The merging is controlled by the group size, which defines the number of periods to merge together in the result. For example, to convert a 3 monthly schedule into a 6 monthly schedule the group size would be 2 (6 divided by 3).

        A group size of zero or less will throw an exception. A group size of 1 will return this schedule. A larger group size will return a schedule where each group of regular periods are merged. The roll flag is used to determine the direction in which grouping occurs.

        Any existing stub periods are considered to be special, and are not merged. Even if the grouping results in an excess period, such as 10 periods with a group size of 3, the excess period will not be merged with a stub.

        If this period is a 'Term' period, this schedule is returned.

        Parameters:
        groupSize - the group size
        rollForwards - whether to roll forwards (true) or backwards (false)
        Returns:
        the merged schedule
        Throws:
        java.lang.IllegalArgumentException - if the group size is zero or less
      • toAdjusted

        public Schedule toAdjusted​(DateAdjuster adjuster)
        Converts this schedule to a schedule where all the start and end dates are adjusted using the specified adjuster.

        The result will have the same number of periods, but each start date and end date is replaced by the adjusted date as returned by the adjuster. The unadjusted start date and unadjusted end date of each period will not be changed.

        Parameters:
        adjuster - the adjuster to use
        Returns:
        the adjusted schedule
      • toUnadjusted

        public Schedule toUnadjusted()
        Converts this schedule to a schedule where every adjusted date is reset to the unadjusted equivalent.

        The result will have the same number of periods, but each start date and end date is replaced by the matching unadjusted start or end date.

        Returns:
        the equivalent unadjusted schedule
      • meta

        public static Schedule.Meta meta()
        The meta-bean for Schedule.
        Returns:
        the meta-bean, not null
      • builder

        public static Schedule.Builder builder()
        Returns a builder used to create an instance of the bean.
        Returns:
        the builder, not null
      • getPeriods

        public com.google.common.collect.ImmutableList<SchedulePeriod> getPeriods()
        Gets the schedule periods.

        There will be at least one period. The periods are ordered from earliest to latest. It is intended that each period is adjacent to the next one, however each period is independent and non-adjacent periods are allowed.

        Returns:
        the value of the property, not empty
      • getFrequency

        public Frequency getFrequency()
        Gets the periodic frequency used when building the schedule.

        If the schedule was not built from a regular periodic frequency, then the frequency should be a suitable estimate.

        Specified by:
        getFrequency in interface DayCount.ScheduleInfo
        Returns:
        the value of the property, not null
      • getRollConvention

        public RollConvention getRollConvention()
        Gets the roll convention used when building the schedule.

        If the schedule was not built from a regular periodic frequency, then the convention should be 'None'.

        Returns:
        the value of the property, not null
      • toBuilder

        public Schedule.Builder toBuilder()
        Returns a builder that allows this bean to be mutated.
        Returns:
        the mutable builder, not null
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object