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.

Example

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:

Details about stubs and date rolling

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'
or 'LongInitial' 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.

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.

Parameters:

unadjustedStartDate - start date, which is the start of the first schedule period

unadjustedEndDate - the end date, which is the end of the last schedule period

createSchedule

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).

applying 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).

the roll convention is numeric or 'EOM'

applying businessDayAdjustment to the day-of-month implied by the roll convention
yields the first/last regular date that was specified

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.

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.

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).

applying 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).

the roll convention is numeric or 'EOM'

applying businessDayAdjustment to the day-of-month implied by the roll convention
yields the first/last regular date that was specified

createAdjustedDates

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).

applying 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).

the roll convention is numeric or 'EOM'

applying businessDayAdjustment to the day-of-month implied by the roll convention
yields the first/last regular date that was specified

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.

metaBean

getStartDate

This is the start date of the schedule.
It is 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.

Returns:

the value of the property, not null

getEndDate

This is the end date of the schedule.
It is 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.

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', 'ShortFinal' and 'LongFinal' 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' or 'LongInitial' 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 entirely on
the presence or absence of the explicit dates.

Returns:

the optional value of the property, not null

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.

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 before the 'firstRegularStartDate'.

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.