Package com.opengamma.strata.basics.schedule

Class Schedule

  • All Implemented Interfaces:
    DayCount.ScheduleInfo, Serializable, org.joda.beans.Bean, org.joda.beans.ImmutableBean
    public final class Schedule
extends Object
implements DayCount.ScheduleInfo, org.joda.beans.ImmutableBean, 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:
        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 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 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 LocalDate getUnadjustedStartDate()
        Gets the unadjusted start date.

        The start date before any business day adjustment.

        Returns:
        the unadjusted schedule start date

      • getUnadjustedEndDate

        public LocalDate getUnadjustedEndDate()
        Gets the unadjusted end date.

        The end date before any business day adjustment.

        Returns:
        the unadjusted schedule end date

      • getStubs

        public Pair<Optional<SchedulePeriod>,​Optional<SchedulePeriod>> getStubs​(boolean preferFinal)
        Gets the stubs if they exist.

        This method returns the initial and final stub. A flag is used to handle the case where there are no regular periods and it is unclear whether the stub is initial or final.

        A period will be allocated to one and only one of getStubs(boolean) and getRegularPeriods().

        Parameters:
        preferFinal - true to prefer final if there is only one period
        Returns:
        the stubs, empty if no stub

      • getUnadjustedDates

        public ImmutableList<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 LocalDate getPeriodEndDate​(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,
                      LocalDate firstRegularStartDate,
                      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:
        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:
        IllegalArgumentException - if the group size is zero or less

      • toAdjusted

        public Schedule toAdjusted​(DateAdjuster adjuster)
        Converts this schedule to a schedule where 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.

        A special rule is applied to the first start date and the last end date. If the first period once adjusted is empty then the unadjusted start date is used instead of the adjusted one. If the last period once adjusted is empty then the unadjusted end date is used instead of the adjusted one. This rule avoids some unnecessary exceptions.

        Parameters:
        adjuster - the adjuster to use
        Returns:
        the adjusted schedule
        Throws:
        IllegalArgumentException - if a period is invalid once adjusted

      • 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

      • metaBean

        public Schedule.Meta metaBean()
        Specified by:
        metaBean in interface org.joda.beans.Bean

      • getPeriods

        public 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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object