Rollover Framework

Change log:

Summary

Rollover bundles are used to enable transfer of remaining free units from one period to another subsequent period. The purpose of this document is to describe how this functionality is implemented as part of the core project.

Rollover Concept

Rollover is the term to describe that some part of free units from one SubscriptionBundle which have not been spent in one period, can be used later by another subsequent SubscriptionBundle. The amount to be 'rolled over' to another bundle can also be referred to as a 'surplus. The Rollover can be described with four parameters:

1. Maximum rollover amount per SubscriptionBundle - how much can be transferred from one period to another.
2. Rollover validity\Rollover period length - for how long is the rollover valid, i.e. how many periods from the past can be used.
3. Rollover usage mode - in use, should free units first be subtracted from surplus or from the current SubscriptionBundle.
4. Internal order of the surplus - are the 'newer' or 'older' free units used first.

Design and Implementation

The starting point of the design was the fact, that a subscription bundle has to work in two contexts:

• in the original - when a billing record has the charge date between start and end date of the subscription bundle
• as a container of surplus available for other subscription_bundles.
  In the rating process, it should be the responsibility of the bundle to fetch and update both original and additional, used for surplus subscription bundles.

SubscriptionBundle

The existing SubscriptionBundle_ has been extended with methods defined by RolloverSurplus interface. These are:

• getSurplus - returns amount of units that can be used by other subscription bundles,
• updateSurplus - updates the surplus with the given value, and returns the part that is above the maximum surplus value (which is defined on VALUE_3),
• save - saves the object.

A subscription_bundle that is used by rollover bundles, utilizes all four value parameters:

• VALUE_1 - maximum number of units inside subscription bundle,
• VALUE_2 - total number of units used, i.e. the sum of units used by the subscription bundle itself and by other subscription bundles (when the bundle is used as a surplus bundle),
• VALUE_3 - maximum number of units that can be rolled over (the maximum number of units that can be used as surplus by other subscription bundles). As this value indicates a part of value_1, it will not make sense to have a number greater than value_1.
• VALUE_4 - total number of units used by rollover. Value cannot exceed value_3. Note that value_4 is not a simple value, it is used as "a value from which other information can be calculated" (for more information, see below).

Value_4 Explained

The difference between value_3 and value_4 (i.e. value_3 - value_4) is supposed to indicate how many units are available for rollover.

This means that every time units are used (i.e. some value is added to value_2), also value_4 is likewise increased with the same number of units, as this now indicates that less units are available for rollover.

The rules for how/when to update value_4 are:

• When the bundle is used as a surplus bundle by another bundle, then value_4 is updated with the amount of units used by that other bundle.
  • Note that the process that updates value_4 shall make sure to also update value_2 with the same amount of units.
• When value_2 is updated it needs to be checked if the total units available in the bundle is now less than the number of units that can be used as surplus. If this is the case, then value_4 needs to be updated such that this is no longer the case.
  • In more mathematical terms, if (value_1-value_2)<(value_3-value_4), then adjust value_4 such that the '<' becomes '='. This means that value_4 shall be set equal to value_3-(value_1-value_2).

Examples

Suppose a bundle has value_1 = 500, value_3 = 200. This means the bundle has 500 units for charges in actual period, from which 200 units may be used by charged from other periods.

Suppose now that 190 units have been used in a period, i.e. value_2 = 190 and value_4 = 190.

• If some usage with 25 units is processed by the bundle within the actual period, all 25 units will be added to value_2 (as all units belong to the actual period), but value_4 will only be added 10 units as there is a limit of 200 units. Consequently, value_2 = 215 and value_4 = 200. 
• Instead, if some usage with 25 units is processed by the bundle outside the actual period (i.e. rollover), only 10 units will be added to both value_2 and value_4. Consequently, value_2 = 200 and value_4 = 200. This means that the period still allows 300 units to be used inside the period, but no units are left for rollover.

Subscription Bundle Update Manager

An update manager is a class responsible for setting and getting the right amounts from the SubscriptionBundle when queried. Currently a number of update managers are implemented, see below.

The rollover functionality can be enabled by enabling the rollover version of the update manager. This is done by adding the following line to the bundle parameters:

UPDATE_MANAGER=ROLLOVER

By not setting the update manager to anything the DefaultUpdateManager will be used which does not consider rollover functionality.

Updating SubscriptionBundle

Standard Update

When a SubscriptionBundle object is used in the normal way, the used units are accumulated on VALUE_2. When VALUE_2 is greater than VALUE_1 - VALUE_3, then VALUE_4 gets a new value calculated in the following way VALUE_2 - (VALUE_1 - VALUE_3). If VALUE_4 is greater than VALUE_3 then VALUE_3 is set.

Update through rollover

The surplus units are aggregated on VALUE_2 and VALUE_4, until the maximum defined by VALUE_3 is reached.

Bundle

If a bundle is designed as a rollover bundle, it must implement the RolloverBundle interface. The interface has five methods and two enumeration types:

• getMaxSurplus - returns the maximum amount of units that can be transferred as surplus from a SubscriptionBundle,
• getSurplusPeriodOrder - returns one of the values of SurplusPeriodOrder, which indicates whether SubscriptionBundle used for surplus should be ordered from newer to older units, or the other way round,
• getSurplusUsageMode - returns one of the values of SurplusUsageMode and is used to define, whether surplus should be used before or after SubscriptionBundle,
• getAmountOfRolloverPeriods - returns an amount (integer value) of previous periods from which surplus can be used
• SurplusPeriodOrder - an enum with two values: NEWER_FIRST and OLDER_FIRST used by getSurplusPeriodOrder,
• SurplusUsageMode - an enum with two values: USE_ROLLOVER_BEFORE_BUNDLE and USE_ROLLOVER_AFTER_BUNDLE used by getSurplusUsageMode,
  Currently, the only bundles that implement the RolloverBundle interface is RestrictActive and PostRatingBundleV2.

One thing worth pointing out: a new method, for calculating the amount of free units on a SubscriptionBundle, has been introduced on the Bundle_ class. It is called getFreeUnits. This was done, because the classical VALUE_1 - VALUE_2 is no longer valid, when surplus is used. The update manager now has this responsibility.

SurplusContainer

SurplusContainer is a wrapper object that encapsulates a list of SubscriptionBundle objects. It has two methods:

• getSurplusValue returns the sum of surplus for the whole period,
• updateSurplus updates the whole surplus by looping through the list of RolloverSurplus; returns the remainder from the last RolloverSurplus.updateSurplus.
  The class does not have a default constructor and can be only constructed by SurplusContainter(List<RolloverSurplus> surplusList). The list can be constructed with a helper class SurplusContainerFetcher.

SurplusContainerFetcher

An implementation of the SurplusContainerFetcher interface is responsible for creation of SurplusContainer objects. The used implementation is defined in the bundle parameter ROLLOVER.SURPLUS.FETCHER. Its value should be a name of the class that implements the SurplusContainerFetcher interface

Configuration

In order to configure DataBundle, DurationBundle, EventBundle or ForwardBundle to use rollover functionality the following parameters must be set up in the bundle's parameters and meta data: