G System: GWE::GXmlDataController Class Reference

Since the GXmlDataController also includes a network capabilities different elements are managed by different GWE Servers. To differentiate between elements that this server is responsible for and elements that other servers are managing, the concept of primary and secondary elements is introduced. All known elements are stored in the same storage, but the GXmlDataController keeps track of which elements are primary and which are secondary.

The difference in handling primary and secondary elements is that influences radiated from secondary elements are not transported to other GWE Servers while influences from primary elements are transported to every affected GWE Server.

Constructor & Destructor Documentation

GWE::GXmlDataController::GXmlDataController	(	GStorage *	storage,
		GXmlNetwork *	network,
		QObject *	parent = `0`
	)

Constructor.

Parameters:

master_server

should hold the network id of a server which is part of the already existing network, empty if this server is the first of the whole infrastructure.

GWE::GXmlDataController::~GXmlDataController ( ) [virtual]

Virtual Destructor.

Member Function Documentation

bool GWE::GXmlDataController::add ( GCS::GElement * ) [virtual, slot]

This method adds a primary element. An added element is open by default.

See also:: GDataController::add()

Implements GWE::GDataController.

void GWE::GXmlDataController::addSecondary	(	GCS::GElement *	element,
		QString	managing_server
	)			`[virtual, slot]`

This data controller differentiates between primary and secondary elements in order to know which are managed on this server and which elements are the responsibility of other GWE Servers.

An added secondary element is open by default after it is added.

Use this slot to insert a secondary element. The add() slot inserts a primary element.

Note:: if the element already exists, it is updated.

bool GWE::GXmlDataController::checkConsistency ( bool & ok ) [virtual, slot]

Checks complete storage consistency. The return value is stored in the ok parameter.

Parameters:

the return value is stored here as well.

Returns:: TRUE when storage is fully consistent, otherwise FALSE.

void GWE::GXmlDataController::checkElementsForSyndication ( ) [protected, virtual, slot]

Basically checks if there are elements that still need to be syndicated and syndicates them if enough time has elapsed since last syndication.

See also:: PendingSyndication

void GWE::GXmlDataController::checkFreeIDs ( ) [protected, virtual, slot]

Basically just checks the amount of left IDs and eventually calls requestFreeIDs()

bool GWE::GXmlDataController::close ( const GCS::GElementID & ) [virtual, slot]

Closes given element.

Returns:: true when the specified element was found and closed;

See also:: open()

Implements GWE::GDataController.

QStringList GWE::GXmlDataController::getAllKnownElementOwners ( ) const

Returns:: all known servers assoziated with the stored elements, duplicates removed.

QStringList GWE::GXmlDataController::getAllKnownServers ( ) const

Returns:: all registered servers, including the master server without duplicated entries; QString::null on failure.

QList< GCS::GElementID > GWE::GXmlDataController::getChildren ( const GCS::GElementID & parent ) const [virtual]

Returns:: the IDs of the children of given element.

Implements GCS::GWorldData.

QList< GCS::GElementID > GWE::GXmlDataController::getListOfAllElements ( ) [virtual]

Returns:: a list with all IDs of all stored elements.

Implements GWE::GDataController.

QList< GCS::GElementID > GWE::GXmlDataController::getListOfOpenElements ( ) [virtual]

Returns:: a list with IDs of all open elements.

Implements GWE::GDataController.

QString GWE::GXmlDataController::getManagingServerOfElement ( const GCS::GElementID & ) const

This method uses the ElementServerMapping.

Returns:: the server, if known, of the given Element ID, otherwise QString::null.

QString GWE::GXmlDataController::getMasterServer ( ) const

Returns:: name of the master server

GCS::GElement * GWE::GXmlDataController::getOpenElement ( const GCS::GElementID & ) [virtual]

Get an already opened element. The element must previously have been opened with open(), otherwise NULL is returned.

Returns:: a currently open element with given ID or NULL if element is not opened.

Implements GWE::GDataController.

bool GWE::GXmlDataController::isMasterServer ( )

Returns:: true if this GWE Server is the master server of a network.

bool GWE::GXmlDataController::isPrimaryElement ( const GCS::GElementID & ) const [virtual]

Returns:: true if the managing server of given element is this server.

See also:: getManagingServerOfElement()

Reimplemented from GWE::GDataController.

bool GWE::GXmlDataController::isRegisteredWithMaster ( ) const

Use this to check whether the GXmlDataController is fully operational. This is the case when a network connection to the server is available.

Todo:: introduce a report infrastructure for the GWE

Returns:: true when a working connection to the master server is available

void GWE::GXmlDataController::moveElement	(	const GCS::GElementID &	id,
		QString	new_owner
	)			`[virtual, slot]`

Moves given element which must be a primary element on this server to the new server.

Todo:: properly implement and mabe(!) use from proccessChildCreation()

GCS::GElement * GWE::GXmlDataController::open ( const GCS::GElementID & ) [virtual]

Open an element for general purposes (e.g. executing the agents,...)

Note:: Every element should only be opened once.

