The ObserverRelationalTable class is a data structure which stores relational data about an observer tree. More...

#include <ObserverRelationalTable.h>

Inheritance diagram for Qtilities::Core::ObserverRelationalTable:

Public Member Functions
bool	compare (ObserverRelationalTable table)
	Compares this table with another relational table. Returns true if they match, false otherwise.
int	count () const
	Returns the number of entries in the table.
void	dumpTableInfo () const
	Prints the table information to the debug output.
RelationalTableEntry *	entryAt (int index)
	Returns the entry at position index.
RelationalTableEntry *	entryAt (int index) const
	Returns the entry at position index.
RelationalTableEntry *	entryWithPreviousSessionID (int session_id) const
	Returns the entry with the given previous session ID.
RelationalTableEntry *	entryWithSessionID (int session_id) const
	Returns the entry with the given session ID.
RelationalTableEntry *	entryWithVisitorID (int visitor_id) const
	Returns the entry with the given visitor ID.
IExportable::ExportResultFlags	exportBinary (QDataStream &stream) const
	Allows exporting to a QDataStream.
IExportable::ExportResultFlags	exportXml (QDomDocument doc, QDomElement object_node) const
	Allows exporting to an XML document. A reference to the QDomElement to which the object's information must be added is provided, along with a reference to the QDomDocument.
IExportable::ExportResultFlags	importBinary (QDataStream &stream, QList< QPointer< QObject > > &import_list)
	Allows importing and reconstruction of the object state from information provided in a QDataStream.
IExportable::ExportResultFlags	importXml (QDomDocument doc, QDomElement object_node, QList< QPointer< QObject > > &import_list)
	Allows importing and reconstruction of data from information provided in a XML document. A reference to the QDomElement which contains the object's information is provided, along with a reference to the QDomDocument.
QObject *	objectBase ()
const QObject *	objectBase () const
	ObserverRelationalTable (Observer *observer, bool exportable_subjects_only=false)
	Constructs an observer relational table for the given observer.
	ObserverRelationalTable (const ObserverRelationalTable &other)
	Copy constructor.
	ObserverRelationalTable ()
	Empty constructor. Only use this constructor when you populate the table using a data stream.
QMap< int, int >	parentsToObserverIDs (RelationalTableEntry *entry) const
	Takes the parents() of an entry and converts them to their equavalent list of observerIDs.
void	refresh ()
	Function to refresh the table after the observer changed.
IExportable::ExportModeFlags	supportedFormats () const
	Provides information about the export format(s) supported by your implementation of IExportable.
Public Member Functions inherited from Qtilities::Core::Interfaces::IExportable
quint32	applicationExportVersion () const
	Returns the application export version currently used by all your application's classes.
virtual void	clearExportTask ()
	Clears the export task.
IExportable *	duplicate (QString error_msg=0, int properties_to_copy=0, ExportResultFlags result_flags=0) const
	Function which will create a duplicate (copy) of this object.
virtual ITask *	exportTask () const
	Gets the task which must be used to log import/export information to.
Qtilities::ExportVersion	exportVersion () const
	Returns the export version currently used by all Qtilities classes.
virtual InstanceFactoryInfo	instanceFactoryInfo () const
	The instance factory information which must be used when the exported object is reconstructed during an import.
bool	isExportable () const
	Gets if this object must be part of it's parents' exports.
virtual void	setApplicationExportVersion (quint32 version)
	Sets the application export version currently used by all your application's classes.
virtual void	setExportTask (ITask *task)
	Sets the task which must be used to log import/export information to.
virtual void	setExportVersion (Qtilities::ExportVersion version)
	Returns the export version currently used by all Qtilities classes.
virtual void	setIsExportable (bool new_is_exportable)
	Sets if this object must be part of it's parents' exports.
Public Member Functions inherited from Qtilities::Core::Interfaces::IObjectBase
QString	objectOriginID () const
	Allows interfaces to provide some sort of source identification.
void	setObjectOriginID (const QString &object_origin_id)
	Allows setting of the object source ID of this interface implementation.

Static Public Member Functions
static int	getVisitorID (QObject *obj)
	Gets the visitor ID of an object. Returns -1 if no visitor ID exists.
static void	removeRelationalProperties (Observer *observer)
	Function to remove all visitorID properties in the specified hierarchy.
Static Public Member Functions inherited from Qtilities::Core::Interfaces::IExportable
template<typename T >
static T *	duplicateInstance (IExportable obj, QString error_msg=0, int properties_to_copy=0, ExportResultFlags *result_flags=0)
	Provides an easy to use template based implementation of IExportable::duplicate().
static QString	exportModeToString (ExportMode export_mode)
	Function which returns a string associated with a specific ExportMode.
static ExportMode	stringToExportMode (const QString &export_mode_string)
	Function which returns the ExportMode associated with a string.
static Result	validateQtilitiesExportVersion (Qtilities::ExportVersion export_version, ITask *task=0)
	Checks the exportVersion() against the supported Qtilities export versions for the current Qtilities version.
static Result	validateQtilitiesImportVersion (Qtilities::ExportVersion import_version, ITask *task=0)
	Checks the exportVersion() against the supported Qtilities import versions for the current Qtilities version.

Friends
class	Qtilities::Core::ObserverData

Additional Inherited Members
Public Types inherited from Qtilities::Core::Interfaces::IExportable
enum	ExportMode { None = 0, Binary = 1, XML = 2 }
	Possible export modes that an implementation of IExportable can support. More...
enum	Result { Complete = 0, Incomplete = 1, Failed = 2, FailedContinue = 4, VersionTooNew = 8, VersionTooOld = 16, VersionSupported = 32, SuccessResult = Complete \| Incomplete \| VersionSupported, FailedResult = Failed \| FailedContinue \| VersionTooNew \| VersionTooOld }
	The possible results of an export/import operation. More...

Detailed Description

The ObserverRelationalTable class is a data structure which stores relational data about an observer tree.

Using this table it is possible to store the relationships between objects in an observer tree. The relational table is constructed by providing a top level observer, or by providing an QDataStream object with information previously exported through the exportBinary() function.

For trees where all objects only occur once in the tree this process is simple and each object will only have one parent and any number of children. Where the table gets usefull is where an object occurs more than once in the tree. In these cases the table will keep track of all the places where the object is used.

The table support streaming data to and from QDataStream and is used whenever a binary export/import operation is performed on an observer object.

To construct a table is easy, for example:

TreeNode* rootNode = new TreeNode("Root");
TreeNode* parentNode1 = rootNode->addNode("Parent 1");
TreeNode* parentNode2 = rootNode->addNode("Parent 2");
parentNode1->addItem("Child 1");
parentNode1->addItem("Child 2");
parentNode2->addItem("Child 3");
parentNode2->addItem("Child 4");
TreeItem* item = parentNode2->addItem("Child 5");
parentNode1->addItem(item);
// Construct relational table:
ObserverRelationalTable table(rootNode);

The table now contains all relational information about the tree underneath rootNode. Note that when an item occurs more than once in the tree (such as "Child 1" in the above tree), it will only occur once in the table. The number of items in the table can be found using the count() function and items can be accessed through the entryAt() function. Each entry in the table is a Qtilities::Core::RelationalTableEntry object which contains information about the parents and children of the entry among other information.

All entries in the table has an unique visitor ID which is assigned to each object in the tree by adding the Qtilities::Core::Properties::qti_prop_VISITOR_ID shared property (Qtilities::Core::SharedProperty) on each item. This unique ID is the most important field in each entry since the parents and children of the entry are defined using their respective visitor IDs. As soon as the ObserverRelationalTable is deleted the visitor ID properties on all object will be removed. Thus it is very important not to create multiple ObserverRelationalTable objects on the same observer at the same time. The class provides functions such as entryWithVisitorID() etc. to easily find items with different parameters.

The following is an example where we loop through the table constructed in the above example. This functionality is provided by the dumpTableInfo() function.

for (int i = 0; i < table.count(); i++) {
    RelationalTableEntry* entry = table.entryAt(i);
    LOG_INFO(QString("Table Entry %1 START:").arg(i));
    LOG_INFO("-------------------------------------");
    LOG_INFO(QString("Name:                   %1").arg(entry->d_name));
    LOG_INFO(QString("Visitor ID:             %1").arg(entry->d_visitorID));
    LOG_INFO(QString("Session ID:             %1").arg(entry->d_sessionID));
    LOG_INFO(QString("Previous Session ID:    %1").arg(entry->d_previousSessionID));
    LOG_INFO(QString("Owner Visitor ID:       %1").arg(entry->d_parentVisitorID));
    LOG_INFO(QString("Child count:            %1").arg(entry->d_children.count()));
    for (int c = 0; c < entry->d_children.count(); c++) {
        RelationalTableEntry* child = table.entryWithVisitorID(entry->d_children.at(c));
        LOG_INFO(QString("> Child No.   %1").arg(c));
        LOG_INFO(QString("> Name        %1").arg(child->d_name));
        LOG_INFO(QString("> Visitor ID  %1").arg(child->d_visitorID));
        LOG_INFO(QString("> Ownership   %1").arg(child->d_ownership));
    }
    LOG_INFO(QString("Parent count: %1")).arg(entry->d_parents.count()));
    for (int c = 0; c < entry->d_parents.count(); c++) {
        RelationalTableEntry* parent = table.entryWithVisitorID(entry->d_parents.at(c));
        LOG_INFO(QString("> Parent No.  %1").arg(c));
        LOG_INFO(QString("> Name        %1").arg(parent->d_name));
        LOG_INFO(QString("> Visitor ID  %1").arg(parent->d_visitorID));
    }
    LOG_INFO("-------------------------------------");
    LOG_INFO(QString("Table Entry %1 END:").arg(i));
    LOG_INFO("-------------------------------------");
}

