OSB_LIB::BsPage

OSB_LIB::BsPage Class Reference

Collaboration diagram for OSB_LIB::BsPage:

Collaboration graph
[legend]
List of all members.

Detailed Description

Store the charges for one invoice of a Contract.

ToDo: rework
Every balance sheet will have a usage handler that contains a list of usage that applies to this balance sheet. Each time a balance sheet accept a rated call details record, it will add the cost to itself then pass the call details record to the usage handler for further processing.

Read access and local changes to a balance page are public.
All operations modifying the status of balance page in the database are private, i.e., accessible for BalanceSheet only. This has several reasons:

Definition at line 384 of file balancesheet.h.

Public Types

Public Member Functions

Accessors:
Read balance page data from database:

Static Public Member Functions

Private Member Functions

Private Attributes

STL containers to store the charges:

Friends

Classes

Member Typedef Documentation

typedef Id<BsPage> OSB_LIB::BsPage::Oid

Typesave object identification and database link.

Definition at line 403 of file balancesheet.h.

Member Enumeration Documentation

enum OSB_LIB::BsPage::CdrFileStatus

Status of changes to the CDRs of the page.

It is used to control the behavior of the page in restoreCdrs() and commitCdrs().

Enumerator:
fsUnchanged  CDRs unchanged: nothing 2do.
fsPending  CDRs written but database changes not commited.

This status implies that the recovery CDR files must be restored.

fsDbCommitted  CDR changes commited in database.

This status implies that the recovery CDR files must be removed.

Definition at line 440 of file balancesheet.h.

enum OSB_LIB::BsPage::Status

Enumeration to reflect the status of a balance page.

Enumerator:
bpUnknown  Unknown status.
bpNormal  Normal status for balance page.
bpRerate  Balance page is to be re-rated.
bpDontBill  Do not bill balance page.
bpBillingFailed  Billing failed for balance page.

Definition at line 420 of file balancesheet.h.

Constructor & Destructor Documentation

OSB_LIB::BsPage::BsPage ( const Oid &  oid = Oid()  )  [explicit]

Constructor with optional object id.

This is to construct a balance page that will later call read operations to populate its data members.

Parameters:
oid Object id of the balance sheet to be created.

OSB_LIB::BsPage::BsPage ( const Contract::Oid &  coId,
const Billcycle::Oid &  bcId 
)

Constructor to create a new balance sheet.

This function will create an empty balance sheet that is related to the contract passed in.

Parameters:
coId Contract id of the balance page.
bcId Billcycle id of the balance page.

OSB_LIB::BsPage::BsPage ( const BsPage &  rhs  ) 

Copy constructor.

OSB_LIB::BsPage::~BsPage (  ) 

Destructor will delete the usage handler object.

Member Function Documentation

void OSB_LIB::BsPage::addAdvCharge ( const Money &  charge  ) 

Add a advance charge (prototype).

void OSB_LIB::BsPage::addCdr ( const Cdr &  cdr  ) 

Add a CDR to the page.

This function updates the balance page based on the call details record it receives. Then it passes the call details record to usage handler for further processing.

Parameters:
cdr Call details record to be added to the balance sheet.
Exceptions:
PageClosed 

void OSB_LIB::BsPage::addOtc ( const OnetimeCharge &  otc  ) 

Add a onetime charge to the balance page.

Parameters:
otc Onetime charge to add.
Exceptions:
PageClosed 

const AdvanceCharges& OSB_LIB::BsPage::advanceCharges (  )  const [inline]

Advance charges assigned to the page.

Definition at line 567 of file balancesheet.h.

References advanceCharges_.

const Billcycle::Oid& OSB_LIB::BsPage::billcycleId (  )  const [inline]

Id of the page's bill cycle.

Definition at line 538 of file balancesheet.h.

References billcycleId_.

CdrIo& OSB_LIB::BsPage::cdrIo (  )  const [private]

Get the CdrIo object.

Allocates a CdrIo object if needed and returns a to it.

const CdrList& OSB_LIB::BsPage::cdrList (  )  const

CDRs of the page.

Returns:
List of CDRs: cdrs_.

const BsTotal& OSB_LIB::BsPage::charges (  )  const [inline]

Total of charges grouped by currency.

Definition at line 563 of file balancesheet.h.

References charges_.

void OSB_LIB::BsPage::clearRecoveryId ( const OSB_DB::Session &  session  )  [private]

