public final class PeriodicSchedule extends Object implements org.joda.beans.ImmutableBean, Serializable
A periodic schedule is determined using a "periodic frequency". This splits the schedule into "regular" periods of a fixed length, such as every 3 months. Any remaining days are allocated to irregular "stubs" at the start and/or end.
For example, a 24 month (2 year) swap might be divided into 3 month periods. The 24 month period is the overall schedule and the 3 month period is the periodic frequency.
Note that a 23 month swap cannot be split into even 3 month periods. Instead, there will be a 2 month "initial" stub at the start, a 2 month "final" stub at the end or both an initial and final stub with a combined length of 2 months.
This example creates a schedule for a 13 month swap cannot be split into 3 month periods with a long initial stub rolling at end-of-month:
// example swap using builder
BusinessDayAdjustment businessDayAdj =
BusinessDayAdjustment.of(BusinessDayConventions.MODIFIED_FOLLOWING, GlobalHolidayCalendars.EUTA);
PeriodicSchedule definition = PeriodicSchedule.builder()
.startDate(LocalDate.of(2014, 2, 12))
.endDate(LocalDate.of(2015, 3, 31))
.businessDayAdjustment(businessDayAdj)
.frequency(Frequency.P3M)
.stubConvention(StubConvention.LONG_INITIAL)
.rollConvention(RollConventions.EOM)
.build();
Schedule schedule = definition.createSchedule();
// result
period 1: 2014-02-12 to 2014-06-30
period 2: 2014-06-30 to 2014-09-30
period 3: 2014-09-30 to 2014-12-31
period 4: 2014-12-31 to 2015-03-31
The stubs are specified using a combination of the StubConvention, RollConvention and dates.
The explicit stub dates are checked first. An explicit stub occurs if 'firstRegularStartDate' or 'lastRegularEndDate' is present and they differ from 'startDate' and 'endDate'.
If explicit stub dates are specified then they are used to lock the initial or final stub. If the stub convention is present, it is matched and validated against the locked stub. For example, if an initial stub is specified by dates and the stub convention is 'ShortInitial', 'LongInitial' or 'SmartInitial' then the convention is considered to be matched, thus the periodic frequency is applied using the implicit stub convention 'None'. If the stub convention does not match the dates, then an exception will be thrown during schedule creation. If the stub convention is not present, then the periodic frequency is applied using the implicit stub convention 'None'.
If explicit stub dates are not specified then the stub convention is used. The convention selects whether to use the start date or the end date as the beginning of the schedule calculation. The beginning of the calculation must match the roll convention, unless the convention is 'EOM', in which case 'EOM' is only applied if the calculation starts at the end of the month.
In all cases, the roll convention is used to fine-tune the dates. If not present or 'None', the convention is effectively implied from the first date of the calculation. All calculated dates will match the roll convention. If this is not possible due to the dates specified then an exception will be thrown during schedule creation.
It is permitted to have 'firstRegularStartDate' equal to 'endDate', or 'lastRegularEndDate' equal to 'startDate'. In both cases, the effect is to define a schedule that is entirely "stub" and has no regular periods. The resulting schedule will retain the frequency specified here, even though it is not used.
The schedule operates primarily on "unadjusted" dates. An unadjusted date can be any day, including non-business days. When the unadjusted schedule has been determined, the appropriate business day adjustment is applied to create a parallel schedule of "adjusted" dates.
| Modifier and Type | Class and Description |
|---|---|
static class |
PeriodicSchedule.Builder
The bean-builder for
PeriodicSchedule. |
static class |
PeriodicSchedule.Meta
The meta-bean for
PeriodicSchedule. |
| Modifier and Type | Method and Description |
|---|---|
static PeriodicSchedule.Builder |
builder()
Returns a builder used to create an instance of the bean.
|
AdjustableDate |
calculatedEndDate()
Calculates the applicable end date.
|
LocalDate |
calculatedFirstRegularStartDate()
Calculates the applicable first regular start date.
|
LocalDate |
calculatedLastRegularEndDate()
Calculates the applicable last regular end date.
|
RollConvention |
calculatedRollConvention()
Gets the applicable roll convention defining how to roll dates.
|
AdjustableDate |
calculatedStartDate()
Calculates the applicable start date.
|
ImmutableList<LocalDate> |
createAdjustedDates(ReferenceData refData)
Creates the list of adjusted dates in the schedule.
|
Schedule |
createSchedule(ReferenceData refData)
Creates the schedule from the definition, see
createSchedule(ReferenceData, boolean). |
Schedule |
createSchedule(ReferenceData refData,
boolean combinePeriodsIfNecessary)
Creates the schedule from the definition.
|
ImmutableList<LocalDate> |
createUnadjustedDates()
Creates the list of unadjusted dates in the schedule.
|
ImmutableList<LocalDate> |
createUnadjustedDates(ReferenceData refData)
Creates the list of unadjusted dates in the schedule.
|
boolean |
equals(Object obj) |
BusinessDayAdjustment |
getBusinessDayAdjustment()
Gets the business day adjustment to apply.
|
LocalDate |
getEndDate()
Gets the end date, which is the end of the last schedule period.
|
Optional<BusinessDayAdjustment> |
getEndDateBusinessDayAdjustment()
Gets the optional business day adjustment to apply to the end date.
|
Optional<LocalDate> |
getFirstRegularStartDate()
Gets the optional start date of the first regular schedule period, which is the end date of the initial stub.
|
Frequency |
getFrequency()
Gets the regular periodic frequency to use.
|
Optional<LocalDate> |
getLastRegularEndDate()
Gets the optional end date of the last regular schedule period, which is the start date of the final stub.
|
Optional<AdjustableDate> |
getOverrideStartDate()
Gets the optional start date of the first schedule period, overriding normal schedule generation.
|
Optional<RollConvention> |
getRollConvention()
Gets the optional convention defining how to roll dates.
|
LocalDate |
getStartDate()
Gets the start date, which is the start of the first schedule period.
|
Optional<BusinessDayAdjustment> |
getStartDateBusinessDayAdjustment()
Gets the optional business day adjustment to apply to the start date.
|
Optional<StubConvention> |
getStubConvention()
Gets the optional convention defining how to handle stubs.
|
int |
hashCode() |
static PeriodicSchedule.Meta |
meta()
The meta-bean for
PeriodicSchedule. |
PeriodicSchedule.Meta |
metaBean() |
static PeriodicSchedule |
of(LocalDate unadjustedStartDate,
LocalDate unadjustedEndDate,
Frequency frequency,
BusinessDayAdjustment businessDayAdjustment,
StubConvention stubConvention,
boolean preferEndOfMonth)
Obtains an instance based on a stub convention and end-of-month flag.
|
static PeriodicSchedule |
of(LocalDate unadjustedStartDate,
LocalDate unadjustedEndDate,
Frequency frequency,
BusinessDayAdjustment businessDayAdjustment,
StubConvention stubConvention,
RollConvention rollConvention)
Obtains an instance based on roll and stub conventions.
|
PeriodicSchedule |
replaceStartDate(LocalDate adjustedStartDate)
Returns an instance based on this schedule with the start date replaced.
|
PeriodicSchedule.Builder |
toBuilder()
Returns a builder that allows this bean to be mutated.
|
String |
toString() |
public static PeriodicSchedule of(LocalDate unadjustedStartDate, LocalDate unadjustedEndDate, Frequency frequency, BusinessDayAdjustment businessDayAdjustment, StubConvention stubConvention, boolean preferEndOfMonth)
The business day adjustment is used for all dates. The stub convention is used to determine whether there are any stubs. If the end-of-month flag is true, then in any case of ambiguity the end-of-month will be chosen.
unadjustedStartDate - start date, which is the start of the first schedule periodunadjustedEndDate - the end date, which is the end of the last schedule periodfrequency - the regular periodic frequencybusinessDayAdjustment - the business day adjustment to applystubConvention - the non-null convention defining how to handle stubspreferEndOfMonth - whether to prefer the end-of-month when rollingpublic static PeriodicSchedule of(LocalDate unadjustedStartDate, LocalDate unadjustedEndDate, Frequency frequency, BusinessDayAdjustment businessDayAdjustment, StubConvention stubConvention, RollConvention rollConvention)
The business day adjustment is used for all dates. The stub convention is used to determine whether there are any stubs. The roll convention is used to fine tune each rolled date.
unadjustedStartDate - start date, which is the start of the first schedule periodunadjustedEndDate - the end date, which is the end of the last schedule periodfrequency - the regular periodic frequencybusinessDayAdjustment - the business day adjustment to applystubConvention - the non-null convention defining how to handle stubsrollConvention - the non-null convention defining how to roll datespublic Schedule createSchedule(ReferenceData refData)
createSchedule(ReferenceData, boolean).refData - the reference data, used to find the holiday calendarsScheduleException - if the definition is invalidpublic Schedule createSchedule(ReferenceData refData, boolean combinePeriodsIfNecessary)
The schedule consists of an optional initial stub, a number of regular periods and an optional final stub.
The roll convention, stub convention and additional dates are all used to determine the schedule. If the roll convention is not present it will be defaulted from the stub convention, with 'None' as the default. If there are explicit stub dates then they will be used. If the stub convention is present, then it will be validated against the stub dates. If the stub convention and stub dates are not present, then no stubs are allowed.
There is special handling for pre-adjusted start dates to avoid creating incorrect stubs. If all the following conditions hold true, then the unadjusted start date is treated as being the day-of-month implied by the roll convention (the adjusted date is unaffected).
startDateBusinessDayAdjustment property equals BusinessDayAdjustment.NONE
or the roll convention is 'EOM'
businessDayAdjustment to the day-of-month implied by the roll convention
yields the specified start date
There is additional special handling for pre-adjusted first/last regular dates and the end date. If the following conditions hold true, then the unadjusted date is treated as being the day-of-month implied by the roll convention (the adjusted date is unaffected).
businessDayAdjustment to the day-of-month implied by the roll convention
yields the first/last regular date that was specified
refData - the reference data, used to find the holiday calendarscombinePeriodsIfNecessary - determines whether periods should be combined if necessaryScheduleException - if the definition is invalidpublic ImmutableList<LocalDate> createUnadjustedDates()
The unadjusted date list will contain at least two elements, the start date and end date. Between those dates will be the calculated periodic schedule.
The roll convention, stub convention and additional dates are all used to determine the schedule. If the roll convention is not present it will be defaulted from the stub convention, with 'None' as the default. If there are explicit stub dates then they will be used. If the stub convention is present, then it will be validated against the stub dates. If the stub convention and stub dates are not present, then no stubs are allowed. If the frequency is 'Term' explicit stub dates are disallowed, and the roll and stub convention are ignored.
The special handling for last business day of month seen in
createUnadjustedDates(ReferenceData) is not applied.
ScheduleException - if the definition is invalidpublic ImmutableList<LocalDate> createUnadjustedDates(ReferenceData refData)
The unadjusted date list will contain at least two elements, the start date and end date. Between those dates will be the calculated periodic schedule.
The roll convention, stub convention and additional dates are all used to determine the schedule. If the roll convention is not present it will be defaulted from the stub convention, with 'None' as the default. If there are explicit stub dates then they will be used. If the stub convention is present, then it will be validated against the stub dates. If the stub convention and stub dates are not present, then no stubs are allowed. If the frequency is 'Term' explicit stub dates are disallowed, and the roll and stub convention are ignored.
There is special handling for pre-adjusted start dates to avoid creating incorrect stubs. If all the following conditions hold true, then the unadjusted start date is treated as being the day-of-month implied by the roll convention (the adjusted date is unaffected).
startDateBusinessDayAdjustment property equals BusinessDayAdjustment.NONE
or the roll convention is 'EOM'
businessDayAdjustment to the day-of-month implied by the roll convention
yields the specified start date
There is additional special handling for pre-adjusted first/last regular dates and the end date. If the following conditions hold true, then the unadjusted date is treated as being the day-of-month implied by the roll convention (the adjusted date is unaffected).
businessDayAdjustment to the day-of-month implied by the roll convention
yields the first/last regular date that was specified
refData - the reference data, used to find the holiday calendarsScheduleException - if the definition is invalidpublic ImmutableList<LocalDate> createAdjustedDates(ReferenceData refData)
The adjusted date list will contain at least two elements, the start date and end date. Between those dates will be the calculated periodic schedule. Each date will be a valid business day as per the appropriate business day adjustment.
The roll convention, stub convention and additional dates are all used to determine the schedule. If the roll convention is not present it will be defaulted from the stub convention, with 'None' as the default. If there are explicit stub dates then they will be used. If the stub convention is present, then it will be validated against the stub dates. If the stub convention and stub dates are not present, then no stubs are allowed.
There is special handling for pre-adjusted start dates to avoid creating incorrect stubs. If all the following conditions hold true, then the unadjusted start date is treated as being the day-of-month implied by the roll convention (the adjusted date is unaffected).
startDateBusinessDayAdjustment property equals BusinessDayAdjustment.NONE
or the roll convention is 'EOM'
businessDayAdjustment to the day-of-month implied by the roll convention
yields the specified start date
There is additional special handling for pre-adjusted first/last regular dates and the end date. If the following conditions hold true, then the unadjusted date is treated as being the day-of-month implied by the roll convention (the adjusted date is unaffected).
businessDayAdjustment to the day-of-month implied by the roll convention
yields the first/last regular date that was specified
refData - the reference data, used to find the holiday calendarScheduleException - if the definition is invalidpublic RollConvention calculatedRollConvention()
The schedule periods are determined at the high level by repeatedly adding the frequency to the start date, or subtracting it from the end date. The roll convention provides the detailed rule to adjust the day-of-month or day-of-week.
The applicable roll convention is a non-null value. If the roll convention property is not present, this is determined from the stub convention, dates and frequency, defaulting to 'None' if necessary.
public LocalDate calculatedFirstRegularStartDate()
This will be either 'firstRegularStartDate' or 'startDate'.
public LocalDate calculatedLastRegularEndDate()
This will be either 'lastRegularEndDate' or 'endDate'.
public AdjustableDate calculatedStartDate()
The result combines the start date and the appropriate business day adjustment. If the override start date is present, it will be returned.
public AdjustableDate calculatedEndDate()
The result combines the end date and the appropriate business day adjustment.
public PeriodicSchedule replaceStartDate(LocalDate adjustedStartDate)
This returns a new instance with the schedule altered to have the specified start date.
The specified date is considered to be adjusted, thus startDateBusinessDayAdjustment is set to 'None'.
The firstRegularStartDate and overrideStartDate fields are also removed.
The stub convention is typically altered to be 'SmartInitial'.
The algorithm retains the 'ShortInitial' and 'LongInitial' conventions as is.
The algorithm examines "Final" conventions to try and set the lastRegularEndDate
via schedule generation allowing the stub convention to become 'SmartInitial'.
adjustedStartDate - the proposed start date, which is considered to be adjustedIllegalArgumentException - if the schedule start date cannot be replaced with the proposed start datepublic static PeriodicSchedule.Meta meta()
PeriodicSchedule.public static PeriodicSchedule.Builder builder()
public PeriodicSchedule.Meta metaBean()
metaBean in interface org.joda.beans.Beanpublic LocalDate getStartDate()
This is the start date of the schedule, it is unadjusted and as such might be a weekend or holiday. Any applicable business day adjustment will be applied when creating the schedule. This is also known as the unadjusted effective date.
In most cases, the start date of a financial instrument is just after the trade date, such as two business days later. However, the start date of a schedule is permitted to be any date, which includes dates before or after the trade date.
public LocalDate getEndDate()
This is the end date of the schedule, it is unadjusted and as such might be a weekend or holiday. Any applicable business day adjustment will be applied when creating the schedule. This is also known as the unadjusted maturity date or unadjusted termination date. This date must be after the start date.
public Frequency getFrequency()
Most dates are calculated using a regular periodic frequency, such as every 3 months. The actual day-of-month or day-of-week is selected using the roll and stub conventions.
public BusinessDayAdjustment getBusinessDayAdjustment()
Each date in the calculated schedule is determined without taking into account weekends and holidays. The adjustment specified here is used to convert those dates to valid business days.
The start date and end date may have their own business day adjustment rules. If those are not present, then this adjustment is used instead.
public Optional<BusinessDayAdjustment> getStartDateBusinessDayAdjustment()
The start date property is an unadjusted date and as such might be a weekend or holiday. The adjustment specified here is used to convert the start date to a valid business day.
If this property is not present, the standard businessDayAdjustment property is used instead.
public Optional<BusinessDayAdjustment> getEndDateBusinessDayAdjustment()
The end date property is an unadjusted date and as such might be a weekend or holiday. The adjustment specified here is used to convert the end date to a valid business day.
If this property is not present, the standard businessDayAdjustment property is used instead.
public Optional<StubConvention> getStubConvention()
The stub convention is used during schedule construction to determine whether the irregular
remaining period occurs at the start or end of the schedule.
It also determines whether the irregular period is shorter or longer than the regular period.
This property interacts with the "explicit dates" of getFirstRegularStartDate()
and getLastRegularEndDate().
The convention 'None' may be used to explicitly indicate there are no stubs. There must be no explicit dates. This will be validated during schedule construction.
The convention 'Both' may be used to explicitly indicate there is both an initial and final stub. The stubs themselves must be specified using explicit dates. This will be validated during schedule construction.
The conventions 'ShortInitial', 'LongInitial', 'SmartInitial', 'ShortFinal', 'LongFinal' and 'SmartFinal' are used to indicate the type of stub to be generated. The exact behavior varies depending on whether there are explicit dates or not:
If explicit dates are specified, then the combination of stub convention an explicit date will be validated during schedule construction. For example, the combination of an explicit dated initial stub and a stub convention of 'ShortInitial', 'LongInitial' or 'SmartInitial' is valid, but other stub conventions, such as 'ShortFinal' or 'None' would be invalid.
If explicit dates are not specified, then it is not required that a stub is generated. The convention determines whether to generate dates from the start date forward, or the end date backwards. Date generation may or may not result in a stub, but if it does then the stub will be of the correct type.
When the stub convention is not present, the generation of stubs is based on the presence or absence of the explicit dates. When there are no explicit stubs and there is a roll convention that matches the start or end date, then the stub convention will be defaulted to 'SmartInitial' or 'SmartFinal'.
public Optional<RollConvention> getRollConvention()
The schedule periods are determined at the high level by repeatedly adding the frequency to the start date, or subtracting it from the end date. The roll convention provides the detailed rule to adjust the day-of-month or day-of-week.
During schedule generation, if this is present it will be used to determine the schedule. If not present, then the roll convention will be implied.
public Optional<LocalDate> getFirstRegularStartDate()
This is used to identify the boundary date between the initial stub and the first regular schedule period.
This is an unadjusted date, and as such it might not be a valid business day. This date must be on or after 'startDate' and on or before 'endDate'.
During schedule generation, if this is present it will be used to determine the schedule. If not present, then the overall schedule start date will be used instead, resulting in no initial stub.
public Optional<LocalDate> getLastRegularEndDate()
This is used to identify the boundary date between the last regular schedule period and the final stub.
This is an unadjusted date, and as such it might not be a valid business day. This date must be one or after 'startDate', on or after 'firstRegularStartDate' and on or before 'endDate'.
During schedule generation, if this is present it will be used to determine the schedule. If not present, then the overall schedule end date will be used instead, resulting in no final stub.
public Optional<AdjustableDate> getOverrideStartDate()
This property is rarely used, and is generally needed when accrual starts before the effective date. If specified, it overrides the start date of the first period once schedule generation has been completed. Note that all schedule generation rules apply to 'startDate', with this applied as a final step. This field primarily exists to support the FpML 'firstPeriodStartDate' concept.
If a roll convention is explicitly specified and the regular start date does not match it, then the override will be used when generating regular periods.
If set, it should be different to the start date, although this is not validated. Validation does check that it is on or before 'firstRegularStartDate' and 'lastRegularEndDate', and before 'endDate'.
During schedule generation, if this is present it will be used to override the start date of the first generated schedule period. If not present, then the start of the first period will be the normal start date.
public PeriodicSchedule.Builder toBuilder()
Copyright 2009-Present by OpenGamma Inc. and individual contributors
Apache v2 licensed
Additional documentation can be found at strata.opengamma.io.