As the above example shows, it is very easy to access the information about all the relationships of items in the tree. The ObserverRelationalTable class allows developers to easily build classes using the tree's relationships around it. The Qtilities::Core::ObserverDotWriter is an example of such a class.

Another powerfull feature of the ObserverRelationalTable class is its functionality to compare two ObserverRelationalTable objects with each other using the compare() method or the overloaded == and != operators.

Constructor & Destructor Documentation

Qtilities::Core::ObserverRelationalTable::ObserverRelationalTable	(	Observer *	observer,
		bool	exportable_subjects_only = `false`
	)

Constructs an observer relational table for the given observer.

Parameters:

observer	The observer to construct the table for.
exportable_subjects_only	When true, only exportable subjects (object implementing Qtilities::Core::Interfaces::IExportable) are added to the table. Otherwise all objects are added. This is usefull when the table is used to verify observer exports.

Qtilities::Core::ObserverRelationalTable::ObserverRelationalTable ( )

Empty constructor. Only use this constructor when you populate the table using a data stream.

For example:

                QDataStream test_stream_in(&test_file);    // read the data serialized from the file
                ObserverRelationalTable readback_table;
                readback_table.importBinary(test_stream_in);

Member Function Documentation

bool Qtilities::Core::ObserverRelationalTable::compare ( ObserverRelationalTable table )

Compares this table with another relational table. Returns true if they match, false otherwise.

Note that for compare to return true, the tables must match completely. That is, the number of entries in the tables must be the same and each entry must be exactly the same (except for d_sessionID and d_previousSessionID).

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::ObserverRelationalTable::exportBinary ( QDataStream & stream ) const

virtual

Allows exporting to a QDataStream.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Parameters:

stream A reference to the QDataStream to which the object's information must be appended is provided.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::ObserverRelationalTable::exportXml	(	QDomDocument *	doc,
		QDomElement *	object_node
	)		const

virtual

Allows exporting to an XML document. A reference to the QDomElement to which the object's information must be added is provided, along with a reference to the QDomDocument.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::ObserverRelationalTable::importBinary	(	QDataStream &	stream,
		QList< QPointer< QObject > > &	import_list
	)

virtual

Allows importing and reconstruction of the object state from information provided in a QDataStream.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Parameters:

stream	The QDataStream which contains the object's information.
import_list	All objects constructed during the import operation must be added to the import list. When the operation fails, all objects in this list will be deleted.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Qtilities::Core::Interfaces::IExportable::ExportResultFlags Qtilities::Core::ObserverRelationalTable::importXml	(	QDomDocument *	doc,
		QDomElement *	object_node,
		QList< QPointer< QObject > > &	import_list
	)

virtual

Allows importing and reconstruction of data from information provided in a XML document. A reference to the QDomElement which contains the object's information is provided, along with a reference to the QDomDocument.

See Serializing Qtilities Data Types Overview for more information about the expected output format.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

QObject* Qtilities::Core::ObserverRelationalTable::objectBase ( )

inlinevirtual

Note:: MultiContextProperty is not a QObject, thus it returns 0.

Implements Qtilities::Core::Interfaces::IObjectBase.

const QObject* Qtilities::Core::ObserverRelationalTable::objectBase ( ) const

inlinevirtual

Note:: MultiContextProperty is not a QObject, thus it returns 0.

Implements Qtilities::Core::Interfaces::IObjectBase.

QMap< int, int > Qtilities::Core::ObserverRelationalTable::parentsToObserverIDs ( RelationalTableEntry * entry ) const

Takes the parents() of an entry and converts them to their equavalent list of observerIDs.

Returns:: A map with keys being the parent visitor IDs and the repective values being the observerIDs.

Note:: If ALL of the parents cannot be converted to equavalent observer IDs, an empty map is returned.

void Qtilities::Core::ObserverRelationalTable::refresh ( )

Function to refresh the table after the observer changed.

When the observer changed you must call refresh manually.

Qtilities::Core::Interfaces::IExportable::ExportModeFlags Qtilities::Core::ObserverRelationalTable::supportedFormats ( ) const

virtual

Provides information about the export format(s) supported by your implementation of IExportable.

Note:: It is important to note that you need to check the exportVersion() when you return the supported formats.

Reimplemented from Qtilities::Core::Interfaces::IExportable.

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation