OSB_LIB::BalanceSheet

OSB_LIB::BalanceSheet Class Reference

Collaboration diagram for OSB_LIB::BalanceSheet:

Collaboration graph
[legend]
List of all members.

Detailed Description

Balance sheet provides the estimated charges for a single contract.

A balance sheet consists of several BsPage where each page stores the estimated charges for one invoice.

The class is the manager of all pages: it controls all database updates and supports clients in adding, changing or removing charges.

In order to avoid a misconception: It is possible for clients to manipulate balance pages directly, they will however to not be able to permanently save the changes.

Bug:
The current design suffers from one problem: On one hand it tries to allow for incremental updates of the pages without the need of locking the balance sheet, on the other hand new pages are created in the database whenever needed.
The later unfortunately would require a database lock: With the current status primary key violations on BS_PAGE may be risen if several clients try to add charges at the same time without having the balance sheet locked. Work-arounds are possible:

Definition at line 1252 of file balancesheet.h.

Public Types

Public Member Functions

Accessors:
Handling of new usage charges:
Handling of onetime charges:
Handling of advance charges (prototype):

Private Member Functions

Private Attributes

Friends

Classes

Member Typedef Documentation

typedef std::list<BsPage> OSB_LIB::BalanceSheet::Pages

Container for a list of balance sheet.

Definition at line 1258 of file balancesheet.h.

Constructor & Destructor Documentation

OSB_LIB::BalanceSheet::BalanceSheet ( const Contract::Oid &  coId = Contract::Oid()  )  [inline, explicit]

Default constructor with optional contract id.

Definition at line 1273 of file balancesheet.h.

Member Function Documentation

void OSB_LIB::BalanceSheet::addAdvCharge ( const Money &  charge,
const DateTime &  valueDate,
const OSB_DB::Session &  session 
)

Add an advance charge.

BsPage::Oid OSB_LIB::BalanceSheet::addOtc ( const OnetimeCharge &  otc,
const OSB_DB::Session &  session 
)

Add a onetime charge.

Parameters:
otc Onetime charge to add, the value date is OnetimeCharge::assigned.
session Database session to use for the creation of a new balance page.
Returns:
The id of the balance page to which the onetime charge was assigned.

void OSB_LIB::BalanceSheet::addUsage ( const CdrList &  cdrs,
const OSB_DB::Session &  session 
)

Add a list of CDRs to the balance sheet.

Parameters:
cdrs STL container with the CDRs to add.
session Database session that is used for the creation of a new balance page.

void OSB_LIB::BalanceSheet::addUsage ( const Cdr &  cdr,
const OSB_DB::Session &  session 
)

Add a CDR to the balance sheet.

Parameters:
cdr Call detail record to add: The value date is the timestamp of the CDR.
session Database session to use for the creation of a new balance page.

bool OSB_LIB::BalanceSheet::allPages (  )  const [inline]

Flag if the balance sheet contains all pages.

Returns:
true if all pages were read, false if the sheet contains the open pages only or no pages at all.

Definition at line 1296 of file balancesheet.h.

ObjectStatus OSB_LIB::BalanceSheet::checkObjVs ( const OSB_DB::Session &  session  )  const

Check the object version.

Parameters:
session Database session to use.
Returns:
The object status of the balance sheet: unchanged, modified or deleted.

void OSB_LIB::BalanceSheet::clearRecoveryId ( const OSB_DB::Session &  session  ) 

Unset the recovery id.

Parameters:
session Database session to use.
Exceptions:
OsbException (BsPage::SetRecoveryFailed) if the update fails for any of the pages.
Returns:
False if the recovery id of any balance page could not be unset, else true.
The function calls BsPage::clearRecoveryId() for each page.

void OSB_LIB::BalanceSheet::closeBilledPages ( const OSB_DB::Session &  session,
const DateTime &  billed,
const Contract &  contract 
)

Close all billed pages.

Parameters:
session Database session to use.
billed Date and time when the pages were billed: used to set BsPage::closed_.
contract Contract that was billed. It it used to determine if a new page should be opened.
Exceptions:
NotLocked 
OsbException from BsPage::close.
Returns:
true if the update is successful for all pages, else false.

const Contract::Oid& OSB_LIB::BalanceSheet::coId (  )  const [inline]

Contract id.

Definition at line 1281 of file balancesheet.h.

References OSB_LIB::BsPage::coId_.

void OSB_LIB::BalanceSheet::commitCdrs (  ) 

Remove backup files.

This function removes the backup files created during writeCdrs().
It calls BsPage::commitCdrs() for each page.

Exceptions:
NotLocked 
OsbException from BsPage::commitCdrs().
Do not call this function if the session that was used to add and save the usage is not commited!

bool OSB_LIB::BalanceSheet::createPage ( const OSB_DB::Session &  session,
const Date &  tsDate 
) [private]

Create one (or more) balance page.

Parameters:
session Database session to use.
tsDate Date of the timestamp for which to create the page.
Returns:
True in case of success, else false.
Exceptions:
BillcycleInvalid After the successful return of this function, the caller should use getOpenPage to retrieve the open balance page for ts.
This function create one or more balance pages in the database. It is called only if no open balance page with ts < end date exists.
One of the following two scenarios applies: 
          a) no page with start date <= ts < end date exists.
             Because pages are created without gaps, this means
             that no page beyond ts exists.

             -------|--C--|-C/O-|--N--|--N--|-------> t
                                        ^ts

          b) the page with start date <= ts < end date is closed.
             Because we know (only) all open pages, other closed
             pages for later invoice periods may exist:

             ----|--C--|--O--|--C--|--C--|--N--|----> t
                               ^ts
          C: closed page
          O: open page
          N: new page(s) created by this function.

For a) we have to create all pages since the latest page (or the contract creation date) till ts is the invoice period.
For b) we must create the page after the last closed one.

For both scenarios we can use the end date of the latest page or, if no page exists, the contract creation date as start date for the pages to add. The creation of pages is complete once we have created a page with end date > ts.

In the special situation where the last open balance page belongs to a DateBillcyle that function returns without creating a new page. This is because all charges added to the balance sheet will be assigned to this open page.
In normal operation this function should never be called if this scenario applies: if this happens for whatsoever reason the next call to getOpenPage will fail and result in the exception NoOpenPage.

Note:
The behavior as described above is the rationale for the member nextPageStart_.

BsPage* OSB_LIB::BalanceSheet::findPage ( const BsPage::Oid &  pageId  ) 

Find a balance page by its id.

Parameters:
pageId Id of the balance page to find.
Returns:
Pointer to the page, 0 if not found.

void OSB_LIB::BalanceSheet::getCdrsToRerate ( CdrList &  dest  ) 

Read the usage charges of the pages that need rerating.

Parameters:
dest STL container to store the CDRs.
For every page that needs rerating the function sets the rerating flag (BsPage::rerating_) and stores the CDRs of the page in dest.

Note:
The pages will not store the CDRs in their internal list (BsPage::cdrs_).

BsPage* OSB_LIB::BalanceSheet::getOpenPage ( const DateTime &  ts  ) 

Get the open balance page for a time stamp.

Returns:
A pointer to an open balance page to which a charge with value-date ts should be assigned, 0 if no such open page exists.
The task of the function is the following:
Within the set of all open pages with ts < end, find the one with the earliest (smallest) start date.
In the 95% trivial case this will be the open page with start <= ts.

Pages& OSB_LIB::BalanceSheet::getPages (  )  [inline]

Write access to all balance pages.

Definition at line 1309 of file balancesheet.h.

bool OSB_LIB::BalanceSheet::insert ( const OSB_DB::Session &  session  ) 

Create a new balance sheet entry in database.

Parameters:
session Database session.
Returns:
true in case of success.
The implementation uses an OSB_DB::BalanceSheetGw:
After the balance sheet is successfully inserted it reads itself from the database to initialize data members that are otherwise not available, e.g. bcType_.

ObjectStatus OSB_LIB::BalanceSheet::lock ( const OSB_DB::Session &  session,
bool  noWait = false 
)

Lock the balance sheet.

If locking is successful the object version of the balance sheet is incremented by 1 in the object itself and in the database.
If the function returns objModified it is the decision of the caller to or not to reread balance sheet from the database.

Parameters:
session Database session.
noWait Flag if the function should not block if the balance sheet is locked otherwise.
Exceptions:
Deadlock 
LockFailed 
Returns:
The object status of the balance sheet: unchanged or modified.
The function always throws if the balance sheet can not be locked:
If the balance sheet does not exist in the database or it is locked by another thread/application and noWait is true the function throws LockFailed.

Attention:
Use the nowait option with care:
Multiple balance sheets must be locked in ascending order of the contract id. Unless the caller does some kind of polling (discouraged!) until the balance sheet becomes available: if locking of a balance sheet fails, any hold locks must be released prior to lock it again.
Todo:
We may try to be more clever. Provide an optional argument reRead: if set to true locking will be done by contract id only, if set to false the locking criteria will include the object version.
Should we be more clever? In (programmer's) real life such a specification may prove too restrictive because it prevents incremental updates.

bool OSB_LIB::BalanceSheet::locked (  )  const [inline]

Balance sheet locked?

Definition at line 1283 of file balancesheet.h.

long OSB_LIB::BalanceSheet::objVs (  )  const [inline]

Balance sheet object version.

Definition at line 1285 of file balancesheet.h.

bool OSB_LIB::BalanceSheet::openPage ( const OSB_DB::Session &  session,
const DateTime &  ts,
const Contract &  contract 
)

Open a new balance page if needed.

Parameters:
session Database session to use.
ts Date and time for which to create the page.
contract Contract of the balance sheet.
Returns:
true if a new page was created, else false.
The function creates a new balance page if

The second condition is not evaluated strictly. Instead the contract's effective status and date are used. In very rare situations this might result in a "wrongly" opened page in the past, which is later nullified by the billing application.

const Pages& OSB_LIB::BalanceSheet::pages (  )  const [inline]

All balance pages.

Definition at line 1298 of file balancesheet.h.

bool OSB_LIB::BalanceSheet::read ( const OSB_DB::Session &  session,
bool  readAll = false 
)

Read the balance sheet from the database.

This includes:

After the pages have been read, they are sorted by descending start date by calling sortPages.

Note:
The function can be called with or without having the balance sheet locked. Clients that need to access the charge details of all pages consistently can either rely on the object version of the sheet and the pages or lock the balance sheet.
Attention:
Never lock the balance sheet for on-line browsing of the pages and their charge details: we would give the on-line user control over database locks!
Parameters:
session Database session to use.
readAll Flag to read closed pages too.
Exceptions:
BillcycleInvalid if the billcycle type is unknown.
Returns:
True if success, false if the balance sheet does not exist in the database.

void OSB_LIB::BalanceSheet::readCdrs (  ) 

Read the CDRs for all pages.

bool OSB_LIB::BalanceSheet::readCharges ( const OSB_DB::Session &  session,
bool  withUsg,
bool  withCdr,
bool  withOtc,
bool  withAdv 
)

Read the charge details for all pages.

The function reads the charge details for the pages of the balance sheet previously retrieved by read().
NOTE that read() calls BsPage::readInfo() for each page, so there's no need to call this member function of the balance page again.

Parameters:
session Database session to use.
withUsg Flag to read usage charges.
withCdr Flag to read the individual Cdr.
withOtc Flag to read onetime charges.
withAdv Flag to read advance charges.
Returns:
True if all pages could be read, else false.
Note:
As stated in BsPage::readUsageCharges the detailed meaning for withCdr remains to be worked out. For the moment usages charges are read as follows: 
          // somehow iter points to a page ...
          Pages::iterator iter = ...;
          if (withUsg) i->readUsageCharges(session, withCdr);

void OSB_LIB::BalanceSheet::removeUsage ( const OSB_DB::Session &  session  ) 

Remove cdrs from the file sysytem and database.

Parameters:
session Database session to use.
Exceptions:
OsbException from BsPage::removeUsage().
This function will remove all usage charges and rated cdr files of the balance pages in the balance sheet.

bool OSB_LIB::BalanceSheet::restoreCdrs ( OSB_DB::Session &  session  ) 

Restore changed CDRs after a failure.

Parameters:
session Database session to unset and commit the recovery id to the database.
Returns:
true in case of success, false if
  • the balance sheet is not locked
  • restoreCdrs fails for one of the pages.
Restores CDRs previously written to the file system (using writeCdrs()). If the balance sheet is locked, the function calls BsPage::restoreCdrs() for each page.

bool OSB_LIB::BalanceSheet::saveAdvCharges ( const OSB_DB::Session &  session  ) 

Write advance charges to database.

bool OSB_LIB::BalanceSheet::saveOtCharges ( const OSB_DB::Session &  session  ) 

Save changes to onetime charges.

Parameters:
session Database session to use.
Exceptions:
NotLocked 
Returns:
true if the update is successful for all pages, else false.
Stores all modifications of onetime charges in the database.

bool OSB_LIB::BalanceSheet::setUnlocked (  ) 

Mark the balance sheet as unlocked.

Clients of the class call this member after a commit or rollback of the database session used to call lock.

Returns:
The value of locked_ prior to calling the function.

void OSB_LIB::BalanceSheet::sortPages ( bool  desc = true  ) 

Sort balance pages by start date.

Parameters:
desc Flag to sort in descending (true) or ascending (false) order.
Remarks:
Clients that need a different sorting may use getPages().sort instead.

void OSB_LIB::BalanceSheet::totalCharges ( BsTotal &  dest,
bool  openOnly 
) const

The summed-up charge totals of all pages.

Parameters:
dest Balance sheet total list to populate.
openOnly Flag if only open pages should be summed-up.

void OSB_LIB::BalanceSheet::updateUsage ( const OSB_DB::Session &  session  ) 

Update the usage charges.

Parameters:
session Database session to use.
Exceptions:
NotLocked 
OsbException from BsPage::updateUsage().
Writes the added usage charges (see addUsage()) to the database.

bool OSB_LIB::BalanceSheet::usageModified (  )  const

Flag if usage of the balance sheet was modified.

void OSB_LIB::BalanceSheet::writeCdrs ( long  recoveryId,
OSB_DB::Session &  session,
Asn1Writer &  writer 
)

Write added CDRs to the file system.

Parameters:
recoveryId Recovery mark to use.
session Session used to write and commit the recovery id to the database.
writer ASN.1 writer to use.
Exceptions:
NotLocked 
OsbException from BsPage::writeCdrs().
Stores added CDRs (see addUsage()) on the file system. The function calls BsPage::writeCdrs() for each page.

Friends And Related Function Documentation

friend struct OSB_DB::BalanceSheetGw [friend]

Allow the supporting gateway to set data members directely.

Definition at line 1254 of file balancesheet.h.

Member Data Documentation

bool OSB_LIB::BalanceSheet::allPages_ [private]

All pages read?

Definition at line 1795 of file balancesheet.h.

Billcycle::Oid OSB_LIB::BalanceSheet::bcId_ [private]

Current billcycle of the contract.

Definition at line 1810 of file balancesheet.h.

Billcycle::Type OSB_LIB::BalanceSheet::bcType_ [private]

The type of the currenct billcycle.

Definition at line 1812 of file balancesheet.h.

Contract::Oid OSB_LIB::BalanceSheet::coId_ [private]

Contract where this balance sheet belongs to.

Definition at line 1782 of file balancesheet.h.

bool OSB_LIB::BalanceSheet::locked_ [private]

Indicator if the balance sheet is locked or not.

Use this with care. Since a lock is only released at the end of each database transaction, i.e., through a rollback or commit, the value returned by this function only tells if a lock has been acquired for this balance sheet.

Definition at line 1791 of file balancesheet.h.

Date OSB_LIB::BalanceSheet::nextPageStart_ [private]

Start date for the next balance page.

This is either the latest end of a balance page or -if no page exists- the creation date of the contract.
If the end date of the latest balance page is not set (DateBillcycle) the value is Date::notSet().
See createPage for a detailed explanation.

Definition at line 1807 of file balancesheet.h.

long OSB_LIB::BalanceSheet::objVs_ [private]

Object version: incremented by 1 for each database update.

Definition at line 1793 of file balancesheet.h.

Pages OSB_LIB::BalanceSheet::pages_ [private]

List of balance pages.

Definition at line 1797 of file balancesheet.h.

The documentation for this class was generated from the following file:
Generated on Sat Sep 2 14:09:43 2006 for OSB Library by  doxygen 1.4.7