DataPool Class Reference
[Data Processing]

#include <DataPool.h>

Inheritance diagram for DataPool:

List of all members.

---

Detailed Description

Base class from which all data pool classes are derived.

A data pool is a component that acts as a shared data area for data that must be exchanged among other components. The data pool physically contains the data to be exchanged. The producers of the data deposit them into the data pool and the consumers of the data retrieve them from the data pool. This class implements a data pool as a collection of items with the following attributes:

• Each item in the data pool has a value.
• Each item in the data pool has a time stamp that represents the time when the value of the item was last updated.
• Each item in the data pool has a type that represents the syntactical type of the value of the item. This interface recognizes two possible types: "float" and "integer" that, at syntactical level, correspond to two types defined through typedef declarations (TD_Float and TD_Integer).
• Each item in the data pool is identified by a data pool item identifier. Access to the value of the item is exclusively through its identifier. Note that this class does not mandate any checks on the legality of the data identifier used by a caller. This is not done because of the potential execution and memory costs of such checks. Legality checks can however be introduced by some implementations if needed.
• Each item in the data pool has a validity status that can have two values: "valid" and "not valid".
• Each item in the data pool has an associated monitoring profile that represents the legal time profile that the value of the data pool item can take.
• Each item in the data pool has an associated recovery action that represents the recovery action that should be performed when the value of the item violates its monitoring profile.

This is an abstract class because the internal organization of the data pool is application-dependent. In particular, the data structure used to represent the data pool and the implementation of the attributes defined above is left undefined. Full implementation of all the above attributes would result in a very "heavy" class that would not be suitable for applications with tight memory and CPU budgets. Most concrete data pool classes will only provide meaningful implementations for only a subset of the above attributes.

This class defines the following service:

• The iteration service that allows a client to iterate over all the identifiers of the items contained in the data pool.
• The type checking service that allows a client to check the type of an item as a function of its identifier. The type checking service can also be used to check whether a certain integer is a legal identifier.
• The reset service that resets the validity status of all data pool items to the value they had at the time the data pool component was initialized.

The purpose of a data pool is to allow client components to link to it to access data which they share with other components. This data pool offers three types of linking mechanism to a client component:<ul> Copy Link: the client component accesses the value of the shared datum through data setter and getter methods. The shared datum is copied to and from the data pool. Pointer Link: at configuration time, the client component accesses the pointer of the shared datum and then uses this pointer to access the value of the datum during the operational phase. Data Item Link: at configuration time, the client component accesses the data item that encapsulates the shared datum and accesses its value during during the operational phase using the services defined by the DC_DataItem class. A data pool is a low-level data structure whose implementation will usually require use of pointers. Most implementations of this class will therefore violate project specific coding rule PR3.1.

Todo:

This class defines the setter and getter methods to be virtual. This is expensive in CPU time. Given that data pool implementations will often be generated automatically by XSL programs, and given that an application would normally only have one data pool component, it may be wiser to have the XSL program generate an implementation for class DataPool that is defined to have only non-virtual methods. The problem with this approach is that it is not possible to have multiple implementations of a data pool in a single delivery and that therefore it is not possible to have several data pool test cases in the same delivery (this could be alleviated by generating the test case for the data pool as well as the data pool implementation).

Author:

Alessandro Pasetti (P&P Software GmbH)

Version:

1.0

Definition at line 101 of file DataPool.h.

Public Member Functions
	DataPool (void)
	Instantiate a data pool object.
virtual void	setValue (TD_DataPoolId id, TD_Float newValue)=0
	Setter method for the value of a real-typed data pool item.
virtual void	setValue (TD_DataPoolId id, TD_Integer newValue)=0
	Setter method for the value of an integer-typed data pool item.
virtual TD_Float	getFloatValue (TD_DataPoolId id)=0
	Getter method for the value of a real-typed data pool item.
virtual TD_Integer	getIntegerValue (TD_DataPoolId id)=0
	Getter method for the value of an integer-typed data pool item.
virtual TD_Float *	getPointerFloatValue (TD_DataPoolId id)=0
	Getter method for the pointer to a real-typed data pool item.
virtual TD_Integer *	getPointerIntegerValue (TD_DataPoolId id)=0
	Getter method for the pointer to an integer-typed data pool item.
virtual DC_DataItem *	getDataItem (TD_DataPoolId id)
	Getter method for a data item that encapsulates a data pool item.
virtual TD_ObsTime	getTimeStamp (TD_DataPoolId id)
	Return the time stamp of a data pool item.
virtual bool	isValid (TD_DataPoolId id)
	Return the validity status of a data pool item.
virtual void	setValidityStatus (TD_DataPoolId id, bool newValidityStatus)
	Set the validity status of a data pool item.
virtual MonitoringProfile *	getMonitoringProfile (TD_DataPoolId id)
	Get the monitoring profile for a data pool item.
virtual RecoveryAction *	getRecoveryAction (TD_DataPoolId id)
	Get the recovery action for a data pool item.
virtual TD_DataPoolId	firstIdentifier (void)
	Iteration method that resets the iteration and returns the lowest indentifier of the items in the data pool.
virtual TD_DataPoolId	nextIdentifier (void)
	Iteration method that returns the next identifier in an iteration.
virtual bool	isLastIdentifier (void)
	Iteration method that checks whether an iteration is finished.
virtual bool	isFloat (TD_DataPoolId id)
	Method implementing the type checking service to check whether a data pool item is real-valued.
virtual bool	isInteger (TD_DataPoolId id)
	Method implementing the type checking service to check whether a data pool item is integer-typed.
virtual void	reset (void)
	Implement the data pool reset service.

---

Member Function Documentation

TD_DataPoolId DataPool::firstIdentifier (  void   )  [virtual]

Iteration method that resets the iteration and returns the lowest indentifier of the items in the data pool. This method is used in conjunction with the other two iteration methods nextIdentifier and isLastIdentifier. These three methods are typically used in a for-loop as follows: for (unsigned int i=firstIdentifier(); !isLastIdentifier(); i=nextIdentifier()) ... // process i-th item in the data pool The conceptual model behind the iteration methods is as follows. The data pool maintains an internal iteration pointer. During an iteration, this pointer scans all the items in the data pool in sequence. When method firstIdentifier is called, the pointer is reset to point to the lowest valued identifier in the data pool. Each call to method nextIdentifier causes this pointer to switch to the next higher valid identifier in the data pool. Users can check the progress of the iteration by calling method isLastIdentifier which returns false if (and only if) the pointer is positioned on the highest valued identifier in the data pool. This class provides a default implementation that always returns zero. Note that the value of zero is not a legal identifier. This default implementation is useful for the case where a data pool is unable or unwilling to provide a meaningful implementation for the iteration services. See also: nextIdentifier isLastIdentifier Returns: the identifier of the first data pool item in the iteration Reimplemented in DC_SampleFullDataPool, and DC_SampleMonitoredDataPool. Definition at line 51 of file DataPool.cpp.

DC_DataItem * DataPool::getDataItem (  TD_DataPoolId  id  )  [virtual]

Getter method for a data item that encapsulates a data pool item. This method implements the data item link mechanism. This class provides a default implementation that returns a data item that encapsulates an internal variable of type "unsigned integer" and with a constant value of zero. This default implementation is useful for subclasses that do not wish to implement a data item link mechanism. See also: DC_DataItem Parameters: id  the data identifier of the data pool item to be read Returns: the DC_DataItem item encapsulating the data pool item with identifier id Reimplemented in DC_SampleFullDataPool, and DC_SampleMonitoredDataPool. Definition at line 27 of file DataPool.cpp.

virtual TD_Float DataPool::getFloatValue (  TD_DataPoolId  id  )  [pure virtual]

Getter method for the value of a real-typed data pool item. This method implements the copy link mechanism for real-valued data. Parameters: id  the data identifier of the data pool item to be read Returns: the value of the data with identifier id Implemented in DC_BasicDataPool, DC_SampleFullDataPool, and DC_SampleMonitoredDataPool.

virtual TD_Integer DataPool::getIntegerValue (  TD_DataPoolId  id  )  [pure virtual]

Getter method for the value of an integer-typed data pool item. This method implements the copy link mechanism for integer-valued data. Parameters: id  the data identifier of the data pool item to be read Returns: the value of the data with identifier id Implemented in DC_BasicDataPool, DC_SampleFullDataPool, and DC_SampleMonitoredDataPool.

MonitoringProfile * DataPool::getMonitoringProfile (  TD_DataPoolId  id  )  [virtual]

Get the monitoring profile for a data pool item. This class provides a default implementation that returns the same dummy monitoring profile (an instance of DC_NullMonitoringProfile) for all values of the parameter identifier. Note that this class does not define any setter method for the monitoring profile. This is because different implementations may have different policies for defining the monitoring profiles. In a typical case, to each data pool item a particular and fixed monitoring profile is associated. In this case, the data pool class would offer a setter method for the monitoring profile. In another typical case, the monitoring profiles are mode-dependent: the association between a particular data pool item and its monitoring profile is a function of the operational mode. In that case, the monitoring profiles are dynamically loaded by a mode manager and the data pool class only exposes a a setter method for this mode manager. Parameters: id  the identifier of the data pool item Returns: the monitoring profile Reimplemented in DC_SampleFullDataPool, and DC_SampleMonitoredDataPool. Definition at line 43 of file DataPool.cpp.

virtual TD_Float* DataPool::getPointerFloatValue (  TD_DataPoolId  id  )  [pure virtual]

Getter method for the pointer to a real-typed data pool item. This method implements the pointer link mechanism for real-typed data. Parameters: id  the data identifier of the data pool item to be read Returns: the pointer to the data with identifier id Implemented in DC_BasicDataPool, DC_SampleFullDataPool, and DC_SampleMonitoredDataPool.

virtual TD_Integer* DataPool::getPointerIntegerValue (  TD_DataPoolId  id  )  [pure virtual]

Getter method for the pointer to an integer-typed data pool item. This method implements the pointer link mechanism for integer-typed data. Parameters: id  the data identifier of the data pool item to be read Returns: the pointer to the data with identifier id Implemented in DC_BasicDataPool, DC_SampleFullDataPool, and DC_SampleMonitoredDataPool.

RecoveryAction * DataPool::getRecoveryAction (  TD_DataPoolId  id  )  [virtual]

Get the recovery action for a data pool item. This class provides a default implementation that returns the same dummy recovery action (an instance of DC_NullRecoveryAction) for all values of the parameter identifier. Note that this class does not define any setter method for the recovery action. This is because different implementations may have different policies for defining the recovery actions. In a typical case, to each data pool item a particular and fixed recovery action is associated. In this case, the data pool class would offer a setter method for the recovery action. In another typical case, the recovery actions are mode-dependent: the association between a particular data pool item and its recovery action is a function of the operational mode. In that case, the recovery actions are dynamically loaded by a mode manager and the data pool class only exposes a a setter method for this mode manager. Parameters: id  the identifier of the data pool item Returns: the recovery action Reimplemented in DC_SampleFullDataPool. Definition at line 47 of file DataPool.cpp.

TD_ObsTime DataPool::getTimeStamp (  TD_DataPoolId  id  )  [virtual]

Return the time stamp of a data pool item. The time stamp of a data pool item is normally set by the setter method when the item value is updated. This class provides a default implementation that always returns zero. Parameters: id  the data identifier of the data whose time stamp is sought Returns: the time stamp of the data with identifier id Reimplemented in DC_SampleFullDataPool. Definition at line 31 of file DataPool.cpp.

bool DataPool::isFloat (  TD_DataPoolId  id  )  [virtual]

Method implementing the type checking service to check whether a data pool item is real-valued. A real-value item is an item with a value whose syntactical type is TD_Float. This method returns true if the argument is the identifier of a data pool item that is real-typed. The method returns false if the identifier is either illegal (there is no item in the data pool that takes it as its identifier) or if the identifier identifies a an item that is integer-valued. This method is often used during an iteration to verify whether the data item being iterated upon is real-valued. This is important because it allows the client to decide which getter method to use to retrieve its value. Note that this class also offers a method to check whether a data pool item is integer-valued (method isInteger). Since a data item must be either real-valued or integer-valued, these two methods taken together allow a client to check whether to a particular identifier value there corresponds a data item or not. This class provides a default implementation that always returns true. This default implementation is useful for the case where a data pool is unable or unwilling to distinguish between real-valued and integer-valued items. See also: isInteger id the identifier of the data pool item Returns: true if the id is the identifier of a floating point data pool item, false otherwise Reimplemented in DC_SampleFullDataPool. Definition at line 63 of file DataPool.cpp.

bool DataPool::isInteger (  TD_DataPoolId  id  )  [virtual]

Method implementing the type checking service to check whether a data pool item is integer-typed. This method is the counterpart of method isFloat. This class provides a default implementation that always returns true. See also: isFloat id the identifier of the data pool item Returns: true if the id is the identifier of an integer data pool item, false otherwise Reimplemented in DC_SampleFullDataPool. Definition at line 67 of file DataPool.cpp.

bool DataPool::isLastIdentifier (  void   )  [virtual]

Iteration method that checks whether an iteration is finished. This method is used in conjunction with the other two iteration methods firstIdentifier and isLastIdentifier. It returns true when the iteration is finished. The iteration is finished if method nextIdentifier has been called N times since the last time method isFirstIdentifier was called where N is the number of items in the data pool This class provides a default implementation that always returns true. This default implementation is useful for the case where a data pool is unable or unwilling to provide a meaningful implementation for the iteration services. See also: nextIdentifier firstIdentifier Returns: true if the iteration has completed, false otherwise Reimplemented in DC_SampleFullDataPool, and DC_SampleMonitoredDataPool. Definition at line 59 of file DataPool.cpp.

bool DataPool::isValid (  TD_DataPoolId  id  )  [virtual]

Return the validity status of a data pool item. This class provides a default implementation that always returns "data valid". Parameters: id  the data identifier of the data pool item Returns: true if the data pool item is valid, false otherwise Reimplemented in DC_SampleFullDataPool, and DC_SampleMonitoredDataPool. Definition at line 35 of file DataPool.cpp.

TD_DataPoolId DataPool::nextIdentifier (  void   )  [virtual]

Iteration method that returns the next identifier in an iteration. This method is used in conjunction with the other two iteration methods firstIdentifier and isLastIdentifier. This method should only be called after having called method firstIdentifier and while method isLastIdentifier returns false. If these conditions do not hold, the return value of this method is undefined. This class provides a default implementation that always returns zero. Note that the value of zero is not a legal identifier. This default implementation is useful for the case where a data pool is unable or unwilling to provide a meaningful implementation for the iteration services. See also: firstIdentifier isLastIdentifier Returns: the identifier of the next data pool item in the iteration Reimplemented in DC_SampleFullDataPool, and DC_SampleMonitoredDataPool. Definition at line 55 of file DataPool.cpp.

void DataPool::reset (  void   )  [virtual]

Implement the data pool reset service. The validity status of all data pool item is reset to the value it had at the time the data pool component was created. This class provides a default implementation that returns without doing anything. See also: isValid Reimplemented in DC_SampleFullDataPool, and DC_SampleMonitoredDataPool. Definition at line 71 of file DataPool.cpp.

void DataPool::setValidityStatus (  TD_DataPoolId  id, bool  newValidityStatus )  [virtual]

Set the validity status of a data pool item. This class provides a default implementation that returns without taking any action. Parameters: id  the data identifier of the data pool item newValidityStatus  the new validity status Reimplemented in DC_SampleFullDataPool, and DC_SampleMonitoredDataPool. Definition at line 39 of file DataPool.cpp.

virtual void DataPool::setValue (  TD_DataPoolId  id, TD_Integer  newValue )  [pure virtual]

Setter method for the value of an integer-typed data pool item. Parameters: id  the data identifier of the data pool item to be set newValue  the new value to be set Implemented in DC_BasicDataPool, DC_SampleFullDataPool, and DC_SampleMonitoredDataPool.

virtual void DataPool::setValue (  TD_DataPoolId  id, TD_Float  newValue )  [pure virtual]

Setter method for the value of a real-typed data pool item. Parameters: id  the data identifier of the data pool item to be set newValue  the new value to be set Implemented in DC_BasicDataPool, DC_SampleFullDataPool, and DC_SampleMonitoredDataPool.

---

The documentation for this class was generated from the following files:

• DataPool.h
• DataPool.cpp

Copyright 2003 P&P Software GmbH - All Rights Reserved