Returns:: NULL if element does not exist or is already opened.

See also:: close()

Implements GWE::GDataController.

bool GWE::GXmlDataController::postDelete ( const GCS::GElementID & id ) [virtual, slot]

Note:: when syndication of delete event is implemented, make sure that moving still works correctly!!!

Implements GWE::GDataController.

void GWE::GXmlDataController::postSyndication ( const GCS::GElementID & id ) [protected, virtual, slot]

Adds given element to list of pending syndications.

See also:: PendingSyndication

void GWE::GXmlDataController::prepareOpenedElement ( GCS::GElement * element ) [protected, virtual, slot]

Called for every opened element, connects some signals and slots, registers the element in the OpenElements map.

void GWE::GXmlDataController::processActionPerformed	(	const QString &	action,
		QStringList	params,
		const QString &	agent
	)			`[protected, virtual, slot]`

When an action is performed in an element, the GCS::GElement::actionPerformed() signal is emitted. This signal is connected to this slot and if the element is a secondary element on this server, the action is forwarded to the managing server of the element.

The protocol is somewhat like this (agent attr is optional, any number of params): <action name="actionname" element="elementid" agent="agentname"> string

string

</action>

void GWE::GXmlDataController::processChildCreation ( GCS::GElement * element ) [protected, virtual, slot]

Called when an element creates a new child. It inserts the newly created element either as primary element if the creator is a primary element on this server or as secondary element if the creator is a secondary element.

void GWE::GXmlDataController::processInfluencing ( const GCS::GElementInfluence & influence ) [protected, virtual, slot]

When an element is influenced and this server is not the managing server of the affected element the influence is transported to the managing server.

This slot is usually connected to the influenceReceived() signal from elements.

void GWE::GXmlDataController::processUnregister ( const QString & server ) [protected, virtual, slot]

Unregisters given server from this server and does all required postprocessing such an event requires.

const GCS::GElement * GWE::GXmlDataController::read ( const GCS::GElementID & id ) const [virtual]

Todo:: memory leaks! difference between returning an open element and creating one from DB

Implements GCS::GWorldData.

void GWE::GXmlDataController::receiveData	(	QDomElement	data,
		const QString &	sender
	)			`[virtual, slot]`

Connected to the XML network for receiving data. This implements the XML protocol used for GWE communication.

void GWE::GXmlDataController::registerWithMaster ( ) [protected, virtual, slot]

Registers this GWE Server at the master GWE Server, usually after a successfull network initialization.

void GWE::GXmlDataController::requestFreeIDs ( unsigned long amount ) [protected, virtual, slot]

Generates a requestfreeids message and sends it to the master server.

void GWE::GXmlDataController::sendFreeIDs	(	QString	server,
		unsigned long	amount
	)			`[protected, virtual, slot]`

Sends given amount of free GElementIDs to given server.

void GWE::GXmlDataController::sendUserMessage	(	QString	message,
		QString	destination
	)			`[slot]`

Sends a user message to given destination.

See also:: userMessageReceived()

void GWE::GXmlDataController::serverPresenceChanged	(	QString	server,
		bool	available,
		bool	internal
	)			`[signal]`

Emitted when a server presence state changes. This signal is used even when a server changes from external to internal state, which happens when registering - it first gets available as an external server, then registers and becomes an internal server.

Parameters:

internal

is true when the server is inside the G Universe

void GWE::GXmlDataController::shutdown ( ) [protected, virtual, slot]

Called when the application exits, properly unregisters from master server and shuts down network connection.

Implements GWE::GDataController.

void GWE::GXmlDataController::syndicateAllElementDataToServer ( const QString & server ) [protected, virtual, slot]

Propagates all known element data to given server. This is useful for servers that just get online for example.

void GWE::GXmlDataController::syndicateElementData ( const GCS::GElementID & id ) [protected, virtual, slot]

Forces propagation of element data to the master server and all child servers.

Element data is not propagated to the owner (managing server) of given element.

Todo:: this contains code crucial to multi-level hierarchies, search for todos in implementation

void GWE::GXmlDataController::syndicateElementDataToServer	(	const GCS::GElementID &	id,
		const QString &	server
	)			`[protected, virtual, slot]`

Propagates given element to given server.

void GWE::GXmlDataController::syndicateGenericMessage	(	QDomElement	data,
		bool	to_master = `false`,
		QString	exclude = `QString()`
	)			`[protected, virtual, slot]`

Can be used to syndicate data to all known servers, optionally also to the master server and with the possibility to exclude a certain server.

Todo:: implement

void GWE::GXmlDataController::unregisterFromAllKnownServers ( ) [protected, virtual, slot]

Sends an unregister message to all known servers, including the master server.

void GWE::GXmlDataController::unregisterFromMaster ( ) [protected, virtual, slot]

This actually sends an unregister message to the master server, it is automatically called when the application is about to quit.

void GWE::GXmlDataController::updateServerPresence	(	QString	server,
		bool	available
	)			`[protected, virtual, slot]`

Updates server presence. Usually connected to presenceChanged() signals from XML Network.

void GWE::GXmlDataController::userMessageReceived	(	QString	message,
		QString	sender,
		bool	internal
	)			`[signal]`

Emitted when a user message (a "pure" XMPP message tag with text content) is received, this can be used in the user interface of a client for example.

Parameters:

internal

is true when the message comes from inside the G Universe

bool GWE::GXmlDataController::writeOpenElementToStorage ( const GCS::GElementID & ) [virtual, slot]

Forces a full backup of specified element. This is useful when some changes were made to an open element and the complete element should be written back to the storage.

Implements GWE::GDataController.

Member Data Documentation

QMap<GCS::GElementID,QDateTime> GWE::GXmlDataController::LastSyndicationTime [protected]

Holds the values of last propagations of elements. This is used to avoid resending frequently changing elements too often. This is used for "general syndication to all known servers".

See also:: syndicateElementData(), PendingSyndication

GXmlNetwork* GWE::GXmlDataController::Network [protected]

The GXmlDataController class is able to handle distributed world management.

For the communication between all GWE Server instances, a network class is used.

QMap<GCS::GElementID,GCS::GElement*> GWE::GXmlDataController::OpenElements [protected]

Includes all open elements.

QList<GCS::GElementID> GWE::GXmlDataController::PendingSyndication [protected]

Holds all elements that will be syndicated, but are delayed because of too frequent syndication requests. This is used for "general syndication to all known servers".

See also:: syndicateElementData(), processAgentChanged(), postSyndication(), LastSyndicationTime

GCoreXmlSerializer* GWE::GXmlDataController::Serializer [protected]

The serializer is used to actually convert all data between C++ objects and XML documents

GStorage* GWE::GXmlDataController::Storage [protected]

The storage that is used by the data controller, most likely a database backend.


Public Slots
virtual bool	add (GCS::GElement *)
virtual bool	writeOpenElementToStorage (const GCS::GElementID &)
virtual bool	close (const GCS::GElementID &)
virtual bool	postDelete (const GCS::GElementID &)
virtual void	receiveData (QDomElement data, const QString &sender)
virtual void	addSecondary (GCS::GElement *element, QString managing_server)
virtual void	moveElement (const GCS::GElementID &id, QString new_owner)
virtual bool	checkConsistency (bool &ok)
void	sendUserMessage (QString message, QString destination)
Signals
void	userMessageReceived (QString message, QString sender, bool internal)
void	serverPresenceChanged (QString server, bool available, bool internal)
Public Member Functions
	GXmlDataController (GStorage storage, GXmlNetwork network, QObject *parent=0)
virtual	~GXmlDataController ()
virtual const GCS::GElement *	read (const GCS::GElementID &) const
virtual QList< GCS::GElementID >	getChildren (const GCS::GElementID &parent) const
virtual GCS::GElement *	open (const GCS::GElementID &)
virtual GCS::GElement *	getOpenElement (const GCS::GElementID &)
virtual QList< GCS::GElementID >	getListOfOpenElements ()
virtual QList< GCS::GElementID >	getListOfAllElements ()
virtual bool	isPrimaryElement (const GCS::GElementID &) const
bool	isMasterServer ()
QString	getMasterServer () const
bool	isRegisteredWithMaster () const
QString	getManagingServerOfElement (const GCS::GElementID &) const
QStringList	getAllKnownElementOwners () const
QStringList	getAllKnownServers () const
Protected Slots
virtual void	shutdown ()
virtual void	syndicateGenericMessage (QDomElement data, bool to_master=false, QString exclude=QString())
virtual void	registerWithMaster ()
virtual void	unregisterFromMaster ()
virtual void	unregisterFromAllKnownServers ()
virtual void	checkFreeIDs ()
virtual void	requestFreeIDs (unsigned long amount)
virtual void	sendFreeIDs (QString server, unsigned long amount)
virtual void	postSyndication (const GCS::GElementID &id)
virtual void	checkElementsForSyndication ()
virtual void	syndicateElementDataToServer (const GCS::GElementID &id, const QString &server)
virtual void	syndicateElementData (const GCS::GElementID &id)
virtual void	syndicateAllElementDataToServer (const QString &server)
virtual void	updateServerPresence (QString server, bool available)
virtual void	prepareOpenedElement (GCS::GElement *element)
virtual void	processChildCreation (GCS::GElement *element)
virtual void	processInfluencing (const GCS::GElementInfluence &influence)
virtual void	processActionPerformed (const QString &action, QStringList params, const QString &agent)
virtual void	processUnregister (const QString &server)
Protected Attributes
GCoreXmlSerializer *	Serializer
GStorage *	Storage
GXmlNetwork *	Network
QMap< GCS::GElementID, GCS::GElement * >	OpenElements
QMap< GCS::GElementID, QDateTime >	LastSyndicationTime
QList< GCS::GElementID >	PendingSyndication

GWE::GXmlDataController Class Reference

Public Slots

Signals

Public Member Functions

Protected Slots

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation