Skip to end of metadata
  • Created by Former user , last modified on 11.09.2012
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Summary

Rollover bundles are used to make possible transferring, some of remaining usage from one period to an another, later period. Purpose of this document is to describe, how this functionality is implemented as a part of the core project.

Dictionary

This section contains specific terms used in the document.
Maximum surplus - a maximum, possible amount of units, that can be used by another period.
Surplus - Amount of units currently available to transfer to the next period.
Rollover period - an amount of previous periods, from which surplus can be used.

Required functionality

A rollover bundle needs to implement following functionality:

  • It should be possible to configure the maximum amount of free units from one period to another.
  • Defining amount of period valid for rollover.
  • How the surplus should be used first - from older or from newer periods first.
  • Should surplus be used before or after the current bundle.
  • Proper handling of late usage. Using surplus from the bundle should not prevent using it for rating.

Design and implementation

The starting point for the design, was the fact, that a subscription bundle needs 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 a responsibility of the bundle to fetch and update both original and additional, used for surplus subscription bundles.

SubscriptionBundle

The existing SubscriptionBundle_, has 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 and returns the remnant, that is above 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
Updating subscription_bundle

Standard update
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 usage is aggregated on both VALUE_1 and VALUE_4 until the maximum, defined by VALUE_3 is reached.

Bundle
If a bundle is supposed to be a rollover bundle, it is a requirement for it to implement RolloverBundle interface. The interface has five methods and two enumeration types:

  • getSurplusContainter - returns a SurplusContainter object, that wraps surplus for a given SubscriptionBundle. The SurplusContainter is described in the following paragraph,
  • getMaxTransferableAmount - returns the maximum amount of units, that can be trasfer as surplus from a SubscriptionBundle,
  • getSurplusPeriodOrder - returns one of the values of SURPLUS_PERIOD_ORDER, which indicates, whether SubscriptionBundle used for surplus shuld be ordered from newer to older or the other wat around,
  • getSurplusUsageMode - returns one of the values of SURPLUS_PERIOD_ORDER and is used to define, whether surplus should be used before or after SubscriptionBundle,
  • getAmountOfRolloverPeriods - returns an amount of previous periods, from which surplus can be used
  • SURPLUS_PERIOD_ORDER - an enum with two values: NEWER_FIRST and OLDER_FIRST,
  • SURPLUS_USAGE_MODE - - an enum with two values: USE_SURPLUS_BEFORE_BUNDLE and USE_SURPLUS_AFTER_BUNDLE,
    Currently, the only Bundle, that implements the RolloverBundle interface is RestrictActive. This means, that DataBundle, DurationBundle, EventBundle and ForwardBundle have a possibility, when properly configured, to behave like a RolloverBundle.

One thing is worth to point 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 has happened, because the classical VALUE_1 - VALUE_2 is no longer valid, when surplus is used.

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

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

Configuration
It is not enough for a bundle to juest implement the RolloverBundle interface to work. There should also be defined three aditional parameters:

  • No labels