Unset the recovery id.

Parameters:
session Database session to use.
Exceptions:
SetRecoveryFailed If the function throws, recoveryId_ is not changed.
If recoveryId_ is 0 (i.e., not set) the function returns immediately.

void OSB_LIB::BsPage::close ( const OSB_DB::Session &  session  )  [private]

Close the balance page.

Parameters:
session Database session to use.
Exceptions:
PageClosed (evaluated in the gateway).
NotFound 
NoEndDate 
Returns:
true in case of success, false if the page does not exist in the database.

const DateTime& OSB_LIB::BsPage::closed (  )  const [inline]

Date when the balance page was closed.

Definition at line 545 of file balancesheet.h.

References closed_.

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

Id of the contract.

Definition at line 528 of file balancesheet.h.

References coId_.

void OSB_LIB::BsPage::commitCdrs (  )  [private]

Remove backup CDR files.

This function removes the backup files created during writeCdrs().

Exceptions:
CommitCdrFailed Do not call this function if the session that was used to add and save the usage is not commited!

bool OSB_LIB::BsPage::delOtc ( const OnetimeCharge::Oid &  otcId  ) 

Delete a onetime charge of the balance page.

Parameters:
otcId Object id of the onetime charge to delete.
Exceptions:
PageClosed 
Returns:
true if the OTC existed in the page, else false.
After the function returns (without throwing) the onetime charge does no more exist in the page.

const Date OSB_LIB::BsPage::endDate (  )  const [inline]

End date of the billing period.

Definition at line 532 of file balancesheet.h.

References endDate_, and OSB_LIB::Date::max().

OnetimeCharge* OSB_LIB::BsPage::find ( const OnetimeCharge::Oid &  otcId  )  [private]

Find a onetime charge by its id.

const OnetimeCharge* OSB_LIB::BsPage::findOtc ( const OnetimeCharge::Oid &  otcId  ) 

Find a onetime charge by its id.

Parameters:
otcId Id of the onetime charge to find.
Returns:
Pointer to the onetime charge, 0 if not found.

OnetimeCharges& OSB_LIB::BsPage::getOnetimeCharges (  )  [inline]

Write access to onetime charges.

Definition at line 624 of file balancesheet.h.

References onetimeCharges_.

SubsCharges& OSB_LIB::BsPage::getSubsCharges (  )  [inline]

Write access to subscription charges.

Todo:
Redesign is needed once we write subscription charges back to the database:
Most likely we'll have to provide an EditStatus in SubsCharge and an appropriate update function in BsPage.

Definition at line 634 of file balancesheet.h.

References subsCharges_.

void OSB_LIB::BsPage::initialize (  )  [private]

Initialize "common" data members.

This function initializes all data members that can not be set via a constructor (such as e.g., the object id).

bool OSB_LIB::BsPage::insert ( const OSB_DB::Session &  session  )  [private]

Create a new balance page in the database.

The function creates an empty balance page in the database, any charges assigned to the page are ignored. The following data members are stored:
coId_, billcycleId_, startDate_ and endDate_.

If successful the following data members are set by the function: oid_ and opened_.

Parameters:
session Database session.
Exceptions:
OsbException for any error.
Returns:
true if successful else false.

bool OSB_LIB::BsPage::isOpen (  )  const [inline]

Balance page open?

Definition at line 547 of file balancesheet.h.

References closed_, and OSB_LIB::DateTime::notSet().

bool OSB_LIB::BsPage::justBilled (  )  const [inline]

Page just billed?

Definition at line 549 of file balancesheet.h.

References justBilled_.

const DateTime& OSB_LIB::BsPage::lastCharged (  )  const [inline]

Timestamp of the latest charge modification.

Definition at line 553 of file balancesheet.h.

References lastCharged_.

const Oid& OSB_LIB::BsPage::oid (  )  const [inline]

Object id.

Definition at line 526 of file balancesheet.h.

References oid_.

const OnetimeCharges& OSB_LIB::BsPage::onetimeCharges (  )  const [inline]

Onetime charges assigned to the page.

Definition at line 572 of file balancesheet.h.

References onetimeCharges_.

const DateTime& OSB_LIB::BsPage::opened (  )  const [inline]

Date when the balance page was opened.

Definition at line 543 of file balancesheet.h.

References opened_.

BsPage& OSB_LIB::BsPage::operator= ( const BsPage &  rhs  ) 

Assignment operator.

void OSB_LIB::BsPage::readAdvanceCharges ( const OSB_DB::Session &  session  ) 

Read the advanced charges from database.

This function will populate the balance sheet with advanced charges retrieved from database.

Parameters:
session Database session to use.

bool OSB_LIB::BsPage::readAll ( const OSB_DB::Session &  session,
bool  withCdr 
)

Read all balance page data with all charges.

The function reads the basic information and all charges from the database. It calls the following members in this order (please refer to the documentation there):

Parameters:
session Database session to use.
withCdr Flag if the individual Cdr should be read.
Exceptions:
OsbException for any error.
Returns:
true if success else false if object not found.

void OSB_LIB::BsPage::readCdrs ( CdrList &  dest  ) 

Read individual CDRs into a CDR list.

Parameters:
dest STL container to store the CDRs.
Note:
The function does not store the CDRs in cdrs_.

void OSB_LIB::BsPage::readCdrs (  ) 

Read the individual CDRs.

void OSB_LIB::BsPage::readCharges ( const OSB_DB::Session &  session,
bool  withCdr 
)

Read all charges of the balance page.

The function reads all charges of the balance page from the database. It calls the following members in this order (please refer to the documentation there):

Parameters:
session Database session to use.
withCdr Flag if the individual Cdr should be read.
Exceptions:
OsbException for any error.

bool OSB_LIB::BsPage::readInfo ( const OSB_DB::Session &  session  ) 

Read the info for a balance page from database.

The function uses the object id of the page to read basic information and the charge totals from the database.
This does not include not the individual charges.

Parameters:
session Database session to use.
Returns:
true if success else false.

void OSB_LIB::BsPage::readOnetimeCharges ( const OSB_DB::Session &  session  ) 

Read the one time charges from database.

This function will populate the balance sheet with one time charges retrieved from database within the time period stated.

Parameters:
session Database session to use.

void OSB_LIB::BsPage::readUsageCharges ( const OSB_DB::Session &  session,
bool  withCdr 
)

Read the usage charges.

For a balance page that stores summary call details records, this function will populates the usage list with corresponding summary records. To get all related call details records that are related to the summary call details records, set the withCdr parameter to true.

For a balance page that only stores Cdr records, this function, by default, will not populate the call details records into the usage list. This is to avoid storing duplicate Cdr when BsPage::writeCdrs() is called.

In the case where balance page is to be pass to billing module, balance page that only stores call details records will need to have the Cdr related to it. To achieve this, withCdr parameter is used. Set it to true if Cdr should be retrieved else false.

Todo:
Rework the logic described above: start with the requirements for rating and billing. It is not making sense that billing has to read all 10-20 million Cdr (wholesale contract), on the other hand there's call accounting and bundled rating at billing time.
Parameters:
session Database session.
withCdr Flag if the individual Cdr should be read.
Exceptions:
OsbException for any error.

long OSB_LIB::BsPage::recoveryId (  )  const [inline]

Identifier of recovery action.

See recoveryId_ for details.

Definition at line 561 of file balancesheet.h.

References recoveryId_.

bool OSB_LIB::BsPage::remove ( OSB_DB::Session &  session  )  [private]

Remove a balance page entry from database.

This function will remove a balance sheet entry and related summary call details record entries (if any) from database. Related Cdrs and the balance sheet directory structure will not be removed.

Remarks:
This function will unset the id of the balance sheet object that invokes this function. All database operation will be committed.
Parameters:
session Database session.
Returns:
True if success else false if object not found.

void OSB_LIB::BsPage::removeUsage ( const OSB_DB::Session &  session  )  [private]

Remove usage charges from the balance sheet.

Parameters:
session Database session to use.
Exceptions:
UpdateUsageFailed This function will remove all usage charges and rated cdr files from the balance page.

bool OSB_LIB::BsPage::rerating (  )  const [inline]

Page under rerating?

Definition at line 551 of file balancesheet.h.

References rerating_.

bool OSB_LIB::BsPage::restoreCdrFiles ( OSB_DB::Session &  session  )  [private]

Undo previous changes to CDRs.

Parameters:
session Database session to unset and commit the recovery id to the database.
Returns:
true if successful, else false.
Removes CDRs previously written to the file system (see writeCdrs()) and unsets the recovery id in the database.

bool OSB_LIB::BsPage::restoreCdrs ( OSB_DB::Session &  session  )  [private]

Restore changed CDRs after a failure.

Parameters:
session Database session to unset and commit the recovery id to the database.
Returns:
true if successful, else false.
The function uses cdrFileStatus_ to decide which actions should be taken in order to achieve a consistent status of the page, i.e., the CDR files must reflect the database status:

If the function returns true, data members tracking the status of the CDR files are reset:

Note:
session is committed only if changes in the CDR files were pending.

bool OSB_LIB::BsPage::saveAdvCharges ( const OSB_DB::Session &  session  )  [private]

Store added advance charges in the database (prototype).

bool OSB_LIB::BsPage::saveOtCharges ( const OSB_DB::Session &  session  )  [private]

Save all changes to onetime charges.

Parameters:
session Database session to use.
Returns:
true in case of success, else false.

void OSB_LIB::BsPage::setBilled (  )  [inline]

Mark the page as billed.

This member is used by the billing application only.

Definition at line 613 of file balancesheet.h.

References justBilled_.

void OSB_LIB::BsPage::setEndDate ( const Date &  endDate  ) 

Set the end date (see also endDate_).

Parameters:
endDate End date of the balance page.
If endDate is not set, Date::max() is used.

void OSB_LIB::BsPage::setRerating (  ) 

Mark the page as being rerated.

This member is used for the rating application only (rerating).

bool OSB_LIB::BsPage::setStatus ( const OSB_DB::Session &  session,
const Status &  status 
)

Change status of balance page.

Parameters:
session Database session.
status Status of balance page to change to.

const Date& OSB_LIB::BsPage::startDate (  )  const [inline]

Start date of the billing period.

Definition at line 530 of file balancesheet.h.

References startDate_.

const Status& OSB_LIB::BsPage::status (  )  const [inline]

Status of the page.

Definition at line 555 of file balancesheet.h.

References status_.

const SubsCharges& OSB_LIB::BsPage::subsCharges (  )  const [inline]

Subscription charges assigned to the page.

Definition at line 565 of file balancesheet.h.

References subsCharges_.

const SumCdrList* OSB_LIB::BsPage::sumCdrList (  )  const

Summary CDRs of the page.

Returns:
List of summary CDRs: sumCdrs_.

static long OSB_LIB::BsPage::toLong ( Status  status  )  [static]

Convert to status to long.

Parameters:
status Status of balance page to convert.
Returns:
The corresponding long value. Its value is (long)piUnknown if `status' is not supported.

static Status OSB_LIB::BsPage::toStatus ( long  status  )  [static]

Convert a long into a status.

Parameters:
status Status to convert.
Returns:
Status corresponding to long. Its value is bpUnknown if `status' is not supported.

void OSB_LIB::BsPage::updateUsage ( const OSB_DB::Session &  session  )  [private]

Update added usage to the database.

Parameters:
session Database session to use.
Exceptions:
UpdateUsageFailed The function first save the summary CDRs (if applicable), then sums up the added usage charges in the database.

bool OSB_LIB::BsPage::updLastCharged ( const OSB_DB::Session &  session  )  [private]

Set the timestamp for the last charge modification.

Parameters:
session Database session to use.
Returns:
true in case of succes, else false (usually if the page is not found).

bool OSB_LIB::BsPage::usageModified (  )  const

Flag if the usage of the page was modified.

Returns:
true if changes in the usage charges have not been updated to the database or changes to the CDR files have neither been committed nor undone.

void OSB_LIB::BsPage::writeCdrs ( long  recoveryId,
OSB_DB::Session &  session,
Asn1Writer &  writer 
) [private]

Write CDRs to file system.

Parameters:
recoveryId Identifier to use for recovery.
session Session to update and commit the recovery id to the database.
writer ASN.1 writer to use.
Exceptions:
RecoveryNeeded 
SetRecoveryFailed 
OsbException if writing of the CDR fails.
Returns:
true in case of success, else false (e.g. if the page does not exist in the database).
Note:
The function creates backup files used for recovery after a system failure. These backup files are removed in commitCdrs().

Friends And Related Function Documentation

friend class BalanceSheet [friend]

Provide access for the controlling balance sheet.

Only the balance sheet is allowed to call methods that change the page in datebase.
Also during the creation of a new page, the balance sheet must modify the start and end date.

Definition at line 399 of file balancesheet.h.

friend struct OSB_DB::BalanceSheetGw [friend]

Balance sheet gateway will need to populate the private data members of balance sheet object.

Definition at line 389 of file balancesheet.h.

Member Data Documentation

AdvanceCharges OSB_LIB::BsPage::advanceCharges_ [private]

Container holding the advance charges.

Definition at line 1089 of file balancesheet.h.

Referenced by advanceCharges().

Billcycle::Oid OSB_LIB::BsPage::billcycleId_ [private]

Billcycle id.

Definition at line 1024 of file balancesheet.h.

Referenced by billcycleId().

CdrFileStatus OSB_LIB::BsPage::cdrFileStatus_ [private]

Status of CDR changes.

Definition at line 1053 of file balancesheet.h.

CdrIo* OSB_LIB::BsPage::cdrIo_ [mutable, private]

CdrIo object used to handle the CDR files.

Attention:
Use only cdrIo() to get the object.

Definition at line 1081 of file balancesheet.h.

CdrList OSB_LIB::BsPage::cdrs_ [private]

List of cdrs that belong to the page.

Definition at line 1074 of file balancesheet.h.

BsTotal OSB_LIB::BsPage::charges_ [private]

Total of charges grouped by currency.

Definition at line 1070 of file balancesheet.h.

Referenced by charges().

DateTime OSB_LIB::BsPage::closed_ [private]

Date and time when the balance sheet was closed.

Definition at line 1028 of file balancesheet.h.

Referenced by closed(), and isOpen().

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

Contract id where this balance sheet belongs to.

Definition at line 1011 of file balancesheet.h.

Referenced by OSB_LIB::BalanceSheet::coId(), and coId().

Date OSB_LIB::BsPage::endDate_ [private]

End date of the billing period.

The end date is not meaningful for all billcycle types. If not applicable, it is set to Date::max().
Never modify this data member directly (not even the class itself!), use setEndDate() instead.

Definition at line 1022 of file balancesheet.h.

Referenced by endDate().

bool OSB_LIB::BsPage::justBilled_ [private]

Flag if the page was just billed.

Definition at line 1030 of file balancesheet.h.

Referenced by justBilled(), and setBilled().

DateTime OSB_LIB::BsPage::lastCharged_ [private]

Date and time when the charges were last modified.

Definition at line 1036 of file balancesheet.h.

Referenced by lastCharged().

Oid OSB_LIB::BsPage::oid_ [private]

Database link of balance sheet.

Definition at line 1009 of file balancesheet.h.

Referenced by oid().

OnetimeCharges OSB_LIB::BsPage::onetimeCharges_ [private]

Container holding onetime charges.

Definition at line 1091 of file balancesheet.h.

Referenced by getOnetimeCharges(), and onetimeCharges().

DateTime OSB_LIB::BsPage::opened_ [private]

Date and time when the balance sheet was opened.

Definition at line 1026 of file balancesheet.h.

Referenced by opened().

long OSB_LIB::BsPage::recoveryId_ [private]

Identifier for CDR recovery.

Possible values are:

           0: no recovery needed.
          <0: recovery from replacement of CDRs.
          >0: recovery from adding of CDRs.

Remarks:
Clients of the class use status() to check for any processing failures and not rely on this data member.

Definition at line 1067 of file balancesheet.h.

Referenced by recoveryId().

bool OSB_LIB::BsPage::rerating_ [private]

Flag if the page is being rerated.

Definition at line 1032 of file balancesheet.h.

Referenced by rerating().

Date OSB_LIB::BsPage::startDate_ [private]

Start date of the billing period.

Definition at line 1013 of file balancesheet.h.

Referenced by startDate().

Status OSB_LIB::BsPage::status_ [private]

Status of balance page.

Definition at line 1039 of file balancesheet.h.

Referenced by status().

SubsCharges OSB_LIB::BsPage::subsCharges_ [private]

Container holding the subscription charges.

Definition at line 1087 of file balancesheet.h.

Referenced by getSubsCharges(), and subsCharges().

SumCdrList* OSB_LIB::BsPage::sumCdrs_ [private]

List of sum cdrs that belong to the page.

Definition at line 1072 of file balancesheet.h.

bool OSB_LIB::BsPage::usageChanged_ [private]

Usage of the page modified and not updated to database?

The flag is set in all functions that modify the usage charges and cleared in updateUsage().
For the avoidance of doubt: the flag does not track the changes to the CDR files.

Definition at line 1050 of file balancesheet.h.

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