Page Comparison

{float:right|width=300px|background=lightgrey|border=solid blue 2px|margin=10px|padding=8px}*Contents*
{toc:all=true|depth=4|excerpt=true}
{float}

h1. Summary

Rollover bundles are used to enable transfering some of the remaining free units from one period to an another later period. The purpose of this document is to describe, how this functionality is implemented as a part of the core project.

h1. Rollover Concept

Rollover means, that some part of the free units from one {{SubscriptionBundle}} which have not been used in one period, can be used later on by an another later {{SubscriptionBundle}}. The amount to be 'rolled over' to another bundle can also be called "surplus". The Rollover can be described with four parameters:
# Maximum rollover amount per {{SubscriptionBundle}} \- how much can be transferred from one period to another.
# Rollover validity\Rollover period length - For how long is the rollover valid, i.e. how many periods from the past can be used.
# Rollover usage mode - In use, should free units first be subtracted from surplus or from the current {{SubscriptionBundle}}.
# Internal order of the surplus - Are the 'newer' or 'older' free units used first.

h1. Design and implementation
{gliffy:name=Rollover design|align=left|size=L|version=10}
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.

h2. 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 another bundles,
* {{updateSurplus}} \- updates the surplus with a given value, returns the part above the maximum surplus value - {{VALUE_3}},
* {{save}} \- saves the object.

A {{subscription_bundle}} that is used by rollover bundles, utilizes all four value parameters:
* {{VALUE_1}} \- number of units inside bundle,
* {{VALUE_2}} \- number of units used,
* {{VALUE_3}} \- number of units, that can be rolled over
* {{VALUE_4}} \- number of used rollover units.

h2. Subscription Bundle Update Manager

An update manager is a class responsible for setting and getting the right amounts from the {{SubscriptionBundle}} when queried. Currently two versions of update managers are implemented: {{DefaultUpdateManager}} and {{RolloverUpdateManager}}.

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:

{code}
UPDATE_MANAGER=ROLLOVER
{code}
By not setting the update manager to anything the {{DefaultUpdateManager}} will be used which does not consider rollover functionality.

h2. Updating SubscriptionBundle

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

h3. Update through rollover

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

h2. 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 around,
* {{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 is 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.


h2. 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}}.

h2. SurplusContainerFetcher

An inmplementation of the {{SurplusContainerFetcher}} interface is responsible for creation of {{SurplusContainer}} objects. Bundle parameter ROLLOVER.SURPLUS.FETCHER. It's value should be a name of the class that implements the {{SurplusContainerFetcher}} interface. If the parameter is not present {{DefaultSurplusContainerFetcher}} is used. It provides the functionality described on this page. The other option provided by the core is {{AllSubscriptionBundlesOnDate}}, that fetches all {{SubscriptionBundles}} active on the charge date.
h1. Configuration

In order to configure {{DataBundle}}, {{DurationBundle}}, {{EventBundle}} or {{ForwardBundle}} to use rollover functionality following parameters must be set up:
|| Name | Description ||
| ROLLOVER.PERIOD.ORDER | Defines whether older or newer surplus should be used first. Two possible values are possible: NEWER_FIRST and OLDER_FIRST |
| ROLLOVER.USAGE.MODE | Indicates whether surplus should be used before or after the {{SubscriptionBundles}}. Again two values are possible: USE_ROLLOVER_BEFORE_BUNDLE, USE_ROLLOVER_AFTER_BUNDLE |
| ROLLOVER.PERIODS | Amount of previous {{SubscriptionBundles}} used in rollover. In other words, the number defines how many times surplus can be rolled over |
| UPDATE_MANAGER | DEFAULT for the standard functionality without rollover \\
ROLLOVER for the rollover funcationlity enabled |